# 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)。