548f91c37f
- 移除后端产品、目的地、活动专题等废弃模块的数据库表与业务代码，删除冗余API接口 - 删除小程序端详情页、线路组件等冗余代码，移除搜索工具与测试用例，调整导航逻辑 - 清理管理端废弃的类型定义、编辑器与测试代码 - 更新项目文档，修正模块维护说明与接口文档内容
3.6 KiB
3.6 KiB
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，失败时显示可理解错误。
接口变更流程
- 先更新契约文档。
- Public API 变更：更新
public-api.md。 - Admin API 变更：更新
admin-api-requirements.md。 - 页面模块 CRUD 变更：更新
module-config-api.md。
- Public API 变更：更新
- 后端实现或调整接口，并补充对应验证。
- 管理前端或 MiniAPP 按契约调整调用和类型。
- 三端分别运行对应验证命令。
- 若变更影响启动、部署或架构边界，同步更新
backend-api-service.md、backend-plan.md或decisions.md。
验证命令
后端：
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、内容重置、发布、回滚和数据库迁移都属于高风险动作，生产环境执行前必须明确确认。