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

项目采用页面驱动开发：前台页面定义用户流程，管理后台维护运营内容，后端负责鉴权、接口、数据持久化和发布能力。

目录结构

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。

首次安装：

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

健康检查和 OpenAPI 文档：

• http://localhost:4000/health
• http://localhost:4000/docs

首次初始化空库时才执行 python -m app.seed。该命令可能重置站点、商品、目的地和媒体内容，已有开发数据时不要重复执行。

2. 启动管理后台 WonderQ-Admin-UI-Vue

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. 启动前台

Set-Location .\WonderQ-MiniAPP
yarn install
yarn dev

访问 http://localhost:5173。微信小程序开发构建使用：

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：三端启动、联调顺序和接口变更流程
2. docs/api-response-contract.md：三端统一响应和错误契约
3. docs/public-api.md：MiniAPP 使用的 Public API 契约
4. docs/admin-api-requirements.md：Admin UI Vue 使用的 Admin API 契约
5. docs/module-config-api.md：首页与用车站点模块 CRUD 契约
6. docs/wanfa-api.md：玩法分类和路线管理契约
7. docs/detail-api.md：路线详情管理契约
8. docs/concierge-api.md：管家顾问管理契约

接口边界保持如下：

• MiniAPP 只访问 /api/public/...，不依赖后台登录态。
• Admin UI 访问 /api/admin/...，登录后使用 Bearer Token。
• 页面模块字段、排序、删除冲突和媒体上传规则以 docs/module-config-api.md 为准。

常用验证命令

后端：

Set-Location .\WonderQ-Admin
python -m pytest

管理后台：

Set-Location .\WonderQ-Admin-UI-Vue
yarn test
yarn build

前台：

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。