docs: 清理过时文档,新增首页API契约并更新相关内容
- 删除backend-plan.md、backend-api-service.md等多份过时项目文档 - 新增home-api.md规范首页三类内容的Admin API补充契约 - 更新docs/README.md的文档清单与展示格式 - 优化integration-workflow.md、admin-api-requirements.md等文档的表格与内容 - 为WonderQ-MiniAPP的homeExperienceData.ts新增API适配类型与归一化函数
This commit is contained in:
@@ -1,133 +0,0 @@
|
||||
# 页面模块配置 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` 和本文档。
|
||||
Reference in New Issue
Block a user