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:
duanshuwen
2026-08-26 19:41:15 +08:00
parent 8de6ea01d0
commit e8eb8614f0
17 changed files with 143 additions and 1754 deletions

View File

@@ -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 建议保存最终 URLAdmin 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)