WonderQ-Project/AGENTS.md

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. 根目录结构

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

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
│  ├─ generated-products.json
│  ├─ 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/products、/api/public/leads。
• src/lib/data.ts、src/lib/store.ts、src/lib/navigation.ts、src/lib/support.ts：业务数据归一化、共享状态、页面跳转和客服联系封装。
• src/content.ts、src/generated-products.json：前台静态兜底内容与产品数据。
• public/assets/：前台图片资源。

WonderQ-Admin-UI

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/products/ProductsPage.tsx：线路商品维护。
• src/pages/leads/LeadsPage.tsx：需求线索查询、筛选和状态流转。
• src/components/ui/：Button、Card、Input、Textarea、Badge、Alert、Switch、NativeSelect、Separator 等基础组件。
• src/styles.css：Tailwind 入口、设计变量、后台工作台、表格/表单和移动端适配。

WonderQ-Admin

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/generated-products.json
├─ 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、data/generated-products.json：初始化内容、重置命令和迁移数据源。
• alembic/、Dockerfile、docker-compose.yml：数据库迁移与部署入口。

7. 启动方式

后端 WonderQ-Admin

从 WonderQ-Project 根目录启动：

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

首次缺少虚拟环境或依赖时，再执行：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

健康检查：http://localhost:4000/health。

管理前端 WonderQ-Admin-UI

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

默认访问：http://localhost:5602。后端 Admin API 默认运行在 http://localhost:4000。

前台 WonderQ-MiniAPP

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

H5 默认访问：http://localhost:5173。微信小程序开发构建：

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/products、POST /api/admin/products、PATCH /api/admin/products/{id}。
• 禁止新增 /getBanner、/saveProduct、/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、<script setup lang="ts"> 和 uni-app 组件，不引入 React。
• WonderQ-Admin-UI 使用 React 函数组件和 Hooks，不引入 class component。
• 样式优先使用项目已集成的 TailwindCSS；管理端同时遵守 src/styles.css 的设计变量和已有类名体系。
• WonderQ-MiniAPP 页面和组件默认只能使用 TailwindCSS 工具类完成布局、间距、颜色、字体、边框、响应式及交互状态；禁止新增自定义 <style> 或 <style scoped>。仅在 uni-app 平台兼容性、伪元素或 Tailwind 无法表达的特殊规则下允许例外，并在代码附近说明原因。
• WonderQ-MiniAPP 的响应式样式优先使用 TailwindCSS 断点和任意值变体，避免在单文件组件中新增独立媒体查询；重复的视觉规则应提取为全局工具类或可复用组件。
• WonderQ-MiniAPP 移动端采用简约、内容优先的视觉风格：以白色和低饱和中性色为基础，使用绿色作为主操作色，避免大面积渐变、金色渐变按钮、装饰性光晕和重阴影。
• MiniAPP 卡片、输入框和操作按钮优先使用 8-12px 圆角、细边框和轻阴影；图片负责表达目的地与线路，不额外叠加装饰性图形。
• MiniAPP 顶部栏和底部导航保持扁平、稳定的固定布局，选中态通过颜色、细线或浅色底区分，不使用会改变布局的浮动徽章或缩放动画。
• 通用控件优先复用 src/components/ui/；图标优先使用 lucide-react。
• 功能不要集中堆在一个文件中。能拆分组件就拆分组件，能封装工具函数就封装工具函数，保持人工可维护性和复用性。
• UI 必须处理 loading、empty、error、retry、禁用态、提交中状态和移动端布局。
• MiniAPP 页面数据优先来自 Public API；接口失败或字段缺失时按现有本地兜底机制处理，不新增硬编码业务数据源。

13. 命名与代码风格

