377 lines
18 KiB
Markdown
377 lines
18 KiB
Markdown
# 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
|
||
│ ├─ 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
|
||
|
||
```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/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
|
||
|
||
```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/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` 根目录启动：
|
||
|
||
```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/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` 移动端采用简约、内容优先的视觉风格：以白色和低饱和中性色为基础，使用绿色作为主操作色，避免大面积渐变、金色渐变按钮、装饰性光晕和重阴影。
|
||
- 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 和移动端适配。
|
||
- 是否新增硬编码生产地址、客服链接、密钥或真实手机号。
|
||
- 是否运行了与变更范围匹配的验证，或明确说明未运行原因。
|