chore: import WonderQ project

2026-08-11 19:19:11 +08:00
commit f5a9e4403a
452 changed files with 34173 additions and 0 deletions
--- a/docs/integration-workflow.md
+++ b/docs/integration-workflow.md
@@ -0,0 +1,130 @@
+# 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` |
+
+## 本地启动顺序
+
+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` 返回前台所需数组字段。
+- `GET /api/public/products` 返回 `{ items: [...] }`。
+- `POST /api/admin/auth/login` 能返回 token 和 user。
+
+管理端联调重点：
+
+- 登录后请求头包含 `Authorization: Bearer <token>`。
+- 商品、目的地、站点配置、线索、发布和重置接口按 `admin-api-requirements.md` 返回。
+- 页面模块新增、更新、删除、排序按 `module-config-api.md` 返回 JSON。
+
+MiniAPP 联调重点：
+
+- `site-config` 和 `products` 失败时仍能回退本地内容。
+- 首页模块按 Public API 字段渲染，不依赖后台未发布或未启用数据。
+- 线索提交调用 `POST /api/public/leads`，失败时显示可理解错误。
+
+## 接口变更流程
+
+1. 先更新契约文档。
+   - Public API 变更：更新 `public-api.md`。
+   - Admin API 变更：更新 `admin-api-requirements.md`。
+   - 页面模块 CRUD 变更：更新 `module-config-api.md`。
+2. 后端实现或调整接口，并补充对应验证。
+3. 管理前端或 MiniAPP 按契约调整调用和类型。
+4. 三端分别运行对应验证命令。
+5. 若变更影响启动、部署或架构边界，同步更新 `backend-api-service.md`、`backend-plan.md` 或 `decisions.md`。
+
+## 验证命令
+
+后端：
+
+```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`、内容重置、发布、回滚和数据库迁移都属于高风险动作，生产环境执行前必须明确确认。