e8eb8614f0
删除home-api.md、team-building-api.md等废弃文档 统一替换所有文档中的`WonderQ-Admin-UI`为`WonderQ-Admin-UI-Vue` 更新README.md与联调文档的内容与路径 修正各API文档的过时描述，移除废弃的迁移说明与本地mock依赖 整理docs/README.md的文档索引，优化阅读路径
161 lines
5.8 KiB
Markdown
161 lines
5.8 KiB
Markdown
# WonderQ Project
|
||
|
||
万趣旅行三端项目集合，围绕 MiniAPP/H5 前台、运营管理后台和后端 API 协同开发。
|
||
|
||
## 项目组成
|
||
|
||
| 子项目 | 定位 | 技术栈 | 默认地址 |
|
||
| ------------------ | ----------------------- | ----------------------------------------------------------------- | ----------------------- |
|
||
| `WonderQ-MiniAPP` | H5 与微信小程序前台 | uni-app、Vue 3、TypeScript、Tailwind CSS | `http://localhost:5173` |
|
||
| `WonderQ-Admin-UI-Vue` | 运营管理后台前端 | Vite、Vue 3、TypeScript、Element Plus、Pinia | `http://localhost:5604/admin/` |
|
||
| `WonderQ-Admin` | Public API 与 Admin API | Python、FastAPI、SQLAlchemy 2、Alembic、PostgreSQL、JWT、Pydantic | `http://localhost:4000` |
|
||
|
||
项目采用页面驱动开发：前台页面定义用户流程，管理后台维护运营内容，后端负责鉴权、接口、数据持久化和发布能力。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
WonderQ-Project/
|
||
├─ AGENTS.md # AI 协作与项目开发约定
|
||
├─ README.md # 项目入口文档
|
||
├─ docs/ # 接口契约、联调流程和技术决策
|
||
├─ WonderQ-MiniAPP/ # 前台 H5 / 微信小程序
|
||
├─ WonderQ-Admin-UI-Vue/ # Vue 运营管理后台前端
|
||
└─ WonderQ-Admin/ # 后端 API 服务
|
||
```
|
||
|
||
### MiniAPP 页面
|
||
|
||
当前页面路由配置位于 `WonderQ-MiniAPP/src/pages.json`：
|
||
|
||
- `pages/home/index`：首页
|
||
- `pages/play/index`：玩法
|
||
- `pages/concierge/index`：管家
|
||
- `pages/detail/index`：线路详情
|
||
- `pages/mine/index`：我的
|
||
|
||
前台可复用组件位于 `WonderQ-MiniAPP/src/components/`，页面专属组件按页面放在对应的 `components/` 目录中。
|
||
|
||
## 本地启动
|
||
|
||
建议按后端、管理后台、前台的顺序启动。
|
||
|
||
### 1. 启动后端 `WonderQ-Admin`
|
||
|
||
要求：Python `3.12 - 3.14`、Docker Desktop。
|
||
|
||
首次安装：
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-Admin
|
||
Copy-Item .env.example .env
|
||
python -m venv .venv
|
||
.\.venv\Scripts\Activate.ps1
|
||
python -m pip install -r requirements.txt
|
||
```
|
||
|
||
日常启动：
|
||
|
||
```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
|
||
```
|
||
|
||
健康检查和 OpenAPI 文档：
|
||
|
||
- `http://localhost:4000/health`
|
||
- `http://localhost:4000/docs`
|
||
|
||
首次初始化空库时才执行 `python -m app.seed`。该命令可能重置站点、商品、目的地和媒体内容，已有开发数据时不要重复执行。
|
||
|
||
### 2. 启动管理后台 `WonderQ-Admin-UI-Vue`
|
||
|
||
```powershell
|
||
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. 启动前台
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-MiniAPP
|
||
yarn install
|
||
yarn dev
|
||
```
|
||
|
||
访问 `http://localhost:5173`。微信小程序开发构建使用：
|
||
|
||
```powershell
|
||
yarn dev:mp-weixin
|
||
```
|
||
|
||
构建产物位于 `WonderQ-MiniAPP/dist/build/mp-weixin`，需使用微信开发者工具导入验证。
|
||
|
||
### 本地 API 端口说明
|
||
|
||
后端默认监听 `4000`，Vue 管理后台默认运行在 `5604`，并将 `/api` 请求代理到 `http://localhost:4000`。如果修改后端端口，需要同步设置 `WonderQ-Admin-UI-Vue/.env.local` 的 `VITE_API_PROXY_TARGET`。
|
||
|
||
## 接口与文档
|
||
|
||
`docs/README.md` 是详细文档入口。推荐阅读顺序：
|
||
|
||
1. [`docs/integration-workflow.md`](docs/integration-workflow.md)：三端启动、联调顺序和接口变更流程
|
||
2. [`docs/api-response-contract.md`](docs/api-response-contract.md)：三端统一响应和错误契约
|
||
3. [`docs/public-api.md`](docs/public-api.md)：MiniAPP 使用的 Public API 契约
|
||
4. [`docs/admin-api-requirements.md`](docs/admin-api-requirements.md)：Admin UI Vue 使用的 Admin API 契约
|
||
5. [`docs/module-config-api.md`](docs/module-config-api.md)：首页与用车站点模块 CRUD 契约
|
||
6. [`docs/wanfa-api.md`](docs/wanfa-api.md)：玩法分类和路线管理契约
|
||
7. [`docs/detail-api.md`](docs/detail-api.md)：路线详情管理契约
|
||
8. [`docs/concierge-api.md`](docs/concierge-api.md)：管家顾问管理契约
|
||
|
||
接口边界保持如下：
|
||
|
||
- MiniAPP 只访问 `/api/public/...`，不依赖后台登录态。
|
||
- Admin UI 访问 `/api/admin/...`，登录后使用 Bearer Token。
|
||
- 页面模块字段、排序、删除冲突和媒体上传规则以 `docs/module-config-api.md` 为准。
|
||
|
||
## 常用验证命令
|
||
|
||
后端：
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-Admin
|
||
python -m pytest
|
||
```
|
||
|
||
管理后台：
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-Admin-UI-Vue
|
||
yarn test
|
||
yarn build
|
||
```
|
||
|
||
前台：
|
||
|
||
```powershell
|
||
Set-Location .\WonderQ-MiniAPP
|
||
yarn test
|
||
yarn build:h5
|
||
yarn build:mp-weixin
|
||
```
|
||
|
||
UI 或跨端兼容改动还需要在浏览器中检查移动端和桌面宽度；微信小程序改动需要使用微信开发者工具检查构建产物。
|
||
|
||
## 开发约定
|
||
|
||
- MiniAPP 使用 Vue 3 SFC、`<script setup lang="ts">`、uni-app 组件和 Tailwind CSS。
|
||
- UI 样式优先使用现有 Tailwind 类、`src/app.css` 的 `--wq-*` 变量和共享组件，不重复建立颜色、阴影和圆角体系。
|
||
- 组件按职责拆分，页面只负责组合和数据流，不把可复用业务堆在单个文件中。
|
||
- 前台内容优先来自 Public API，接口失败或字段缺失时沿用已有本地 fallback 机制。
|
||
- 新增或变更接口时，先更新对应契约文档，再同步后端和前端实现。
|
||
- 不提交 `.env`、`.env.local`、Token、密码、真实客服信息、`node_modules/`、`.venv/`、`dist/`、日志和数据库备份。
|
||
|
||
更完整的协作边界、锁定文件和安全要求见 [`AGENTS.md`](AGENTS.md)。
|