docs: 清理过时文档并更新管理端名称
删除home-api.md、team-building-api.md等废弃文档 统一替换所有文档中的`WonderQ-Admin-UI`为`WonderQ-Admin-UI-Vue` 更新README.md与联调文档的内容与路径 修正各API文档的过时描述,移除废弃的迁移说明与本地mock依赖 整理docs/README.md的文档索引,优化阅读路径
This commit is contained in:
@@ -1,16 +1,16 @@
|
||||
# 玩法管理 Admin API
|
||||
|
||||
> 适用端:`WonderQ-Admin`、`WonderQ-Admin-UI`。
|
||||
> 适用端:`WonderQ-Admin`、`WonderQ-Admin-UI-Vue`。
|
||||
>
|
||||
> 状态:已实现契约。本文件参考 `WonderQ-MiniAPP/src/pages/play/components/playData.ts` 定义玩法分类和路线的数据结构,以及管理端需要的查询、维护和排序接口。它不是 MiniAPP Public API 文档。
|
||||
> 状态:已实现契约。本文件定义玩法分类和路线的 Admin API,不替代 MiniAPP Public API 文档。
|
||||
|
||||
当前实现:`WonderQ-Admin` 通过迁移 `0015_wanfa` 创建 `WanfaCategory`、`WanfaRoute` 表并导入初始数据;`0022_opaque_ids` 将历史语义 ID 转换为稳定 UUID;`WonderQ-Admin-UI` 已接入分类和路线的查询、新增、编辑、删除及排序操作。
|
||||
当前实现:`WonderQ-Admin` 提供 `WanfaCategory`、`WanfaRoute` 的查询、新增、编辑、删除及排序接口;`WonderQ-Admin-UI-Vue` 已接入对应管理操作。
|
||||
|
||||
所有 JSON 响应遵循 [三端统一 API 响应契约](./api-response-contract.md),成功业务对象位于 `data`,失败时 `data` 为 `null`。
|
||||
|
||||
路线接口只维护分类和路线摘要字段。路线详情不写入 `WanfaRoute`,由独立 `DetailRecord` 通过 `docs/detail-api.md` 管理,详情记录的 `key` 等于路线 ID。首页玩法推荐和玩法页路线点击后统一跳转 `/pages/detail/index?routeId={route.id}`;无关联路线时才回退到需求页。
|
||||
|
||||
分类和路线的正式 `id` 均为服务端生成的稳定 UUID 字符串。下方本地数据映射中的语义 ID 只用于 MiniAPP fallback 和迁移前数据识别,不作为正式接口响应 ID;不要在序列化时临时随机生成 ID。
|
||||
分类和路线的正式 `id` 均为服务端生成的稳定 UUID 字符串;不要在序列化时临时生成 ID,也不要用标题或数组下标代替 ID。
|
||||
|
||||
## 领域边界
|
||||
|
||||
@@ -52,7 +52,7 @@ API 前缀为 `/api/admin`,除登录接口外均需要后台 JWT。
|
||||
- 所有管理接口需要 `Authorization: Bearer <admin-jwt>`。
|
||||
- 创建、编辑、删除和排序成功后写入审计日志,再提交事务。
|
||||
- 变更接口返回最新变更对象;排序接口返回排序后的 `items`。
|
||||
- ID 由后端生成并作为非空字符串返回。初始化迁移时应优先保留 `playData.ts` 中已有的稳定 ID。
|
||||
- ID 由后端生成并作为稳定 UUID 返回;管理端必须保存并复用接口返回的 ID。
|
||||
- 分类和路线的数组顺序就是管理端和前台的展示顺序,接口不要求前端依赖 `sortOrder` 字段。
|
||||
- 空集合返回 `[]`,不能返回 `null` 或省略字段。
|
||||
- 成功结果放入 `data`;失败返回数字 `code`、`msg`、`data: null`,可选 `errorCode` 和 `details`。
|
||||
@@ -60,7 +60,7 @@ API 前缀为 `/api/admin`,除登录接口外均需要后台 JWT。
|
||||
|
||||
## 数据类型
|
||||
|
||||
以下类型与 `playData.ts` 保持字段兼容。管理端接口不应向前台模型强制增加商品 ID、预订 ID 或数据库关联字段。
|
||||
以下类型与 Public API 的前台展示模型保持字段兼容。管理端接口不应向前台模型增加商品 ID、预订 ID 或数据库关联字段。
|
||||
|
||||
```ts
|
||||
type WanfaConfig = {
|
||||
@@ -299,20 +299,7 @@ Content-Type: application/json
|
||||
|
||||
分类不存在返回 `404`,业务码为 `WANFA_CATEGORY_NOT_FOUND`;路线 ID 不完整、重复或不属于该分类时返回 `400`,业务码为 `WANFA_ROUTE_REORDER_INVALID`。
|
||||
|
||||
## 当前本地数据映射
|
||||
|
||||
迁移初始数据时,分类和路线应按以下 ID 与顺序导入:
|
||||
|
||||
| 分类 ID | 分类名称 | 路线 ID(当前顺序) |
|
||||
| --- | --- | --- |
|
||||
| `family-route` | 亲子路线 | `family-water`、`family-village`、`family-grassland` |
|
||||
| `photo-route` | 旅拍路线 | `miao-photo`、`peak-photo`、`terrace-photo` |
|
||||
| `healing-route` | 疗愈路线 | `mountain-healing`、`hot-spring-healing`、`river-healing` |
|
||||
| `team-building` | 团建 | `team-challenge`、`team-stream`、`team-culture` |
|
||||
| `guizhou-panorama` | 贵州全景 | `classic-panorama`、`mountain-panorama`、`wild-panorama` |
|
||||
| `private-custom` | 私人定制 | `private-family`、`private-business`、`private-wild` |
|
||||
|
||||
图片别名的当前解析规则位于 `playData.ts` 的 `routeImageByAsset` 和 `resolveRouteImage`:已配置别名解析为完整远程 URL,完整 `http` URL 直接使用,其他值按 `/assets/guizhou/{image}.jpg` 解析。Admin API 建议保存最终 URL,Admin UI 通过现有媒体上传接口获取 URL 后再提交 `image`。
|
||||
图片字段保存最终 URL;管理端通过媒体上传接口获取 URL 后再提交 `image`。本地 fallback 数据不属于 Admin API 契约。
|
||||
|
||||
## Admin UI 对接要求
|
||||
|
||||
@@ -342,10 +329,9 @@ reorderWanfaRoutes(categoryId: string, itemIds: string[]);
|
||||
|
||||
## 后端落地边界
|
||||
|
||||
玩法数据由 `WonderQ-Admin` 的 `WanfaCategory`、`WanfaRoute` ORM 模型和 Admin API 负责持久化;`WonderQ-Admin-UI` 负责 API 类型、请求封装、表单、删除确认和排序交互。`playData.ts` 仅作为迁移初始数据来源,不能视为数据库或 API 数据。
|
||||
玩法数据由 `WonderQ-Admin` 的 `WanfaCategory`、`WanfaRoute` ORM 模型和 Admin API 负责持久化;`WonderQ-Admin-UI-Vue` 负责 API 类型、请求封装、表单、删除确认和排序交互。本地 fallback 数据不能视为数据库或 API 数据。
|
||||
|
||||
相关文档:
|
||||
|
||||
- [Admin API 主契约](./admin-api-requirements.md)
|
||||
- [页面模块配置契约](./module-config-api.md)
|
||||
- [玩法本地数据](../WonderQ-MiniAPP/src/pages/play/components/playData.ts)
|
||||
|
||||
Reference in New Issue
Block a user