# 当前开发任务

状态：隐患台账页面已完成，生产构建已验证（2026-09-05；同步重试接口待后端提供）

## 隐患台账页面任务（2026-09-04）

### 1. 用户目标

- 还原原型中的隐患台账筛选栏、汇总统计、9 列列表和行操作。
- 列表必须分页；详情优先使用宽屏弹窗完整展示，待审核记录进入隐患审核页面。
- 重试同步调用后端接口并提示结果；当前 `api.json` 未提供该接口，代码保留明确的待后端确认封装，不伪造成功。

### 2. 接口计划

| 页面动作 | 接口名称 | 方法 | 前端请求路径 | 请求字段 | 响应字段 | 确认状态 |
| --- | --- | --- | --- | --- | --- | --- |
| 台账分页 | 隐患信息分页查询 | GET | `/business/hazard/getListByPage` | `pageNum`、`pageSize`、`status`、`unitId` 等实体字段 | `data.list/total`（兼容 `rows/total`） | 已确认 |
| 查看详情 | 查隐患详情 | GET | `/business/hazard/info/{id}` | 路径 `id` | 隐患信息实体 | 已确认 |
| 查看附件 | 按隐患 ID 查附件 | GET | `/business/hazard/attachment/{reportId}` | 路径 `reportId` | 附件数组 | 已确认 |
| 导出 | 导出隐患列表 Excel | POST | `/business/hazard/export` | 当前筛选条件 | Blob | 已确认，入口暂时隐藏 |
| 去审核 | 隐患流程详情 | GET | `/flowable/hazard/detail/{id}` | 由审核页加载 | 隐患详情 | 已确认，跳转携带 `id/taskId` |
| 重试同步 | 未在 API 文档提供 | 未知 | 待后端确认 | 隐患 `id` | 未知 | 阻塞，不虚构 URL |

### 3. 页面字段映射

| UI 文案 | 前端字段 | 展示规则 |
| --- | --- | --- |
| 隐患编号/名称 | `reportNo`/`hazardName` | 表格主字段，名称超长省略 |
| 分级 | `hazardLevelName` 或 `hazardLevel` | `el-tag` |
| 状态 | `statusName` 或 `status` | `el-tag`，筛选四态：待审核/整改中/已闭环/已驳回 |
| 积分发放 | `pointsStatusName`、`pointsAwarded` | `el-tag`，后端值优先 |
| 平台同步 | `pushStatusName` 或 `pushStatus` | 失败显示重试入口 |
| 上报人/时间 | `reporterName`、`createTime` | 原型 9 列 |
| 详情 | 隐患实体全部字段及附件 | 宽屏 `el-dialog` 分组展示 |

### 4. 验收方式

- [x] 筛选、重置、分页、空态、错误态和加载态已实现。
- [x] 表格 9 列和原型操作按钮已实现，所有状态使用 Element UI `el-tag`。
- [x] 待审核记录跳转 `/hazard/audit/detail?id=...&taskId=...`；无任务号时给出提示。
- [x] 详情弹窗加载详情及附件；导出封装保留，入口暂时隐藏。
- [x] 重试同步接口缺失时明确提示，不显示虚假成功。

### 5. 完成结果

- 实际完成：隐患台账筛选、统计、分页表格、详情弹窗、附件展示和审核入口；导出按钮暂时移除。
- 实际使用接口：`getListByPage`、`info/{id}`、`attachment/{reportId}`、系统部门树接口。
- 验证结果：`git diff --check` 通过；使用项目 Node 22 执行 `npm run build:prod` 成功，仅有既有 Browserslist 和资源体积 warning。
- 遗留事项：后端需提供同步重试接口路径、请求字段和响应结构后，替换 `retryHazardSync` 占位封装。
- [x] 构建通过并更新状态、日志和接口映射。

本次先完成原型、页面字段、接口和入口关系梳理，尚未修改 Vue 业务代码。

