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,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) 为准。
|
||||
|
||||
Reference in New Issue
Block a user