zhongyouweb/docs/development/CURRENT_TASK.md

当前开发任务

状态：隐患台账页面已完成，生产构建已验证（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. 验收方式

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

5. 完成结果

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

本次先完成原型、页面字段、接口和入口关系梳理，尚未修改 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. 完成结果

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