# 前端开发手册

这份文档用于人和 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`

关键目录：

```text
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，使用绝对路径：

```powershell
& '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 兼容参数，避免：

```text
error:0308010C:digital envelope routines::unsupported
```

更新接口文档：

```powershell
& '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`。例如：

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

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

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

## 5. 接口资料怎么查

入口：[API 接口资料中心](../api/README.md)。

推荐顺序：

1. [页面与接口映射](../api/page-api-map.md)：已有页面应该使用哪些接口。
2. `docs/api/modules/*.md`：按业务模块阅读接口名称、用途、参数和响应。
3. [数据模型与字段字典](../api/schemas.md)：查询实体字段说明。
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` 更新后重新生成 |