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-Vue`：正式后台管理前端，用于维护首页工作台、玩法、详情、管家、需求线索和 RBAC，技术栈为 Vue 3、TypeScript、Vite、Element Plus、Pinia、Vue Router 4；采用 RuoYi-Vue3 风格壳层，但不复制其 Java 后端。
- `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-Vue/
└─ 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-Vue

```text
WonderQ-Admin-UI-Vue/
├─ README.md
├─ public/
├─ src/
│  ├─ App.vue
│  ├─ api/client.ts
│  ├─ components/layout/
│  ├─ components/home/
│  ├─ components/system/
│  ├─ components/wanfa/
│  ├─ directives/permission.ts
│  ├─ lib/
│  ├─ pages/
│  ├─ router/
│  ├─ stores/
│  ├─ styles.css
│  └─ vite-env.d.ts
├─ index.html
├─ package.json
├─ tsconfig.json
├─ vite.config.ts
└─ yarn.lock
```

- `src/layouts/AdminLayout.vue` 与 `src/components/layout/`：RuoYi 风格侧栏、Navbar、TagsView、设置抽屉和响应式布局。
- `src/api/client.ts`：Admin API 类型、Token 管理、鉴权头和请求封装。
- `src/pages/HomePage.vue`：顶部轮播、玩法推荐、万趣用车、团队共创和极境视界统一工作台。
- `src/pages/LeadsPage.vue`：需求线索筛选、分页、状态写入和详情弹窗。
- `src/pages/SystemResourcePage.vue`：用户、角色、菜单、部门管理；菜单使用服务端父子树。
- `src/components/wanfa/`、`src/components/concierge/`、`src/components/media/`：领域编辑器和 URL/OSS 媒体上传组件。
- `src/styles.css`：RuoYi/Element Plus 主题变量、布局、表格/表单和响应式样式。

### 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-Vue`

```powershell
Set-Location .\WonderQ-Admin-UI-Vue
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-Vue`：变更后运行 `yarn test` 和 `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-Vue`：生产发布使用 `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、`<script setup lang="ts">` 和 uni-app 组件，不引入 React。
- `WonderQ-Admin-UI-Vue` 使用 Vue 3 SFC、`<script setup lang="ts">`、Element Plus 和 Pinia；不恢复旧 React 管理端。
- `WonderQ-Admin-UI-Vue` 优先复用 Element Plus 和布局组件；重复样式集中在 `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/leads`，除非后端契约已同步变更。
- `vite.config.ts`、`manifest.json` 的 `/api` 代理只服务本地开发，不作为生产后端配置。
- 不要随意改动 `public/assets/source/` 中的采集内容，除非任务专门针对这些资源。

### `WonderQ-Admin-UI-Vue`

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

- `.env`、`.env.local`、任何生产环境变量或密钥配置。
- `vite.config.ts` 中的代理、端口和构建配置。
- `tsconfig.json` 的严格类型配置。
- `package.json`、`yarn.lock` 的依赖与脚本。
- `src/api/client.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`：初始化内容和迁移数据源。
- `Dockerfile`、`docker-compose.yml`：部署入口。
- `requirements.txt`、`pyproject.toml`：依赖和测试配置。

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

## 15. AI 输出要求

### 开发类需求

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

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

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

### 评审类需求

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

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

### 实施类需求

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

## 16. 自检清单

提交或答复前检查：

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