548f91c37f
- 移除后端产品、目的地、活动专题等废弃模块的数据库表与业务代码，删除冗余API接口 - 删除小程序端详情页、线路组件等冗余代码，移除搜索工具与测试用例，调整导航逻辑 - 清理管理端废弃的类型定义、编辑器与测试代码 - 更新项目文档，修正模块维护说明与接口文档内容
134 lines
3.3 KiB
Markdown
134 lines
3.3 KiB
Markdown
# 页面模块配置 Admin API 契约
|
||
|
||
本文档约束 `WonderQ-Admin-UI` 对站点结构模块的 CRUD、排序和字段白名单。
|
||
|
||
## 适用模块
|
||
|
||
| 模块 | 用途 |
|
||
| --- | --- |
|
||
| `heroSlides` | 首页顶部轮播 |
|
||
| `destinationHero` | 目的地页主视觉 |
|
||
| `demandHero` | 需求页主视觉 |
|
||
| `demandFeatureCards` | 需求页能力卡片 |
|
||
| `demandForm` | 需求提交表单 |
|
||
| `vehicleOptions` | 万趣用车卡片 |
|
||
|
||
## 通用规则
|
||
|
||
- 路径：`/api/admin/site-config/{module}`。
|
||
- 所有模块项都使用字符串 `id`；排序项使用整数 `sortOrder`。
|
||
- 创建、更新、删除和排序均需要后台 JWT。
|
||
- 后端只接受模块字段白名单，未知字段会被忽略。
|
||
- `demandForm` 是单例模块，重复创建返回 `409`。
|
||
- `demandForm` 不支持排序；其他模块支持排序。
|
||
- 所有变更写入审计日志，并在成功提交后返回最新模块项。
|
||
|
||
## 类型
|
||
|
||
```ts
|
||
type SiteModule =
|
||
| "heroSlides"
|
||
| "destinationHero"
|
||
| "demandHero"
|
||
| "demandFeatureCards"
|
||
| "demandForm"
|
||
| "vehicleOptions"
|
||
|
||
type SiteItemPatch = {
|
||
title?: string;
|
||
kicker?: string | null;
|
||
image?: string | null;
|
||
description?: string | null;
|
||
steps?: string[];
|
||
destinationLabel?: string;
|
||
destinationPlaceholder?: string | null;
|
||
phoneLabel?: string;
|
||
phonePlaceholder?: string | null;
|
||
noteLabel?: string;
|
||
notePlaceholder?: string | null;
|
||
submitLabel?: string;
|
||
chips?: string[];
|
||
targetType?: string | null;
|
||
targetValue?: string | null;
|
||
isActive?: boolean;
|
||
sortOrder?: number;
|
||
};
|
||
```
|
||
|
||
## 获取完整配置
|
||
|
||
### `GET /api/admin/site-config`
|
||
|
||
返回所有模块数组，包括停用项：
|
||
|
||
```ts
|
||
{
|
||
heroSlides: unknown[];
|
||
destinationHero: unknown[];
|
||
demandHero: unknown[];
|
||
demandFeatureCards: unknown[];
|
||
demandForm: unknown[];
|
||
vehicleOptions: unknown[];
|
||
}
|
||
```
|
||
|
||
空模块必须返回 `[]`，不能返回 `null` 或省略字段。
|
||
|
||
## CRUD
|
||
|
||
### 新增
|
||
|
||
```http
|
||
POST /api/admin/site-config/{module}
|
||
Authorization: Bearer <admin-jwt>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
请求体使用 `SiteItemPatch`。成功返回 `201` 和新建模块项。各模块的主字段如下：
|
||
|
||
| 模块 | 主字段 |
|
||
| --- | --- |
|
||
| `heroSlides` | `title` |
|
||
| `destinationHero` | `title` |
|
||
| `demandHero` | `title` |
|
||
| `demandFeatureCards` | `title` |
|
||
| `demandForm` | `submitLabel` |
|
||
| `vehicleOptions` | `title` |
|
||
|
||
缺少主字段返回 `422 MODULE_CONFIG_VALIDATION_ERROR`。模块不存在返回 `400 MODULE_CONFIG_FORBIDDEN`。
|
||
|
||
### 更新
|
||
|
||
```http
|
||
PATCH /api/admin/site-config/{module}/{id}
|
||
```
|
||
|
||
只更新该模块允许的字段；不存在的 ID 返回 `404 MODULE_CONFIG_NOT_FOUND`。
|
||
|
||
### 删除
|
||
|
||
```http
|
||
DELETE /api/admin/site-config/{module}/{id}
|
||
```
|
||
|
||
成功返回 `{ "id": "..." }`。删除后，排序模块会重新从 0 开始编号。
|
||
|
||
### 排序
|
||
|
||
```http
|
||
PATCH /api/admin/site-config/{module}/reorder
|
||
Content-Type: application/json
|
||
|
||
{ "itemIds": ["id-2", "id-1"] }
|
||
```
|
||
|
||
`itemIds` 必须刚好包含当前模块的全部 ID，且不能重复。否则返回 `400 MODULE_CONFIG_REORDER_INVALID`。不支持排序的模块返回 `400 MODULE_CONFIG_REORDER_UNSUPPORTED`。
|
||
|
||
## 模块字段补充
|
||
|
||
- `demandForm` 的 `chips` 会过滤空白值；表单只保留一条配置。
|
||
|
||
## 删除范围边界
|
||
|
||
模块配置只维护站点内容，不负责客户、线索或订单数据。接口变更必须同步 `src/api.ts`、`src/types/admin.ts` 和本文档。
|