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,6 +1,6 @@
# 三端统一 API 响应契约
本文档是 `WonderQ-Admin`、`WonderQ-Admin-UI`、`WonderQ-MiniAPP` 的统一 JSON 响应规范。适用于 `/health`、`/api/public/**` 和 `/api/admin/**`,新接口必须直接遵守本契约。
本文档是 `WonderQ-Admin`、`WonderQ-Admin-UI-Vue`、`WonderQ-MiniAPP` 的统一 JSON 响应规范。适用于 `/health`、`/api/public/**` 和 `/api/admin/**`,新接口必须直接遵守本契约。
## 基本结构
@@ -28,9 +28,8 @@
- 所有持久化资源的 `id` 都是服务端生成的稳定不透明字符串,当前实现统一使用 UUID v4 格式。
- ID 只在记录创建时生成,后续列表、详情、排序、编辑和删除响应必须保持不变;禁止在序列化或每次请求时重新随机生成。
- 玩法路线详情的 `DetailRecord.key` 等于对应的 `WanfaRoute.id`,因此路线 ID 迁移后详情 `key` 必须同步更新。
- 玩法路线详情的 `DetailRecord.key` 等于对应的 `WanfaRoute.id`,详情、列表、排序和跳转必须复用同一个路线 ID。
- 本地 fallback/mock 数据可以继续使用便于阅读的语义 ID,但这些 ID 不代表服务端正式 ID;接口成功后应以 API 返回的 UUID 为准。
- `0022_opaque_ids` 迁移只转换历史非 UUID ID,并同步外键、详情 key 和审计实体引用;新建记录继续由 ORM 默认生成 UUID。
## 成功响应
@@ -106,7 +105,7 @@
## 客户端处理
- `WonderQ-Admin` 负责所有路由和全局异常处理,不能把内部异常、SQL、堆栈、Token 或环境配置写入 `msg`、`details` 或响应日志。
- `WonderQ-Admin-UI` 的公共 `request<T>` 校验包裹结构,成功只返回 `data`;失败使用 `msg` 提示,并保留 `errorCode`、`details`。
- `WonderQ-Admin-UI-Vue` 的公共 `request<T>` 校验包裹结构,成功只返回 `data`;失败使用 `msg` 提示,并保留 `errorCode`、`details`。
- `WonderQ-MiniAPP` 的公共请求层执行同样校验,页面、Store 和归一化函数继续只接收业务类型,不重复读取 `data`。
- HTTP 错误是服务端返回了合法错误包;网络错误是请求未获得 HTTP 响应;协议错误是响应缺少必填字段或字段类型不正确,三者应分别进入现有错误、重试和 fallback 流程。
- 未包裹的旧响应不再兼容,客户端必须将其识别为协议错误。
@@ -121,4 +120,4 @@
4. 列表、详情、删除和排序的原业务字段只出现在 `data` 内。
5. `400`、`401`、`404`、`409`、`422`、`500`(适用时)都保持相同包裹结构。
相关领域字段和路径以 [public-api.md](./public-api.md)、[admin-api-requirements.md](./admin-api-requirements.md)、[home-api.md](./home-api.md)、[wanfa-api.md](./wanfa-api.md)、[detail-api.md](./detail-api.md)、[concierge-api.md](./concierge-api.md)、[team-building-api.md](./team-building-api.md) 和 [wild-archives-api.md](./wild-archives-api.md) 为准。
相关领域字段和路径以 [public-api.md](./public-api.md)、[admin-api-requirements.md](./admin-api-requirements.md)、[module-config-api.md](./module-config-api.md)、[wanfa-api.md](./wanfa-api.md)、[detail-api.md](./detail-api.md) 和 [concierge-api.md](./concierge-api.md) 为准。