zhongyouweb/docs/development

前端开发手册

这份文档用于人和 AI 在新窗口中快速接手项目。开发顺序固定为：先了解现状 → 梳理任务和接口 → 开发 → 验证 → 更新交接文档。

1. 新窗口先做什么

新开的 AI 窗口应先阅读项目根目录的 AGENTS.md。如果需要手动向 AI 说明，可以直接发送：

请在 C:\Du\work\duu\zhongyou\zhongyou_web 工作。先完整阅读 AGENTS.md、docs/development/README.md、docs/development/CURRENT_STATUS.md、docs/development/CURRENT_TASK.md、docs/api/README.md 和 docs/api/page-api-map.md，检查 git status 和相关现有代码。先把本次开发目标、页面、接口、字段映射、风险及验收方式整理进 CURRENT_TASK.md，向我汇报方案后再进行开发。完成后构建验证，并更新当前状态、开发日志和页面接口映射。

2. 技术栈和项目结构

• Vue 2.6
• Vue Router 3（history 模式）
• Vuex 3
• Element UI 2.15
• Axios
• Vue CLI 4 / Webpack 4
• Node：当前可用版本位于 C:\Du\Modules\nvm\v22.14.0

关键目录：

zhongyou_web/
├─ public/static/config.js       # 运行时服务地址、MQTT、APK 等配置
├─ src/api/                      # API 请求封装
├─ src/layout/                   # 页面整体布局
├─ src/router/                   # 公共及本地动态路由
├─ src/store/modules/permission.js # 后端菜单转换为动态路由
├─ src/utils/request.js          # Axios 实例和拦截器
├─ src/views/                    # 业务页面
├─ docs/api/                     # 从 api.json 整理出的接口资料
└─ docs/development/             # 开发状态和交接资料

3. 启动和构建

如果当前终端 PATH 中没有 npm，使用绝对路径：

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

生产构建脚本已配置 OpenSSL 3 兼容参数，避免：

error:0308010C:digital envelope routines::unsupported

更新接口文档：

& 'C:\Du\Modules\nvm\v22.14.0\npm.cmd' run docs:api

4. 路由和菜单机制

菜单不是主要写死在 src/router/index.js，而是登录后由后端菜单接口下发，在 src/store/modules/permission.js 中转换成组件和路由。

后端菜单的组件路径以 src/views 为根，不写 .vue。例如：

页面文件：src/views/hazard/audit/index.vue
组件路径：hazard/audit/index
父级路由：hazard
子级路由：audit
最终地址：/hazard/audit

页面创建完成不代表菜单自动出现，还需要：

1. 在“系统管理 → 菜单管理”创建目录/菜单。
2. 在“角色管理”给当前角色授权。
3. 重新登录或刷新，让后端重新下发菜单。

5. 接口资料怎么查

入口：API 接口资料中心。

推荐顺序：

1. 页面与接口映射：已有页面应该使用哪些接口。
2. docs/api/modules/*.md：按业务模块阅读接口名称、用途、参数和响应。
3. 数据模型与字段字典：查询实体字段说明。
4. docs/api/catalog.json：全文或程序化搜索全部 278 个接口。

接口原始文件位于项目上一级：C:\Du\work\duu\zhongyou\api.json。

6. 每次任务的开发流程

开发前

1. 理解用户目标和验收标准。
2. 检查当前页面是否为空白、是否已有用户改动。
3. 找到对应接口、请求字段、响应字段、字典和权限。
4. 确认原型字段和接口字段如何映射。
5. 识别接口缺失、定义不完整、权限或菜单依赖。
6. 更新 CURRENT_TASK.md 后再编码。

开发中

1. 先写/复用 src/api 请求封装。
2. 页面拆分专用组件到同级 components/。
3. 使用真实字段，不用未经允许的假接口或假数据。
4. 保留加载、空态、错误、分页和危险操作确认。
5. 修改范围保持与任务一致。

开发后

1. 静态检查和生产构建。
2. 核对菜单组件路径与实际文件大小写完全一致。
3. 更新 CURRENT_STATUS.md、CURRENT_TASK.md 和 DEVELOPMENT_LOG.md。
4. 页面接口变化时更新 docs/api/page-api-map.md。
5. 向用户说明接口是否仅接入代码、是否已实际联调。

7. 接口接入的关键注意事项

• MyConfig.BASE_API 当前是 http://www.bjsdqc.cn:10090/gd_dataserver。
• 因此 api.json 中 /gd_dataserver/gd_dataserver/... 的完整路径，在前端通常应封装为 /... 或 /flowable/...、/business/...，由 baseURL 补第一个 /gd_dataserver。
• 当前请求拦截器发送 Authorization: Bearer，OpenAPI 却标注 X-Access-Token；未经确认不要修改全局鉴权。
• 导出接口使用 Blob，优先复用 src/utils/request.js 提供的 download()。
• 页面若依赖字典值，应先搜索项目现有字典工具和后端字典配置，不要只显示裸编码。

8. 文档职责

文档	用途	什么时候更新
AGENTS.md	AI 必须遵守的项目规则	项目约定变化时
CURRENT_STATUS.md	当前项目和页面真实状态	每次开发完成后
CURRENT_TASK.md	正在开发任务的计划和结果	每次开发前、开发后
DEVELOPMENT_LOG.md	按时间记录已完成工作	每次开发完成后追加
docs/api/page-api-map.md	页面与接口、字段映射	页面接口发生变化时
docs/api/* 自动文档	OpenAPI 全量整理	api.json 更新后重新生成