Files

duanshuwen c143b67275 feat(route-detail): 实现路线详情独立管理全链路功能

添加`DetailRecord`数据库模型、迁移脚本及完整的CRUD管理接口，将路线详情从玩法路线表解耦，实现独立存储。
在Admin UI的路线编辑器中集成详情配置面板，支持编辑详情文案、图片等展示内容。
完善MiniAPP路线详情页，新增导航函数、API调用及数据归一化逻辑，并添加对应单元测试。
更新所有相关文档，明确领域边界、联调流程及接口契约规范。
调整首页和玩法页的点击跳转逻辑，优先跳转路线详情页而非原需求页。
新增数值格式化工具函数优化内容展示效果。

2026-08-19 21:20:51 +08:00

5.1 KiB

Raw Blame History

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`

本地启动顺序

确认 Docker Desktop 已运行，然后启动后端依赖和数据库迁移。

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。健康检查：

http://localhost:4000/health

启动管理前端。

Set-Location .\WonderQ-Admin-UI
yarn install
yarn dev

默认访问：

http://localhost:5602

管理端优先通过 VITE_API_BASE_URL 或本地 Vite /api 代理访问 http://localhost:4000。

启动 MiniAPP H5。

Set-Location .\WonderQ-MiniAPP
yarn install
yarn dev

默认访问：

http://localhost:5173

微信小程序开发构建：

yarn dev:mp-weixin

联调检查清单

后端启动后先检查：

GET /health 返回服务健康状态。
GET /api/public/site-config 返回前台所需数组字段。
POST /api/admin/auth/login 能返回 token 和 user。

管理端联调重点：

登录后请求头包含 Authorization: Bearer <token>。
站点配置、线索、发布和重置接口按 admin-api-requirements.md 返回。
页面模块新增、更新、删除、排序按 module-config-api.md 返回 JSON。

MiniAPP 联调重点：

site-config 失败时仍能回退本地内容。
首页模块按 Public API 字段渲染，不依赖后台未发布或未启用数据。
线索提交调用 POST /api/public/leads，失败时显示可理解错误。

路线详情三端联调

路线详情使用独立 DetailRecord，不修改 WanfaRoute 表结构，也不建立商品、订单或预订关联。联调顺序如下：

执行数据库迁移，确认 0021_detail_records 已创建详情表并为已有路线生成基础记录；生产环境执行前按迁移规范单独确认。
在 Admin UI 进入“玩法”，编辑路线摘要和详情字段，保存时先保存路线，再以路线 ID 作为 DetailRecord.key 创建或更新详情。
检查 GET /api/public/wanfa/categories 仍只返回路线摘要；检查 GET /api/public/home 的玩法推荐携带关联路线摘要。
在 MiniAPP 首页玩法推荐或玩法页点击路线，确认跳转 /pages/detail/index?routeId={routeId}，并请求 GET /api/public/details/{routeId}。
修改 Admin UI 的详情内容后刷新 MiniAPP，确认标题、正文、费用说明、注意事项和画廊更新；停用或删除详情时确认 Public API 返回 404。
关闭后端接口，确认 MiniAPP 按路线 ID 展示本地网络图片和模拟文案，并提示当前为模拟数据；未知路线展示未找到和重试状态。

路线详情页当前不包含价格、收藏、在线订阅、预订、订单或管家联系动作。字段和错误约定以 detail-api.md、public-api.md 为准。

接口变更流程

先更新契约文档。
- Public API 变更：更新 public-api.md。
- Admin API 变更：更新 admin-api-requirements.md。
后端实现或调整接口，并补充对应验证。
管理前端或 MiniAPP 按契约调整调用和类型。
三端分别运行对应验证命令。

验证命令

后端：

Set-Location .\WonderQ-Admin
python -m pytest
python -m alembic upgrade head

管理前端：

Set-Location .\WonderQ-Admin-UI
yarn build

MiniAPP：

Set-Location .\WonderQ-MiniAPP
yarn build:h5
yarn build:mp-weixin
yarn test

安全边界

不读取、展示或提交 .env、.env.local 和生产环境变量值。
文档示例只写变量名，不写真实 Token、JWT secret、客服链接、企业 ID 或手机号。
python -m app.seed、内容重置、发布、回滚和数据库迁移都属于高风险动作，生产环境执行前必须明确确认。

5.1 KiB Raw Blame History Unescape Escape