## 隐患审核页面分析结论（2026-09-03）

### 1. 原型 UI 结构

- `隐患治理 → 隐患审核` 原型只有用户截图所示的“审核详情工作区”，没有待办/已办列表 UI；因此本页面按带隐患 `id` 的详情处理页实现，不自行增加列表。
- 原型另有 `流程管理 → 隐患审批` 页面，那里才有待办/已办列表、筛选和办理入口；该页面不是当前 `src/views/hazard/audit/index.vue`，后续是否合并由用户另行决定。
- 详情工作区采用三列布局：
  - 左列“上报内容”：附件缩略图（最多 8 张）、基础信息、隐患信息、隐患描述、GPS/上报时间。
  - 中列“审核动作·平台字段补录”：基本信息（可编辑/自动带入）、整改信息、选填信息、附件补充、审核意见和三个操作按钮。
  - 右列“流转与同步”：员工提交时间、平台同步状态、相似隐患提示、预计积分及通过后的联动说明。
- 建议 Vue 结构：页面 `index.vue` 负责列表/详情状态和接口；详情拆为 `components/HazardReportPanel.vue`、`components/AuditActionForm.vue`、`components/FlowSyncPanel.vue`，驳回、等级切换、附件预览/上传使用 `el-dialog` 或独立组件。
- 使用 Element UI：`el-form`、`el-tabs`（待办/已办）、`el-table`、`el-pagination`、`el-descriptions`、`el-upload`、`el-image`、`el-dialog`、`el-radio-group`、`el-select`、`el-date-picker`。

### 2. 页面字段清单与接口映射

#### 左侧上报内容（详情只读）

| 原型字段 | 接口字段 | 来源/备注 |
| --- | --- | --- |
| 隐患编号 | `reportNo` | 详情或列表 |
| 隐患名称 | `hazardName` | 详情 |
| 检查人/上报人 | `reporterName`、`reporterId`、`reporterUsername` | 原型“检查人”实际需确认是否等同上报人 |
| 单位 | `unitId`、`unitName` | 详情 |
| 所属部门/厂区 | `departmentId`、`departmentName`、`factoryDeptId`、`factoryDeptName` | 详情 |
| 风险分析对象 | `riskTarget` | 纯字符串，无选项接口 |
| 风险分析单元 | `riskUnit` | 纯字符串，无选项接口 |
| 发现日期/时间 | `discoverTime` | 详情 |
| 隐患状态 | `status`、`statusName` | 详情/列表 |
| 隐患分类 | `hazardCategory`、`hazardCategoryId`、`hazardCategoryName` | 详情 |
| 管理级别/流程等级 | `hazardLevel`、`hazardLevelId`、`hazardLevelName`、`currentFlowLevel` | 等级编码 general/major/critical 已在流程接口说明 |
| 资金来源 | `fundsSource`、`fundsSourceId`、`fundsSourceName` | 原型标为非必填 |
| 隐患来源 | `sourceType`、`sourceTypeId`、`sourceTypeName`、`hazardSourceDetail` | 原型“日常检查/随手拍”需字典确认 |
| 治理类型 | `governanceType`、`governanceTypeId`、`governanceTypeName` | 原型“限期整改/立即整改”需字典确认 |
| 隐患类型 | `hazardType`、`hazardTypeId`、`hazardTypeName` | 原型“电气”需字典确认 |
| 限定完成时间 | `limitedCompleteTime` | 详情 |
| 整改负责人 | `chargePersonId`、`chargePersonName`、`chargePersonUsername` | 详情 |
| 专业 | `major`、`majorId`、`majorName` | 详情；原型出现“电气/配电系统”，后半部分无独立字段 |
| 隐患描述 | `description` | 详情 |
| 原因分析 | `causeAnalysis` | 详情 |
| 防范措施 | `preventiveMeasures` | 详情 |
| 整改方案 | `rectificationPlan` | 接口有字段，原型详情未单独展示，不能遗漏 |
| 备注 | `remark` | 接口有字段，原型详情未单独展示，不能遗漏 |
| 实际完成时间 | `actualCompleteTime` | 接口有字段，整改闭环阶段使用 |
| 审核信息 | `auditRemark`、`auditTime`、`auditUserId`、`auditUserNameName`、`auditUserUsername` | 详情/流程历史 |
| 积分 | `pointsAwarded`、`pointsStatus`、`pointsStatusId`、`pointsStatusName` | 预计积分不可由前端固定写死 |
| 平台推送 | `pushStatus`、`pushStatusId`、`pushStatusName`、`pushTime`、`pushResponse`、`thirdPartyId` | 右列同步信息 |
| 流程状态 | `flowInstanceId`、`flowStatus`、`deployId`、`canApprove`、`isInitiator` | 详情；流程节点/历史是否随详情返回需确认 |
| 创建/更新时间 | `createBy`、`createTime`、`updateBy`、`updateTime` | 详情/审计 |

