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
@@ -8,6 +8,8 @@
|
||||
|
||||
详情展示内容的字段、图片、排序与商品领域隔离约束见 [detail-api.md](./detail-api.md)。该文档是本主契约的详情领域补充，适用端为 `WonderQ-Admin` 和 `WonderQ-Admin-UI`。
|
||||
|
||||
首页体验、团队共创和极境视界内容的字段、图片、排序与商品领域隔离约束见 [home-api.md](./home-api.md)。该文档是本主契约的首页内容补充，适用端为 `WonderQ-Admin` 和 `WonderQ-Admin-UI`。
|
||||
|
||||
## 通用约定
|
||||
|
||||
- API 前缀：`/api/admin`。
|
||||
@@ -18,22 +20,22 @@
|
||||
|
||||
## 接口清单
|
||||
|
||||
| 方法 | 路径 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| `POST` | `/api/admin/auth/login` | 后台登录 |
|
||||
| `GET` | `/api/admin/me` | 当前后台用户 |
|
||||
| `GET` | `/api/admin/dashboard` | 工作台统计和最近线索 |
|
||||
| `GET` | `/api/admin/site-config` | 获取全部站点配置 |
|
||||
| `POST` | `/api/admin/site-config/{module}` | 新增模块项 |
|
||||
| `PATCH` | `/api/admin/site-config/{module}/{id}` | 更新模块项 |
|
||||
| `DELETE` | `/api/admin/site-config/{module}/{id}` | 删除模块项 |
|
||||
| `PATCH` | `/api/admin/site-config/{module}/reorder` | 调整排序 |
|
||||
| `GET` | `/api/admin/leads` | 线索列表 |
|
||||
| `PATCH` | `/api/admin/leads/{id}/status` | 更新线索状态 |
|
||||
| `GET` | `/api/admin/media-assets` | 素材列表 |
|
||||
| `POST` | `/api/admin/media-assets/upload` | 上传图片 |
|
||||
| `POST` | `/api/admin/reset-guizhou-content` | 重置站点内容 |
|
||||
| `POST` | `/api/admin/publish` | 发布站点快照 |
|
||||
| 方法 | 路径 | 用途 |
|
||||
| -------- | ----------------------------------------- | -------------------- |
|
||||
| `POST` | `/api/admin/auth/login` | 后台登录 |
|
||||
| `GET` | `/api/admin/me` | 当前后台用户 |
|
||||
| `GET` | `/api/admin/dashboard` | 工作台统计和最近线索 |
|
||||
| `GET` | `/api/admin/site-config` | 获取全部站点配置 |
|
||||
| `POST` | `/api/admin/site-config/{module}` | 新增模块项 |
|
||||
| `PATCH` | `/api/admin/site-config/{module}/{id}` | 更新模块项 |
|
||||
| `DELETE` | `/api/admin/site-config/{module}/{id}` | 删除模块项 |
|
||||
| `PATCH` | `/api/admin/site-config/{module}/reorder` | 调整排序 |
|
||||
| `GET` | `/api/admin/leads` | 线索列表 |
|
||||
| `PATCH` | `/api/admin/leads/{id}/status` | 更新线索状态 |
|
||||
| `GET` | `/api/admin/media-assets` | 素材列表 |
|
||||
| `POST` | `/api/admin/media-assets/upload` | 上传图片 |
|
||||
| `POST` | `/api/admin/reset-guizhou-content` | 重置站点内容 |
|
||||
| `POST` | `/api/admin/publish` | 发布站点快照 |
|
||||
|
||||
## 站点模块
|
||||
|
||||
@@ -46,19 +48,19 @@ type SiteModule =
|
||||
| "demandHero"
|
||||
| "demandFeatureCards"
|
||||
| "demandForm"
|
||||
| "vehicleOptions"
|
||||
| "vehicleOptions";
|
||||
```
|
||||
|
||||
模块职责：
|
||||
|
||||
| 模块 | 主要字段 | 约束 |
|
||||
| --- | --- | --- |
|
||||
| `heroSlides` | `title`、`kicker`、`image`、`isActive`、`sortOrder` | 可新增、编辑、删除、排序 |
|
||||
| `destinationHero` | `title`、`kicker`、`image`、`isActive`、`sortOrder` | 可新增、编辑、删除、排序 |
|
||||
| `demandHero` | `title`、`kicker`、`description`、`steps`、`isActive`、`sortOrder` | 可新增、编辑、删除、排序 |
|
||||
| `demandFeatureCards` | `title`、`description`、`isActive`、`sortOrder` | 可新增、编辑、删除、排序 |
|
||||
| `demandForm` | 表单标签、占位文案、`chips`、`isActive` | 单例，不支持排序 |
|
||||
| `vehicleOptions` | `title`、`description`、`image`、`isActive`、`sortOrder` | 可新增、编辑、删除、排序 |
|
||||
| 模块 | 主要字段 | 约束 |
|
||||
| -------------------- | ------------------------------------------------------------------ | ------------------------ |
|
||||
| `heroSlides` | `title`、`kicker`、`image`、`isActive`、`sortOrder` | 可新增、编辑、删除、排序 |
|
||||
| `destinationHero` | `title`、`kicker`、`image`、`isActive`、`sortOrder` | 可新增、编辑、删除、排序 |
|
||||
| `demandHero` | `title`、`kicker`、`description`、`steps`、`isActive`、`sortOrder` | 可新增、编辑、删除、排序 |
|
||||
| `demandFeatureCards` | `title`、`description`、`isActive`、`sortOrder` | 可新增、编辑、删除、排序 |
|
||||
| `demandForm` | 表单标签、占位文案、`chips`、`isActive` | 单例，不支持排序 |
|
||||
| `vehicleOptions` | `title`、`description`、`image`、`isActive`、`sortOrder` | 可新增、编辑、删除、排序 |
|
||||
|
||||
`GET /api/admin/site-config` 返回以上全部模块，包含停用内容，空模块返回 `[]`。
|
||||
|
||||
@@ -74,43 +76,6 @@ type SiteModule =
|
||||
|
||||
成功响应包含 `token` 和 `{ id, email, name, role }`。
|
||||
|
||||
### 工作台统计
|
||||
|
||||
`GET /api/admin/dashboard` 返回：
|
||||
|
||||
```ts
|
||||
{
|
||||
stats: {
|
||||
newLeadCount: number;
|
||||
leadCount: number;
|
||||
};
|
||||
recentLeads: Lead[];
|
||||
}
|
||||
```
|
||||
|
||||
## 线索
|
||||
|
||||
### `GET /api/admin/leads`
|
||||
|
||||
Query 参数：`status`、`sourcePage`、`keyword`、`createdFrom`、`createdTo`、`take`。`take` 范围为 1-200，默认 100。关键词只搜索联系方式、目的地和备注。
|
||||
|
||||
### `PATCH /api/admin/leads/{id}/status`
|
||||
|
||||
请求：
|
||||
|
||||
```json
|
||||
{ "status": "contacted" }
|
||||
```
|
||||
|
||||
状态值：`new`、`assigned`、`contacted`、`planning`、`won`、`invalid`。
|
||||
|
||||
## 媒体与发布
|
||||
|
||||
- 图片上传字段为 multipart `file` 和 `group`。
|
||||
- 允许 JPG、PNG、WebP、GIF，单文件最大 5MB。
|
||||
- `POST /api/admin/publish` 保存当前启用内容快照并返回版本记录。
|
||||
- `POST /api/admin/reset-guizhou-content` 只重置站点内容模块，不创建已移除领域的数据。
|
||||
|
||||
## 兼容边界
|
||||
|
||||
- 当前 Admin UI 不应调用未列出的领域接口。
|
||||
|
||||
Reference in New Issue
Block a user