# WonderQ Project

万趣旅行三端项目集合，围绕 MiniAPP/H5 前台、运营管理后台和后端 API 协同开发。

## 项目组成

| 子项目             | 定位                    | 技术栈                                                            | 默认地址                |
| ------------------ | ----------------------- | ----------------------------------------------------------------- | ----------------------- |
| `WonderQ-MiniAPP`  | H5 与微信小程序前台     | uni-app、Vue 3、TypeScript、Tailwind CSS                          | `http://localhost:5173` |
| `WonderQ-Admin-UI` | 运营管理后台前端        | Vite、React、TypeScript、Tailwind CSS 4                           | `http://localhost:5602` |
| `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/         # 运营管理后台前端
└─ 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. 启动后端

要求：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
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. 启动管理后台

```powershell
Set-Location .\WonderQ-Admin-UI
yarn install
yarn dev
```

访问 `http://localhost:5602`。

### 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`；当前 `WonderQ-MiniAPP/vite.config.ts` 与 `WonderQ-Admin-UI/vite.config.ts` 的 `/api` 代理目标为 `4001`。三端联调前必须统一端口：

- 让后端监听 `4001`；或
- 将两个前端 Vite 配置中的代理目标同步改为 `4000`。

不要同时使用不一致的端口，否则页面会出现接口连接失败或空数据。

## 接口与文档

`docs/README.md` 是详细文档入口。推荐阅读顺序：

1. [`docs/integration-workflow.md`](docs/integration-workflow.md)：三端启动、联调顺序和接口变更流程
2. [`docs/development-status.md`](docs/development-status.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 使用的 Admin API 契约
5. [`docs/module-config-api.md`](docs/module-config-api.md)：页面模块 CRUD 细节契约
6. [`docs/backend-api-service.md`](docs/backend-api-service.md)：后端运行和集成说明
7. [`docs/decisions.md`](docs/decisions.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
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)。