d5a4f7549b
- 新增详情页全套UI组件，重构详情页面的代码结构与业务逻辑 - 删除单独的登录页面与对应路由，将登录逻辑集成至个人中心页面 - 统一多页面组件的UI圆角样式，优化部分组件的布局与交互 - 调整玩法页面的跳转逻辑，点击路线卡片直接跳转至详情页 - 优化管家页面的tabBar显示隐藏与页面滚动锁定逻辑 - 更新首页团建项目的文案内容，简化描述文本 - 更新README文档，删除冗余的测试文件与废弃的路由配置 - 修复联系弹窗的事件触发逻辑，新增opened事件支持
155 lines
5.6 KiB
Markdown
155 lines
5.6 KiB
Markdown
# 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)。
|