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:
duanshuwen
2026-08-18 20:00:25 +08:00
parent ca6f9397e0
commit cda8069630
11 changed files with 475 additions and 512 deletions

View File

@@ -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` 和本文档。