e082bd2d98
- 新增`api_response.py`统一响应封装工具类，提供标准成功/错误响应构造方法 - 重构WonderQ-Admin全局异常处理器，将所有异常转换为标准响应格式 - 修改所有公共和管理端接口的返回逻辑，统一使用`code`（与HTTP状态码一致）、`msg`和`data`的三层结构 - 新增`api-response-contract.md`文档，定义完整的三端统一JSON响应规范 - 更新所有领域API文档，明确业务数据需位于`data`字段内，补充响应格式说明 - 为WonderQ-MiniAPP和WonderQ-Admin-UI新增响应解析逻辑和类型定义，自动完成协议校验和错误处理 - 更新所有测试用例，适配新的响应结构确保接口符合契约要求 - 新增`module-config-api.md`模块配置API文档，补充站点模块配置的接口约定 - 更新项目README文档，调整文档分类顺序将响应契约置于首位
87 lines
4.7 KiB
Markdown
87 lines
4.7 KiB
Markdown
# WonderQ Admin API 接口需求
|
|
|
|
本文档描述 `WonderQ-Admin-UI` 当前使用的 Admin API。接口负责站点内容维护、素材、发布和需求线索管理。
|
|
|
|
玩法分类和路线管理的字段、嵌套路由、排序与删除约束见 [wanfa-api.md](./wanfa-api.md)。该文档是本主契约的玩法领域补充，适用端为 `WonderQ-Admin` 和 `WonderQ-Admin-UI`。
|
|
|
|
管家顾问资料管理的字段、图片、排序与删除约束见 [concierge-api.md](./concierge-api.md)。该文档是本主契约的管家领域补充，适用端为 `WonderQ-Admin` 和 `WonderQ-Admin-UI`。
|
|
|
|
详情展示内容的字段、图片、排序与商品领域隔离约束见 [detail-api.md](./detail-api.md)。该文档是本主契约的详情领域补充，适用端为 `WonderQ-Admin` 和 `WonderQ-Admin-UI`。
|
|
|
|
首页体验、团队共创和极境视界内容的字段、图片、排序与商品领域隔离约束见 [home-api.md](./home-api.md)。该文档是本主契约的首页内容补充，适用端为 `WonderQ-Admin` 和 `WonderQ-Admin-UI`。
|
|
|
|
所有 Admin JSON 接口遵循 [三端统一 API 响应契约](./api-response-contract.md)。
|
|
|
|
## 通用约定
|
|
|
|
- API 前缀：`/api/admin`。
|
|
- 除登录接口外均需 `Authorization: Bearer <admin-jwt>`。
|
|
- JSON 请求统一使用 camelCase 字段。
|
|
- 变更接口写入审计日志后再提交事务。
|
|
- 成功业务结果统一放在 `data`；创建成功为 HTTP/code `201`。
|
|
- 失败统一返回数字 `code`、用户可读 `msg`、`data: null`，业务错误码放在可选的 `errorCode`。
|
|
|
|
## 接口清单
|
|
|
|
| 方法 | 路径 | 用途 |
|
|
| -------- | ----------------------------------------- | -------------------- |
|
|
| `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` | 发布站点快照 |
|
|
|
|
## 站点模块
|
|
|
|
`SiteModule` 只允许以下值：
|
|
|
|
```ts
|
|
type SiteModule =
|
|
| "heroSlides"
|
|
| "destinationHero"
|
|
| "demandHero"
|
|
| "demandFeatureCards"
|
|
| "demandForm"
|
|
| "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` | 可新增、编辑、删除、排序 |
|
|
|
|
`GET /api/admin/site-config` 返回以上全部模块，包含停用内容，空模块返回 `[]`。
|
|
|
|
## 登录与工作台
|
|
|
|
### 登录
|
|
|
|
`POST /api/admin/auth/login` 请求：
|
|
|
|
```json
|
|
{ "email": "admin@example.test", "password": "<password>" }
|
|
```
|
|
|
|
成功响应包裹为 `data: { token, user: { id, email, name, role } }`；具体字段结构保持现有登录接口约定。
|
|
|
|
## 兼容边界
|
|
|
|
- 当前 Admin UI 不应调用未列出的领域接口。
|
|
- 站点配置字段必须与 `src/api.ts` 保持一致。
|
|
- 任何字段、模块或路径变化必须同步更新本文档和前端类型。
|