# AI 开发协作规则

本文件适用于 `zhongyou_web` 整个项目。任何新开的 AI/Codex 窗口，在修改代码前必须执行以下流程。

## 一、开始开发前

1. 确认工作目录是 `C:\Du\work\duu\zhongyou\zhongyou_web`。
2. 完整阅读：
   - `docs/development/README.md`
   - `docs/development/CURRENT_STATUS.md`
   - `docs/development/CURRENT_TASK.md`
   - `docs/api/README.md`
   - 涉及现有业务页面时，再读 `docs/api/page-api-map.md`
3. 执行 `git status --short`，检查用户已有改动；不得覆盖、回退或清理不属于当前任务的修改。
4. 检查用户点名的页面、相邻页面、`src/api` 请求封装、动态路由和公共组件，确认现状后再制定方案。
5. 在 `docs/development/CURRENT_TASK.md` 中先写清楚本次目标、范围、拟用接口、字段映射、风险和验收方式，然后才开始编码。

## 二、接口使用规则

1. 优先从 `docs/api/page-api-map.md` 按页面找接口；找不到时搜索 `docs/api/catalog.json`，再阅读 `docs/api/modules/` 下的对应模块和 `docs/api/schemas.md`。
2. Vue 页面内不直接调用 URL。请求统一封装到 `src/api/` 下相应业务文件中。
3. `public/static/config.js` 的 `MyConfig.BASE_API` 已包含 `/gd_dataserver`。`api.json` 中路径常为 `/gd_dataserver/gd_dataserver/...`，在 `src/api` 中通常只写第二个前缀之后的路径，例如：

   ```js
   // api.json:
   // /gd_dataserver/gd_dataserver/flowable/hazard/todoList
   // 前端请求封装通常应写：
   url: '/flowable/hazard/todoList'
   ```

   实现前必须对照现有请求和部署配置确认，不能机械复制完整路径。
4. 当前请求拦截器默认发送 `Authorization: Bearer <token>`，但 `api.json` 声明的是 `X-Access-Token`。在没有联调证据前，不得擅自全局修改鉴权头；发现 401 时先与后端确认。
5. 接口模型、原型字段和页面字段不一致时，应建立明确映射并记录在 `CURRENT_TASK.md`；不得虚构字段。
6. OpenAPI 定义不完整时先记录阻塞点并向用户/后端确认。尤其注意：
   - “切换日志”没有明确的独立列表接口。
   - “手动调整积分”说明需要用户与积分值，但请求体仅声明单个整数，格式不完整。
   - 多个通用 CRUD 响应只声明为 `object`，需要结合真实响应确认 `data/list/total` 结构。

## 三、页面开发规则

1. 新页面默认目录结构：

   ```text
   src/views/<module>/<page>/
   ├─ index.vue
   └─ components/
   ```

2. 页面专用组件放到本页面的 `components/`，可复用的跨业务组件才放 `src/components/`。
3. API 文件按业务模块划分，避免一个接口一个文件，也避免所有新接口堆到通用文件。
4. 菜单来自后端“系统管理 → 菜单管理”。新增页面时必须同时给出：菜单名称、上级菜单、菜单类型、路由地址、组件路径、权限字符和最终访问地址。
5. 列表页至少考虑：加载状态、查询/重置、分页、空数据、接口错误；删除/停用/审批等操作需要确认提示。
6. 不为了“看起来完成”而写假数据。接口未确认时保留清晰的空态或阻塞说明。

## 四、验证与交付

1. 修改 Vue/JS 后至少执行相关静态检查，并执行生产构建：

   ```powershell
   & 'C:\Du\Modules\nvm\v22.14.0\npm.cmd' run build:prod
   ```

2. 当前项目是 Vue 2 + Vue CLI 4 + Webpack 4；构建脚本已包含 `--openssl-legacy-provider`，用于兼容 Node 22/OpenSSL 3。
3. `Browserslist` 过期和资源体积通常是警告，不等于构建失败；交付时要区分 warning 和 error。
4. 完成开发后必须更新：
   - `docs/development/CURRENT_STATUS.md`：当前已实现/未实现状态。
   - `docs/development/DEVELOPMENT_LOG.md`：追加本次改动、接口、验证和遗留问题。
   - `docs/api/page-api-map.md`：页面实际使用的接口或字段发生变化时更新。
   - `docs/development/CURRENT_TASK.md`：标记完成情况和剩余事项。
5. 最终回复必须说明：完成内容、关键文件、实际使用接口、验证结果、仍需用户或后端确认的内容。

## 五、禁止事项

- 不回退用户现有改动，不对无关文件做批量格式化。
- 不直接编辑 `dist`；通过构建生成。
- 不手工修改自动生成的 `docs/api/modules/`、`docs/api/schemas.md`、`docs/api/catalog.json`。`api.json` 更新后运行 `npm run docs:api`。
- 不在未授权时修改生产地址、Token 策略或调用真实的删除/审批/扣减积分接口。
- 不声称接口联调成功，除非实际拿到成功响应并核对数据结构。