zhongyouweb/AGENTS.md

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 中通常只写第二个前缀之后的路径，例如：

   // 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. 新页面默认目录结构：

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

2. 页面专用组件放到本页面的 components/，可复用的跨业务组件才放 src/components/。

3. API 文件按业务模块划分，避免一个接口一个文件，也避免所有新接口堆到通用文件。

4. 菜单来自后端“系统管理 → 菜单管理”。新增页面时必须同时给出：菜单名称、上级菜单、菜单类型、路由地址、组件路径、权限字符和最终访问地址。

5. 列表页至少考虑：加载状态、查询/重置、分页、空数据、接口错误；删除/停用/审批等操作需要确认提示。

6. 不为了“看起来完成”而写假数据。接口未确认时保留清晰的空态或阻塞说明。

四、验证与交付

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

   & '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 策略或调用真实的删除/审批/扣减积分接口。
• 不声称接口联调成功，除非实际拿到成功响应并核对数据结构。