fbf2c772a8
- 移除所有废弃的旧首页配置模块，包括destinationHero、demand相关、HomeExperience、vehicleService等表结构与代码，新增数据库迁移删除遗留表 - 重构管理端后台布局为标准RuoYi风格，新增Sidebar、Navbar、SettingsDrawer等组件，替换旧的过渡菜单实现 - 调整移动端响应断点为768px，更新布局相关测试用例，新增布局组件测试 - 删除OperationsTools发布/重置页面，移除/tools菜单入口，清理对应的API调用与测试代码 - 重构玩法模块编辑器：替换旧的图片手动输入框为图片上传组件，移除冗余的取消按钮 - 新增线索查询offset参数支持，完善查询参数处理逻辑 - 优化rbac菜单构建逻辑，新增可见性控制参数 - 修正管家编辑器提示文案，优化系统资源编辑器表单初始化逻辑 - 清理小程序端废弃的体验推荐组件与相关测试代码 - 更新文档与种子脚本，匹配新的API契约与使用说明
4.2 KiB
4.2 KiB
WonderQ 三端联调流程
本文档定义 WonderQ-Admin 后端、WonderQ-Admin-UI-Vue 管理前端和 WonderQ-MiniAPP 前台的本地启动、联调顺序与接口变更流程。
三端职责
| 端 | 目录 | 职责 | 主要契约 |
|---|---|---|---|
| 后端 API | WonderQ-Admin |
提供 Public API、Admin API、鉴权、数据库、迁移和 seed | admin-api-requirements.md、public-api.md |
| 管理前端 | WonderQ-Admin-UI-Vue |
管理登录、权限、站点模块、玩法、详情、管家和线索 | admin-api-requirements.md、module-config-api.md、各领域契约 |
| 前台 MiniAPP | WonderQ-MiniAPP |
H5 与微信小程序展示、咨询和线索提交 | public-api.md |
三端所有 JSON 接口还必须遵守 api-response-contract.md：成功业务数据位于 data，失败时 data: null，code 等于 HTTP 状态码。
本地启动顺序
1. 启动后端
首次安装：
Set-Location .\WonderQ-Admin
Copy-Item .env.example .env
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
日常启动：
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
健康检查：http://localhost:4000/health。
首次空库初始化内容才执行 python -m app.seed；该命令会覆盖初始化站点与媒体内容，已有开发数据时不要重复执行。
2. 启动管理前端
Set-Location .\WonderQ-Admin-UI-Vue
yarn install
yarn dev
访问 http://localhost:5604/admin/。Vite /api 代理默认指向 http://localhost:4000；修改后端地址时，在 .env.local 设置 VITE_API_PROXY_TARGET。
3. 启动 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返回统一包裹的登录结果。- 所有成功响应包含数字
code、msg: "success"和data；失败响应的data必须为null。
管理端重点检查：
- 登录后请求带
Authorization: Bearer <access-token>，Refresh Token 只通过 HttpOnly Cookie 传递。 - 站点模块、玩法、详情、管家、线索和媒体接口按当前契约返回。
- 新增、更新、删除和排序成功后，页面使用接口返回的数据更新状态，不自行生成 ID 或排序结果。
MiniAPP 重点检查：
- Public API 失败时显示错误、重试或空态，并按现有本地 fallback 规则处理。
- 首页、玩法、路线详情、管家、团队共创和客片案例都由公共 API 层解包
data，页面不重复解包。 POST /api/public/leads的用车需求携带客户 JWT；后端从 JWT 写入customerId，客户端不提交该字段。
接口变更流程
- 响应包裹、错误结构或 ID 规则变化：先更新
api-response-contract.md。 - Admin API 路径、字段、权限或状态码变化：更新
admin-api-requirements.md或对应领域契约。 - 站点模块字段、排序、单例或删除规则变化：更新
module-config-api.md。 - Public API 变化：更新
public-api.md，再同步后端序列化和 MiniAPP 类型。 - 完成后端实现、前端调用和影响范围内的测试；不得在流程文档中复制接口字段。
验证命令
后端：
Set-Location .\WonderQ-Admin
python -m pytest
管理前端：
Set-Location .\WonderQ-Admin-UI-Vue
yarn test
yarn build
MiniAPP：
Set-Location .\WonderQ-MiniAPP
yarn test
yarn build:h5
yarn build:mp-weixin
安全边界
- 不读取、展示或提交
.env、.env.local和生产环境变量值。 - 文档示例只写占位值，不写真实 Token、JWT secret、客服链接、企业 ID 或手机号。
python -m app.seed和数据库迁移属于高风险动作，生产环境执行前必须明确确认。