d3a246a873
更新所有业务API文档，明确持久化资源的正式ID必须为服务端生成的稳定UUID，本地调试或接口失败时可使用语义ID作为fallback。新增数据库迁移脚本0022_opaque_ids，用于将历史语义ID转换为稳定UUID，并同步外键关联、详情记录的key字段以及审计日志的实体ID引用。新增该迁移的单元测试用例，验证ID替换与关联数据同步的逻辑正确性。调整MiniAPP前端代码，优化导航工具函数的格式，移除废弃函数并修改首页跳转逻辑，使用接口返回的UUID作为详情跳转参数。
153 lines
6.3 KiB
Markdown
153 lines
6.3 KiB
Markdown
# WonderQ 三端联调流程
|
||
|
||
本文档定义 `WonderQ-Admin` 后端、`WonderQ-Admin-UI` 管理前端、`WonderQ-MiniAPP` 前台的本地联调顺序和接口变更流程。
|
||
|
||
## 三端职责
|
||
|
||
| 端 | 目录 | 职责 | 主要契约 |
|
||
| ------------ | ------------------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||
| 后端 API | `WonderQ-Admin` | 提供 Public API、Admin API、鉴权、数据库、迁移和 seed | `backend-api-service.md`、`backend-plan.md`、`public-api.md`、`admin-api-requirements.md` |
|
||
| 管理前端 | `WonderQ-Admin-UI` | 维护首页结构、目的地、线索和页面模块配置 | `admin-api-requirements.md`、`module-config-api.md` |
|
||
| 前台 MiniAPP | `WonderQ-MiniAPP` | H5 与微信小程序前台展示、咨询和线索提交 | `public-api.md` |
|
||
|
||
三端所有 JSON 接口还必须遵守 [api-response-contract.md](./api-response-contract.md)：成功业务数据位于 `data`，失败为 `data: null`，`code` 必须等于 HTTP 状态码。
|
||
|
||
## 本地启动顺序
|
||
|
||
1. 确认 Docker Desktop 已运行，然后启动后端依赖和数据库迁移。
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-Admin
|
||
.\.venv\Scripts\Activate.ps1
|
||
docker-compose up -d postgres redis
|
||
python -m alembic upgrade head
|
||
python -m uvicorn app.main:app --host 0.0.0.0 --port 4000 --reload
|
||
```
|
||
|
||
首次缺少虚拟环境或依赖时，先在 `WonderQ-Admin` 目录执行 `python -m venv .venv` 和 `python -m pip install -r requirements.txt`。
|
||
健康检查：
|
||
|
||
```text
|
||
http://localhost:4000/health
|
||
```
|
||
|
||
2. 启动管理前端。
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-Admin-UI
|
||
yarn install
|
||
yarn dev
|
||
```
|
||
|
||
默认访问：
|
||
|
||
```text
|
||
http://localhost:5602
|
||
```
|
||
|
||
管理端优先通过 `VITE_API_BASE_URL` 或本地 Vite `/api` 代理访问 `http://localhost:4000`。
|
||
|
||
3. 启动 MiniAPP H5。
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-MiniAPP
|
||
yarn install
|
||
yarn dev
|
||
```
|
||
|
||
默认访问：
|
||
|
||
```text
|
||
http://localhost:5173
|
||
```
|
||
|
||
微信小程序开发构建：
|
||
|
||
```bash
|
||
yarn dev:mp-weixin
|
||
```
|
||
|
||
## 联调检查清单
|
||
|
||
后端启动后先检查：
|
||
|
||
- `GET /health` 返回服务健康状态。
|
||
- `GET /api/public/site-config` 返回前台所需数组字段。
|
||
- `POST /api/admin/auth/login` 能返回 token 和 user。
|
||
- 使用客户端或 curl 检查响应顶层包含数字 `code`、字符串 `msg` 和 `data`；不能继续接受旧的未包裹响应。
|
||
|
||
管理端联调重点：
|
||
|
||
- 登录后请求头包含 `Authorization: Bearer <token>`。
|
||
- 站点配置、线索、发布和重置接口按 `admin-api-requirements.md` 返回。
|
||
- 页面模块新增、更新、删除、排序按 `module-config-api.md` 返回 JSON。
|
||
|
||
MiniAPP 联调重点：
|
||
|
||
- `site-config` 失败时仍能回退本地内容。
|
||
- 首页模块按 Public API 字段渲染，不依赖后台未发布或未启用数据。
|
||
- 线索提交调用 `POST /api/public/leads`，失败时显示可理解错误。
|
||
- 首页、玩法、路线详情、管家、团队共创和客片案例请求都由公共 API 层解包 `data`，页面不重复解包。
|
||
|
||
## 路线详情三端联调
|
||
|
||
路线详情使用独立 `DetailRecord`，不修改 `WanfaRoute` 表结构，也不建立商品、订单或预订关联。联调顺序如下：
|
||
|
||
1. 执行数据库迁移，确认 `0021_detail_records` 已创建详情表并为已有路线生成基础记录；确认 `0022_opaque_ids` 已将历史语义 ID 转换为稳定 UUID，并同步玩法外键、详情 `key` 和审计引用。生产环境执行前按迁移规范单独确认。
|
||
2. 在 Admin UI 进入“玩法”，编辑路线摘要和详情字段，保存时先保存路线，再以路线 ID 作为 `DetailRecord.key` 创建或更新详情。
|
||
3. 检查 `GET /api/public/wanfa/categories` 仍只返回路线摘要；检查 `GET /api/public/home` 的玩法推荐携带关联路线摘要。
|
||
4. 在 MiniAPP 首页玩法推荐或玩法页点击路线，确认跳转 `/pages/detail/index?routeId={routeId}`，并请求 `GET /api/public/details/{routeId}`。
|
||
5. 修改 Admin UI 的详情内容后刷新 MiniAPP，确认标题、正文、费用说明、注意事项和画廊更新；停用或删除详情时确认 Public API 返回 `404`。
|
||
6. 关闭后端接口，确认 MiniAPP 按路线 ID 展示本地网络图片和模拟文案，并提示当前为模拟数据；未知路线展示未找到和重试状态。
|
||
|
||
## 稳定 ID 联调检查
|
||
|
||
1. 执行 `0022_opaque_ids` 后，检查首页、玩法、管家、团队共创和客片案例列表返回的 `id` 均为 UUID 字符串。
|
||
2. 从列表复制一个 ID 请求对应详情、排序或删除接口，确认同一 ID 可连续复用，不能每次响应变化。
|
||
3. 检查首页玩法推荐的 `categoryId`、路线 `id` 与 `GET /api/public/details/{key}` 的 `key` 关联正确。
|
||
4. MiniAPP 本地 fallback 的语义 ID 只在接口失败时使用，不得覆盖接口成功返回的 UUID。
|
||
|
||
路线详情页当前不包含价格、收藏、在线订阅、预订、订单或管家联系动作。字段和错误约定以 `detail-api.md`、`public-api.md` 为准。
|
||
|
||
## 接口变更流程
|
||
|
||
1. 先更新契约文档。
|
||
- 响应包裹、错误结构或状态码变化：更新 `api-response-contract.md`。
|
||
- Public API 变更：更新 `public-api.md`。
|
||
- Admin API 变更：更新 `admin-api-requirements.md`。
|
||
2. 后端实现或调整接口，并补充对应验证。
|
||
3. 管理前端或 MiniAPP 按契约调整调用和类型。
|
||
4. 三端分别运行对应验证命令。
|
||
|
||
## 验证命令
|
||
|
||
后端：
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-Admin
|
||
python -m pytest
|
||
python -m alembic upgrade head
|
||
```
|
||
|
||
管理前端：
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-Admin-UI
|
||
yarn build
|
||
```
|
||
|
||
MiniAPP：
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-MiniAPP
|
||
yarn build:h5
|
||
yarn build:mp-weixin
|
||
yarn test
|
||
```
|
||
|
||
## 安全边界
|
||
|
||
- 不读取、展示或提交 `.env`、`.env.local` 和生产环境变量值。
|
||
- 文档示例只写变量名，不写真实 Token、JWT secret、客服链接、企业 ID 或手机号。
|
||
- `python -m app.seed`、内容重置、发布、回滚和数据库迁移都属于高风险动作，生产环境执行前必须明确确认。
|