113 lines
7.6 KiB
Markdown
113 lines
7.6 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`。
|
||
- 所有持久化资源的 `id` 由后端生成稳定 UUID 字符串。Admin UI 必须保存并复用接口返回的 ID，不能根据标题、文案或数组下标自行拼接，也不能假设 ID 是可读 slug。
|
||
|
||
## 接口清单
|
||
|
||
| 方法 | 路径 | 用途 |
|
||
| -------- | ----------------------------------------- | -------------------- |
|
||
| `POST` | `/api/admin/auth/login` | 后台登录 |
|
||
| `POST` | `/api/admin/auth/refresh` | 使用 HttpOnly Cookie 刷新后台访问令牌 |
|
||
| `POST` | `/api/admin/auth/logout` | 撤销当前后台会话 |
|
||
| `GET` | `/api/admin/me` | 当前后台用户 |
|
||
| `GET` | `/api/admin/system/profile` | 当前用户、角色、权限码和动态菜单 |
|
||
| `GET/POST/PATCH` | `/api/admin/system/users` | 管理后台用户 |
|
||
| `GET/POST/PATCH` | `/api/admin/system/roles` | 管理角色和数据范围 |
|
||
| `GET/POST/PATCH` | `/api/admin/system/menus` | 管理目录、页面和按钮 |
|
||
| `GET/POST/PATCH` | `/api/admin/system/depts` | 管理部门 |
|
||
| `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"
|
||
| "vehicleService";
|
||
```
|
||
|
||
模块职责：
|
||
|
||
| 模块 | 主要字段 | 约束 |
|
||
| -------------------- | ------------------------------------------------------------------ | ------------------------ |
|
||
| `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` | 可新增、编辑、删除、排序 |
|
||
| `vehicleService` | `introTitle`、`intro`、`serviceSections`、`advantages`、`processSteps`、`isActive` | 单例，维护用车需求页说明 |
|
||
|
||
`GET /api/admin/site-config` 返回以上全部模块，包含停用内容，空模块返回 `[]`。
|
||
|
||
`vehicleService` 为单例配置，`serviceSections` 和 `processSteps` 的每项为 `{ title, description }`，`advantages` 为字符串数组。Admin UI 以每行一项编辑并在保存前去除空行。
|
||
|
||
## 用车需求线索
|
||
|
||
`GET /api/admin/leads?leadType=vehicle` 只返回用车线索，可叠加 `status`、`keyword` 和 `take` 筛选。用车线索的 `vehicleDemand` 保留服务类型、日期、地点、人数、行李和车型快照，运营端只负责查看和跟进，不提供车辆库存、排班、计价或订单操作。
|
||
|
||
`PATCH /api/admin/leads/{id}/status` 使用现有状态：`new`、`assigned`、`contacted`、`planning`、`won`、`invalid`。状态变更写入审计日志并返回更新后的线索对象。
|
||
|
||
## 登录与工作台
|
||
|
||
### 登录
|
||
|
||
`POST /api/admin/auth/login` 请求：
|
||
|
||
```json
|
||
{ "email": "admin@example.test", "password": "<password>" }
|
||
```
|
||
|
||
成功响应包裹为 `data: { token, accessToken, expiresIn, user: { id, email, name, role } }`。`token` 保留给过渡期 React 管理端，`accessToken` 为短时访问令牌；Refresh Token 只通过同域 HttpOnly Cookie 返回，不进入 JSON。
|
||
|
||
管理员登录、刷新和退出依赖 Redis 会话存储。Refresh Token 轮换后旧令牌立即失效；Redis 不可用时认证接口返回 `503`，不降级为无会话校验。
|
||
|
||
`/api/admin/system/profile` 返回 `roles`、`permissions`、`menus`、`dataScopes` 和 `deptIds`。菜单只返回启用且可见的目录/页面，按钮菜单保留在页面节点的 `children` 中；前端组件只能从预注册组件白名单加载 `component`。
|
||
|
||
角色数据范围使用以下五个编码：`all`（全部）、`dept`（当前部门）、`dept_and_children`（当前部门及子部门）、`custom_dept`（自定义部门）、`self`（本人）。运营资源通过 `deptId` 和 `createdById` 归属字段执行查询过滤；资源归属迁移完成前不得在生产环境切换非管理员角色。
|
||
|
||
登录按 IP 与账号组合执行 Redis 限流，默认 60 秒最多 5 次；权限菜单缓存默认 300 秒。Redis 故障不能放行权限检查，缓存不可用时只能重新读取数据库，认证会话和限流不可用时返回 `503`。
|
||
|
||
## 兼容边界
|
||
|
||
- 当前 Admin UI 不应调用未列出的领域接口。
|
||
- 站点配置字段必须与 `src/api.ts` 保持一致。
|
||
- 任何字段、模块或路径变化必须同步更新本文档和前端类型。
|