附件字段来自附件接口：`id`、`reportId`、`fileName`、`filePath`、`fileUrl`（列表接口文档使用该名称）、`fileType`、`fileSize`、`attachmentType`、`suffix`、`sortOrder`、`remark`、`uploadUserId`、`createTime`、`updateTime`、`createBy`、`updateBy`。`filePath` 与 `fileUrl` 的实际可访问字段需联调确认。

#### 待办/已办列表归属

- 当前隐患审核详情页不实现列表。
- `GET /flowable/hazard/todoList` 对应原型中的 `流程管理 → 隐患审批` 待办/已办列表，待开发该页面时再确认筛选参数和分页响应结构。

### 3. 下拉/选择项来源分析

| UI 选择项 | 已有字段/API | 当前结论 |
| --- | --- | --- |
| 单位 | `unitId/unitName`；前端已有 `/system/dept/treeselect`、`/system/getOrgUsers` 封装 | 没有“单位”专用接口；部门树是否等同单位树需后端确认，不可直接当作单位字典 |
| 部门/厂区 | `departmentId/name`、`factoryDeptId/name`；已有 `deptTreeSelect()` | 可以读取现有部门树，但厂区层级和筛选权限需确认 |
| 整改负责人/检查人 | `chargePerson*`、`reporter*`；已有 `getOrgUsers()`、`getUsersByDeptId()` | 可使用组织架构树/部门人员接口；详情回填优先使用接口返回对象，不主动覆盖 |
| 隐患等级 | `hazardLevel*`、`currentFlowLevel`；`myFactoryConfigs` 返回当前厂区流程等级配置 | 等级编码已确认 general/major/critical；若用于切换，选项可来自已配置流程，但需确认是否允许选择未配置等级 |
| 专业 | `major*` | 未发现专用 API 或确定字典编码；可调用通用 `/system/dict/data/type/{dictType}`，但 `dictType` 未提供，待后端确认 |
| 隐患分类 | `hazardCategory*` | 同上，缺少字典类型/接口说明 |
| 隐患来源 | `sourceType*`、`hazardSourceDetail` | 同上，缺少字典类型/接口说明 |
| 隐患类型 | `hazardType*` | 同上，缺少字典类型/接口说明 |
| 治理类型 | `governanceType*` | 同上，缺少字典类型/接口说明 |
| 资金来源 | `fundsSource*` | 同上，缺少字典类型/接口说明 |
| 状态 | `status/statusName` | 列表/详情直接展示后端名称；状态编码枚举在资料中不统一，不能前端硬编码筛选值 |
| 驳回理由 | 无独立字段/API | 原型四个选项（照片不清晰、重复上报、非安全隐患、信息不全）只能暂存为 UI 选项，并拼入 `comment`；需确认后端是否有固定编码 |

