# AGENTS.md 本文档用于约束 AI 代理参与 WonderQ 项目开发时的行为、边界和验证方式。适用于 Codex、ChatGPT、Cursor、Claude Code 等 AI 工具。 项目层规则优先于通用规则；进入某个子项目工作时，优先遵守该子项目技术栈、接口契约和锁定边界。 ## 1. 全局协作规则 - 默认全程使用中文回答；用户明确要求其他语言时才切换。 - 回答简洁直接，不做无效铺垫，不输出与任务无关的说明。 - 需求不清晰、影响范围不明或涉及高风险文件时，先提问确认，不自行猜测执行。 - 默认只读优先。创建、修改、删除文件必须先获得用户明确授权。 - 严格按当前需求工作，不额外加功能、不扩大改动范围。 - 修改前先阅读目标文件、相邻实现、相关类型和契约文档；修改后检查变更内容，并按影响范围运行验证。 - 保留工作区里的用户改动，不使用 `git reset`、`git checkout --`、批量删除或覆盖无关文件。 - 不读取、展示、复述或提交 `.env`、`.env.local`、生产环境变量、Token、密码、密钥、真实客服链接、企业 ID、客户手机号等敏感信息。 - 文档、示例和测试只能使用占位值，不写入真实账号、密钥、联系方式或生产配置。 - 用户提到产品设计时，优先考虑 `product design`。 - 用户提出“调整视觉 UI”“视觉不好看”“美化界面”“优化视觉”“界面更好看”等需求时，优先考虑 `ui-ux-pro-max`，并结合项目现有设计系统落地。 ## 2. 项目定位 WonderQ 是三端分离的旅行产品项目集合，当前由三个独立子项目组成： - `WonderQ-MiniAPP`：万趣旅行移动端前台，面向 H5 与微信小程序，技术栈为 uni-app、Vue 3、TypeScript、TailwindCSS。 - `WonderQ-Admin-UI`：后台管理前端，用于维护首页结构、目的地、线路商品、页面模块和客户需求线索，技术栈为 Vite、React、TypeScript、Tailwind CSS 4、shadcn/ui 风格组件。 - `WonderQ-Admin`：后端 API 服务，为 MiniAPP 提供 Public API，为后台管理端提供 Admin API，技术栈为 Python、FastAPI、SQLAlchemy 2、Alembic、PostgreSQL、JWT、Pydantic。 核心开发原则是页面驱动开发：业务围绕 MiniAPP/H5 前台页面和运营配置场景展开；后台负责配置页面数据；后端负责业务逻辑、鉴权、数据持久化和接口；MiniAPP 负责展示与交互。 ## 3. 根目录结构 ```text WonderQ-Project/ ├─ AGENTS.md ├─ README.md ├─ docs/ │ ├─ README.md │ ├─ integration-workflow.md │ ├─ development-status.md │ ├─ decisions.md │ ├─ backend-api-service.md │ ├─ backend-plan.md │ ├─ admin-api-requirements.md │ ├─ module-config-api.md │ └─ public-api.md ├─ WonderQ-MiniAPP/ ├─ WonderQ-Admin-UI/ └─ WonderQ-Admin/ ``` ## 4. 文档入口与权威来源 - `docs/README.md` 是当前文档索引。 - `docs/integration-workflow.md` 定义三端本地启动、联调顺序、接口变更流程和验证命令。 - `docs/development-status.md` 记录三端能力对接状态，不替代实际测试结果。 - `docs/decisions.md` 记录当前有效技术和文档决策。 - `docs/public-api.md` 是 MiniAPP 对接后端的唯一 Public API 契约。 - `docs/admin-api-requirements.md` 是 Admin UI 对接后端的主契约。 - `docs/module-config-api.md` 是页面模块配置 CRUD 的唯一细节契约。 - `docs/backend-api-service.md`、`docs/backend-plan.md` 约束后端运行、联调、部署和规划边界。 接口、字段、状态码或模块规则发生变化时，先更新对应契约文档，再改后端和前端实现。 ## 5. 页面驱动开发流程 本项目采用页面驱动开发（Page Driven Development）：先从 MiniAPP/H5 前台页面和运营配置场景定义需求，再推进数据模型、后端 API、后台管理和前台实现。 新增或重构面向用户的页面、模块或运营能力时，按以下顺序推进： 1. 明确前台页面目标：用户角色、页面流程、展示模块、交互方式、空态、错误态和边界情况。 2. 明确数据归属：哪些字段来自 Public API，哪些字段由 Admin API 维护，哪些仅为本地兜底内容。 3. 更新契约文档：Public API 改 `public-api.md`，Admin API 改 `admin-api-requirements.md`，页面模块 CRUD 改 `module-config-api.md`。 4. 设计后端数据与接口：数据库模型、迁移、Pydantic schema、鉴权、审计、参数校验和错误响应。 5. 实现后端 API：保持现有路径和响应结构兼容，不随意破坏 MiniAPP 与 Admin UI 调用。 6. 实现后台管理：围绕运营配置页面组织菜单和表单，不按数据库表名机械拆菜单。 7. 实现 MiniAPP 展示：调用 Public API，处理 loading、empty、error、retry、分页/刷新和本地兜底。 8. 运行三端验证：按变更范围执行后端测试、前端构建、MiniAPP 构建和必要的浏览器/小程序验证。 小型修复、纯文档整理、单端 UI 调整不强制输出完整八步，但不能跳过与当前任务相关的契约、安全和验证检查。 ## 6. 三端模块分工 ### WonderQ-MiniAPP ```text WonderQ-MiniAPP/ ├─ index.html ├─ package.json ├─ tsconfig.json ├─ tailwind.config.ts ├─ vitest.config.ts ├─ vite.config.ts ├─ src/ │ ├─ main.ts │ ├─ App.vue │ ├─ app.css │ ├─ manifest.json │ ├─ pages.json │ ├─ content.ts │ ├─ components/ │ ├─ lib/ │ └─ pages/ ├─ tests/ ├─ public/assets/ └─ scripts/ ``` - `src/pages/`：首页、目的地、需求、权益和我的页面。 - `src/components/`：复用 Vue SFC 组件，如顶部栏、底部导航、客服弹层、空状态和留资表单。 - `src/lib/api.ts`：Public API 客户端与类型定义，访问 `/api/public/site-config`、`/api/public/leads`。 - `src/lib/data.ts`、`src/lib/store.ts`、`src/lib/navigation.ts`、`src/lib/support.ts`：业务数据归一化、共享状态、页面跳转和客服联系封装。 - `src/content.ts`：前台静态兜底内容。 - `public/assets/`：前台图片资源。 ### WonderQ-Admin-UI ```text WonderQ-Admin-UI/ ├─ README.md ├─ components.json ├─ public/assets/ ├─ src/ │ ├─ App.tsx │ ├─ api.ts │ ├─ components/ui/ │ ├─ lib/ │ ├─ pages/ │ ├─ main.tsx │ ├─ styles.css │ └─ vite-env.d.ts ├─ index.html ├─ package.json ├─ tsconfig.json ├─ vite.config.ts └─ yarn.lock ``` - `src/App.tsx`：后台应用壳、登录态、侧边导航和全局布局。 - `src/api.ts`：Admin API 类型、Token 管理、鉴权头和请求封装。 - `src/pages/structure/StructurePage.tsx`：首页、目的地页、需求页等页面模块配置主界面。 - `src/pages/leads/LeadsPage.tsx`：需求线索查询、筛选和状态流转。 - `src/components/ui/`：Button、Card、Input、Textarea、Badge、Alert、Switch、NativeSelect、Separator 等基础组件。 - `src/styles.css`：Tailwind 入口、设计变量、后台工作台、表格/表单和移动端适配。 ### WonderQ-Admin ```text WonderQ-Admin/ ├─ app/ │ ├─ main.py │ ├─ config.py │ ├─ database.py │ ├─ models.py │ ├─ schemas.py │ ├─ auth.py │ ├─ serializers.py │ ├─ content.py │ ├─ seed.py │ └─ routers/ │ ├─ public.py │ ├─ admin.py │ └─ shared.py ├─ alembic/ ├─ data/ ├─ tests/ ├─ Dockerfile ├─ docker-compose.yml ├─ requirements.txt ├─ pyproject.toml ├─ .env.example └─ README.md ``` - `app/main.py`：FastAPI 应用入口、CORS、错误处理和路由注册。 - `app/config.py`、`app/database.py`：环境变量配置与 SQLAlchemy engine/session/Base。 - `app/models.py`、`app/schemas.py`、`app/serializers.py`：ORM 模型、Pydantic 校验和响应序列化。 - `app/auth.py`：JWT 与后台鉴权。 - `app/routers/public.py`、`app/routers/admin.py`、`app/routers/shared.py`：Public API、Admin API 和共享查询。 - `app/content.py`、`app/seed.py`：初始化内容、重置命令和迁移数据源。 - `alembic/`、`Dockerfile`、`docker-compose.yml`：数据库迁移与部署入口。 ## 7. 启动方式 ### 后端 `WonderQ-Admin` 从 `WonderQ-Project` 根目录启动： ```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 ``` 首次缺少虚拟环境或依赖时，再执行： ```powershell python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install -r requirements.txt ``` 健康检查：http://localhost:4000/health。 ### 管理前端 `WonderQ-Admin-UI` ```powershell Set-Location .\WonderQ-Admin-UI yarn install yarn dev ``` 默认访问：http://localhost:5602。后端 Admin API 默认运行在 http://localhost:4000。 ### 前台 `WonderQ-MiniAPP` ```powershell Set-Location .\WonderQ-MiniAPP yarn install yarn dev ``` H5 默认访问：http://localhost:5173。微信小程序开发构建： ```powershell yarn dev:mp-weixin ``` ## 8. 测试与验证 - `WonderQ-Admin`：修改 Python 代码后运行 `python -m pytest`；涉及迁移时运行 `python -m alembic upgrade head`；空库或 seed 相关变更才考虑 `python -m app.seed`，且执行前必须确认风险。 - `WonderQ-Admin-UI`：当前未配置独立测试脚本，提交前至少运行 `yarn build`；涉及 UI、交互或接口行为时，本地启动页面并手动验证关键流程。 - `WonderQ-MiniAPP`：前台变更后至少运行 `yarn build:h5`、`yarn build:mp-weixin`、`yarn test`；UI 变更还应浏览器验证移动端和桌面宽度，涉及小程序兼容时用微信开发者工具验证 `dist/build/mp-weixin`。 - 纯文档变更可不跑构建，但必须检查文档链接、命令、路径和敏感信息。 ## 9. 部署规范 - `WonderQ-MiniAPP`：H5 生产构建使用 `yarn build:h5`，产物在 `dist/build/h5`；微信小程序构建使用 `yarn build:mp-weixin`，产物在 `dist/build/mp-weixin`。 - `WonderQ-Admin-UI`：生产发布使用 `yarn build` 生成 `dist/`，可交给 Nginx、CDN 或静态托管服务部署。 - `WonderQ-Admin`：使用 Dockerfile 与 `docker-compose.yml` 部署 API、PostgreSQL 和 Redis。 - 生产 API 地址、客服链接、企业 ID、JWT secret、OSS 密钥、数据库连接只允许通过部署环境变量注入，不硬编码到源码、测试或文档。 - 不提交 `dist/`、`node_modules/`、`.venv/`、`.env`、`.env.local`、日志、coverage、数据库备份或临时规划文件。 ## 10. 接口与数据规范 - Public API 与 Admin API 分离：MiniAPP 只访问 `/api/public/...`，Admin UI 只访问 `/api/admin/...`。 - 保持现有 API 路径和响应结构兼容；不要为了统一风格擅自改路径、改字段名或改响应包裹结构。 - 接口设计优先 RESTful 风格，如 `GET /api/admin/site-config`、`PATCH /api/admin/site-config/{module}/{id}`。 - 禁止新增 `/getBanner`、`/saveConfig`、`/updateConfig` 这类动作式路径，除非已有契约明确要求。 - TypeScript 与 API 响应字段保持 camelCase；后端内部可使用 snake_case，但序列化给前端时遵守契约。 - 外部输入必须通过 Pydantic schema 或前端表单校验；后端不能信任前端传参。 - 错误响应不得泄露内部异常、SQL、环境变量、Token、密钥或敏感业务数据。 - 页面模块字段、排序、删除冲突、媒体上传等细节以 `module-config-api.md` 为准。 ## 11. 数据库与后端实现原则 - Alembic 管理数据库迁移；涉及模型变更时同步迁移、测试和契约文档。 - 新业务表按实际需要考虑 `id`、`created_at`、`updated_at`、`deleted_at`、`status`、`sort` 等字段，不机械添加无意义字段。 - 时间字段后端统一使用明确时区语义；对外返回 ISO 8601 字符串。 - 查询应合理建立索引，避免 N+1 查询和无界列表。 - Admin 变更类接口应继续写入审计日志，尤其是发布、重置、删除、状态流转和页面配置变更。 - 复杂新业务优先按 Router、Service、Repository 分层拆分；现有简单接口可沿用当前结构，但不要把大量业务逻辑继续堆进单个路由函数。 ## 12. 前端实现原则 - TypeScript 项目使用 strict 模式，新增代码应有明确类型，避免 `any`。 - `WonderQ-MiniAPP` 使用 Vue 3 SFC、`