• 组件、类型使用 PascalCase。
• 函数、变量使用 camelCase。
• CSS class 沿用 kebab-case 或 Tailwind 原子类。
• Python 代码遵守现有 FastAPI、SQLAlchemy、Pydantic 风格。
• 中文文案文件按 UTF-8 处理；Windows PowerShell 中检查中文文件时使用 Get-Content -Encoding UTF8。
• 注释只写必要解释，避免“赋值给变量”这类无意义注释。

14. 高风险区域与锁定文件

全局高风险区域

未经用户明确授权，不得改动：

• .env、.env.local、生产环境变量、密钥配置、账号密码和真实隐私配置。
• 数据库配置、鉴权逻辑、部署入口、依赖锁文件。
• 已被页面引用的图片资源、采集源文件、生成数据和大批量素材文件。
• 任何会重置、迁移、删除、覆盖生产或开发数据的命令。

删除、批量移动、重命名资源文件前必须再次确认。

WonderQ-MiniAPP

• 不要在本子项目重新添加后端、数据库、ORM、Docker Compose、后台认证或管理后台页面。
• src/lib/api.ts 的公共 API 路径保持 /api/public/site-config、/api/public/products、/api/public/leads，除非后端契约已同步变更。
• vite.config.ts、manifest.json 的 /api 代理只服务本地开发，不作为生产后端配置。
• 不要随意改动 src/generated-products.json、public/assets/source/ 中的采集/生成内容，除非任务专门针对这些资源。

WonderQ-Admin-UI

未经用户明确授权，不得改动：

• .env、.env.local、任何生产环境变量或密钥配置。
• vite.config.ts 中的代理、端口和构建配置。
• tsconfig.json 的严格类型配置。
• package.json、yarn.lock 的依赖与脚本。
• src/api.ts 的接口路径、Token 存储键、鉴权头和类型契约。
• public/assets/ 下已被页面引用的图片资源和 manifest.json。
• docs/admin-api-requirements.md 与 docs/module-config-api.md 中的接口契约，除非任务就是同步契约变更。

WonderQ-Admin

未经用户明确授权，不得改动：

• .env、.env.local、生产环境变量和任何密钥配置。
• app/models.py、alembic/versions/*：数据库结构和迁移。
• app/auth.py：后台鉴权逻辑。
• app/routers/admin.py、app/routers/public.py：核心 API 行为。
• app/seed.py、app/content.py、data/generated-products.json：初始化内容和迁移数据源。
• Dockerfile、docker-compose.yml：部署入口。
• requirements.txt、pyproject.toml：依赖和测试配置。

如确需修改上述文件，先说明原因、影响范围、验证方式，并等待用户确认。

15. AI 输出要求

开发类需求

根据任务范围输出必要内容：

• 功能目标和影响范围。
• 涉及页面、用户角色、数据流和边界情况。
• 是否需要数据库、后端 API、Admin UI、MiniAPP 同步变更。
• 需要更新的契约文档。
• 开发顺序、验证命令和风险点。

不要对纯文档、纯样式、小修复机械输出数据库设计、后台 CRUD 或无关扩展建议。

评审类需求

优先输出问题，按严重程度排序，并给出文件和行号。重点关注：

• 行为回归、接口不兼容、权限绕过、数据丢失。
• 缺少参数校验、错误处理、空态处理或测试。
• 敏感信息泄露、生产环境风险、破坏锁定边界。

实施类需求

• 先读相关文件和契约，再动手。
• 修改范围最小化，不做无关重构。
• 编辑后检查变更内容。
• 按影响范围运行验证；无法运行时说明原因和剩余风险。

16. 自检清单

提交或答复前检查：

• 是否误读或输出敏感信息。
• 是否改动了未授权文件或锁定文件。
• 是否保持 Public API、Admin API、页面模块契约一致。
• 是否遗漏鉴权、参数校验、错误响应、审计或删除冲突处理。
• 是否处理 loading、empty、error、retry 和移动端适配。
• 是否新增硬编码生产地址、客服链接、密钥或真实手机号。
• 是否运行了与变更范围匹配的验证，或明确说明未运行原因。