当前 `api.json` 明确提供的组织接口只有 `GET /system/getOrgUsers`、`GET /system/getTokenUser`；项目代码另有若依式部门树和字典封装，但其字典类型未在 API 资料中声明，不能假定具体字典编码。

用户已同意为页面自行创建测试字典。暂定字典类型为：`hazard_major`、`hazard_category`、`hazard_source`、`hazard_type`、`hazard_governance_type`、`hazard_funds_source`。已提供幂等初始化脚本；实际写入生产地址前需在已登录后台执行并核对结果。

### 4. 审核按钮与弹窗接口

- “通过”：`POST /flowable/hazard/complete`，请求体至少应包含 `taskId`、`comment`、`result=1`；原型的积分发放、员工推送、平台同步属于后端连锁结果，前端只展示响应结果，不能自行调用或固定显示 `+40`。
- “驳回”：同一接口，`result=2`，弹窗选择驳回理由并填写/合并意见到 `comment`；是否还需 `taskName`、`instanceId`、`targetKey` 等流程字段待确认。
- “重新评估等级”：`POST /flowable/hazard/switchLevel`，查询参数 `reportId`、`newHazardLevel`、`switchReason`；成功后刷新详情和列表。
- “查看附件/预览”：`GET /business/hazard/attachment/{reportId}`；原型“添加附件”可调用 `POST /flowable/hazard/uploadAttachment`，但审核详情是否允许上传、上传后是否需要再次保存/提交流程需确认。
- 危险操作（通过、驳回、切换、上传/删除附件）均需确认提示；附件删除接口存在但本页面暂不默认接入，除非用户明确要求。

#### 平台字段补录如何提交

- `POST /flowable/hazard/complete` 的请求体模型是“工作流签字任务相关--请求参数”，直接字段只有 `taskId`、`comment`、`result`、`instanceId`、`taskName`、`variables` 等流程字段。
- 该接口**没有直接声明** `unitId`、`major`、`riskUnit`、`riskTarget`、`hazardName`、`governanceType`、`chargePersonId` 等平台补录字段。
- 理论上可以把补录表单放进 `variables`，但 OpenAPI 只把 `variables` 定义为任意 `object`，没有说明后端会把它保存到隐患表或同步给生产运营平台，不能据此认定“complete 会传并保存这些字段”。
- 现有明确可以保存这些字段的接口是 `POST /business/hazard/updateById`，请求体为完整“隐患信息”，包含上述补录字段。
- 用户已确认调用顺序：点击通过/驳回时，先调用 `updateById` 保存中间补录表单及已上传附件关联信息；保存成功后再调用 `complete` 完成审批。第一步失败时不得继续审批。

### 5. 入口、URL 参数与回填

- 本页面必须由其他页面带参数进入，后续从左侧菜单配置中移除；不作为可独立打开的菜单页。
- 从工作台“最新上报/去审核”、隐患台账或 `流程管理 → 隐患审批` 的办理入口进入详情时，应携带隐患主键 `id` 和当前 `taskId`（建议 query：`/hazard/audit?id=123&taskId=456`）。
- 页面 `created`/`watch($route)`：有 `id` 时调用 `GET /flowable/hazard/detail/{id}`，再调用附件列表接口；无 `id` 时展示“缺少隐患 ID，无法加载审核详情”的空态，不请求列表。
- 列表行进入详情时必须传 `row.id`，不能用 `reportNo` 替代；返回列表时保留 tab、筛选和分页状态。
- 详情响应的 `canApprove=false` 或缺少 `taskId` 时，隐藏/禁用通过、驳回、切换按钮并提示当前任务不可处理。
- `HazardReport` 模型没有 `taskId` 字段，而 `complete` 明确要求 `taskId`；待办列表是否额外返回 `taskId`、或需通过其他流程任务接口换取，是当前开发前的关键阻塞点。

#### todoList 与 taskId 核对结果

- 通用待办接口 `GET /flowable/task/todoList` 的返回模型“工作流任务相关-返回参数”明确包含 `taskId`、`businessKey`、`procInsId`、`taskName`、`deployId`、`executionId` 等字段；项目现有待办页面也已直接使用 `row.taskId` 跳转处理页。因此从通用待办列表进入时，可以把 `taskId` 和业务 `id` 一并带入本页。
- 隐患专用接口 `GET /flowable/hazard/todoList` 的说明只保证列表项为 `HazardReport`，该模型没有 `taskId`。不能仅凭文档认定它一定返回 `taskId`；需要真实响应确认，或由后端给该接口补充 `taskId`。
- 实施建议：`流程管理 → 隐患审批` 若采用通用待办接口，使用 `businessKey` 作为隐患业务 ID、`taskId` 作为审批任务 ID；若必须使用隐患专用列表，则在确认其真实返回 `taskId` 后再接跳转。

### 6. 待后端/用户确认问题（简化版）

1. **隐患专用待办响应**：确认 `/flowable/hazard/todoList` 的真实列表项是否额外包含 `taskId`；若没有，审批入口使用通用 `/flowable/task/todoList` 的 `businessKey + taskId`。
2. **字典数据**：专业、隐患分类、隐患来源、隐患类型、治理类型、资金来源由项目方在系统字典中自行维护；用户后续会安排先创建少量测试字典数据，页面必须通过通用字典接口读取，不在代码中写死。
3. **单位/人员范围**：单位机构使用系统机构接口，人员使用人员接口；默认由后端按当前登录用户的数据权限返回“当前机构及下属机构/人员”，前端使用接口返回范围，不擅自扩大范围。
4. **附件关联**：已确认附件上传后，将返回的附件信息随 `updateById` 保存关联；实际请求字段结构仍需以联调响应为准。

其余字段先按详情接口原值回填；积分、同步状态只展示后端返回值，不在前端写死。

### 7. 验收方式（开发阶段）

- [ ] 带 `id` 进入详情时先回填详情和附件；缺少 `id` 时展示明确空态。
- [ ] 三列详情布局覆盖原型全部字段，未确认字段保持空态/禁用并有说明。
- [ ] 通过、驳回、等级切换、附件预览/上传弹窗完成并严格按确认后的请求体调用。
- [ ] `CURRENT_STATUS.md`、`DEVELOPMENT_LOG.md`、`page-api-map.md` 与实际接口保持一致。
- [ ] 生产构建通过。

> 每次开始新功能前，AI 必须先复制下面模板填写。不能直接跳过接口与字段梳理开始编码。

## 任务模板

### 1. 用户目标

- 要解决的问题：
- 涉及页面：
- 明确不在本次范围内的内容：

### 2. 当前代码状态

- 页面/组件现状：
- 已有 API 封装：
- 菜单与权限现状：
- 工作区已有改动及影响：

### 3. 接口计划

| 页面动作 | 接口名称 | 方法 | 前端请求路径 | 请求字段 | 响应字段 | 确认状态 |
| --- | --- | --- | --- | --- | --- | --- |
| 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 已确认/待确认 |

### 4. 页面字段映射

| UI 文案 | 前端字段 | 接口字段 | 展示/编辑规则 | 字典或枚举 |
| --- | --- | --- | --- | --- |
| 待填写 | 待填写 | 待填写 | 待填写 | 待填写 |

### 5. 实施步骤

1. 待填写。
2. 待填写。

### 6. 风险与待确认

- 待填写。

### 7. 验收方式

- [ ] 页面功能符合需求。
- [ ] 接口封装与字段映射已核对。
- [ ] 加载、空态、错误和分页已处理。
- [ ] 菜单路径及权限配置已说明。
- [ ] 生产构建通过。
- [ ] `CURRENT_STATUS.md`、`DEVELOPMENT_LOG.md` 和页面接口映射已更新。

### 8. 完成结果

- 实际完成：
- 实际使用接口：
- 验证结果：
- 遗留事项：