zhongyouweb/docs/api/page-api-map.md

页面与接口映射

本文件按前端页面整理接口用途和页面字段。后续开发页面时，先从这里定位接口，再到 API 接口资料中心 的对应模块查看完整参数。

接口路径按 api.json 原样记录（单前缀 /gd_dataserver）。实际请求时结合项目 VUE_APP_BASE_API 拼接，前端 src/api 通常只写业务段路径。

隐患审核

页面位置：src/views/hazard/audit/index.vue

场景	接口名称	方法与路径	页面建议字段
待办/已办分页列表	隐患流程待办/已办列表	GET /gd_dataserver/flowable/hazard/todoList	id、reportNo、hazardName、status/statusName、hazardLevelName、reporterName、departmentName、createTime、canApprove
查看审批详情	隐患流程详情	GET /gd_dataserver/flowable/hazard/detail/{id}	隐患完整字段、flowStatus、canApprove、isInitiator
获取当前审批任务	获取流程详情	GET /gd_dataserver/flowable/busiInfo/getProcessDetail	query id=flowInstanceId；从当前任务中取 taskId/taskName/taskDefKey/executionId
同意/驳回	审批隐患流程	POST /gd_dataserver/flowable/hazard/complete	请求体重点：taskId、comment、result；result=1 同意，result=2 退回
切换隐患等级	切换隐患流程等级	POST /gd_dataserver/flowable/hazard/switchLevel	reportId、newHazardLevel、switchReason
上传附件	上传隐患附件文件	POST /gd_dataserver/business/hazard/uploadAttachment	query attachmentType；请求体为 multipart/form-data，文件字段为 files
查看附件	按隐患ID查附件列表	GET /gd_dataserver/business/hazard/attachment/{reportId}	fileName、filePath、fileSize、fileType、attachmentType

建议筛选字段：待办/已办类型、隐患编号、隐患名称、隐患等级、状态、上报人、上报时间。

隐患台账

页面位置：src/views/hazard/ledger/index.vue

场景	接口名称	方法与路径	页面建议字段
台账分页列表	隐患流程待办/已办列表	GET /gd_dataserver/flowable/hazard/todoList	reportNo、hazardName、hazardLevelName、hazardCategoryName、unitName、departmentName、reporterName、statusName、pointsAwarded、createTime、flowInstanceId、canApprove
查看详情	查隐患详情	GET /gd_dataserver/business/hazard/info/{id}	description、整改信息、审核信息、流程状态和所有台账字段
导出	导出隐患列表Excel	POST /gd_dataserver/business/hazard/export	复用列表筛选条件，响应按 Blob 下载
删除	删除隐患（级联删除附件）	DELETE /gd_dataserver/business/hazard/{ids}	ids，支持批量；这是破坏性操作，需要二次确认
查看附件	按隐患ID查附件列表	GET /gd_dataserver/business/hazard/attachment/{reportId}	附件名称、类型、大小和下载地址

当前页面实际使用：getListByPage（分页）、info/{id}、attachment/{reportId}。导出入口暂时隐藏，export 封装保留供后续恢复。原始 api.json 没有“重试同步/重新推送”接口，台账页面点击该操作时会提示接口缺失，不伪造请求结果；待后端提供路径后替换 src/api/hazard/ledger.js 的封装即可。

单位筛选项来源（2026-10-08 调整）：超级管理员展示“单位”下拉并调用 GET /system/dept/factoryList；非管理员隐藏该筛选项，调用 GET /system/dept/myFactory 取本厂区并静默作为 unitId 过滤；不再使用 GET /system/user/deptTree（非管理员无权限）。

建议筛选字段：隐患编号、名称、单位、部门、等级、分类、状态、上报人、发现时间、创建时间。

积分管理

页面位置：src/views/points/management/index.vue

当前规划：进入后展示“积分规则、申诉处理、手动调整、流水冲正”四个 Tab，默认展示积分规则；后三个 Tab 暂不可切换。本次先实现积分规则配置，UI 按实际需求调整，不按原型稿强制还原。

场景	接口名称	方法与路径	页面建议字段
规则分页列表	分页查询积分规则列表	GET /gd_dataserver/business/points/rule/list	deptId、deptName、hazardLevel（general/major/critical）、hazardCategory（A/B/C…档位）、points、enabled、操作；厂区优先显示名称、其次 ID、均无显示“全局规则”；展示顺序按等级后档位排序
指定等级规则列表	获取指定等级下的积分规则列表	GET /gd_dataserver/business/points/rule/rulesByLevel	query hazardLevel（general/major/critical，必填）、deptId（选填，超管可用，传具体ID查该厂区+全局、传 global 仅全局兜底、不传全部厂区）；响应 hazardLevel、hazardLevelName、root、children
厂区筛选	获取所有厂区级部门列表	GET /gd_dataserver/system/dept/factoryList	deptId、deptName；仅超级管理员显示，全部返回数据展开选择
当前厂区	获取当前用户所属厂区部门	GET /gd_dataserver/system/dept/myFactory	deptId、deptName；厂区管理员新增时展示并锁定，加载失败时禁止提交；列表权限由后端自动过滤
启用/停用	启用/禁用积分规则	POST /gd_dataserver/business/points/rule/toggleEnabled	query：id、enabled（0/1）
删除	删除积分规则	GET /gd_dataserver/business/points/rule/deleteById	query：id；二次确认
详情	获取积分规则详情	GET /gd_dataserver/business/points/rule/info	query：id；弹窗展示规则对象
新增	新增积分规则	POST /gd_dataserver/business/points/rule/add	JSON：hazardLevel、hazardCategory、points、ruleName 必填，enabled 默认 1；超级管理员提交所选 deptId/deptName，厂区管理员不发送厂区字段并由后端自动填充；priority 前端计算当前等级最大值+1但可修改；不传 createTime/updateTime/id，ruleCode 非必填

当前页面超级管理员显示厂区筛选并可选择新增规则所属厂区；厂区管理员不显示厂区筛选，列表请求不传 deptId，可以新增、启停和删除本厂区规则。申诉处理、手动调整、流水冲正 Tab 暂不接入接口，保持禁用状态；积分规则不提供编辑功能。

前端 src/api 请求路径按运行时 BASE_API 约定只写业务段路径，例如 /business/points/rule/list、/system/dept/factoryList；不要重复拼接 /gd_dataserver。

APP 首页数据看板

页面位置：zhongyouApp/src/screens/home/HomeDashboardScreen.tsx（数据分析模块）

场景	接口名称	方法与路径	页面建议字段
核心指标概览	首页-核心指标概览	GET /gd_dataserver/business/points/analysis/home/overview	pendingAuditCount、monthClosedCount、todayReportCount、todayExchangeCount、todayPointsIssued；管理员统计全部、其它账户仅本厂区
待办与预警	首页-待办与预警	GET /gd_dataserver/business/points/analysis/home/todo-warning	pendingAuditOver24hCount、riskWarningCount（集中兑换风控预警）、pendingAppealCount
近7日趋势与最新上报	首页-近7日趋势与最新上报	GET /gd_dataserver/business/points/analysis/home/trend-latest	trend7d[].date/count、latestReports[].id/reportNo/hazardName/hazardLevelName/status/statusName/reporterName/factoryDeptName/createTime（最新前5条）

隐患流程配置

页面位置：src/views/flowable/hazardConfig/index.vue

场景	接口名称	方法与路径	页面建议字段
配置分页列表	查询流程模板配置列表	GET /gd_dataserver/flowable/hazardFlowConfig/list	id、deptName、hazardLevelName、flowKey、flowName、status、createTime、updateTime
查看详情	获取流程模板配置详情	GET /gd_dataserver/flowable/hazardFlowConfig/{id}	配置模型全部字段
新增配置	新增流程模板配置	POST /gd_dataserver/flowable/hazardFlowConfig	必填：deptId、hazardLevel、flowKey；可填 deptName、hazardLevelName、flowName、status
修改配置	修改流程模板配置	PUT /gd_dataserver/flowable/hazardFlowConfig	后端说明不可修改厂区ID和隐患等级，编辑时应禁用对应控件
停用配置	删除流程模板配置	DELETE /gd_dataserver/flowable/hazardFlowConfig/{id}	逻辑删除，页面操作文案建议使用“停用”
当前厂区可用配置	获取当前厂区已配置的流程模板	GET /gd_dataserver/flowable/hazardFlowConfig/myFactoryConfigs	用于隐患上报时选择等级/流程
超级管理员厂区选项	获取所有厂区级部门列表	GET /gd_dataserver/system/dept/factoryList	deptId、deptName，供筛选和新增弹窗选择
二级管理员当前厂区	获取当前用户所属厂区部门	GET /gd_dataserver/system/dept/myFactory	回填并禁用厂区控件；新增时不主动提交厂区字段

当前页面已实际接入列表、详情、新增、修改、删除和两个厂区接口。列表请求发送 status 进行状态筛选；状态列仅以绿色“正常”/灰色“停用”Tag 展示，启停通过编辑弹窗和修改接口更新 status；删除仍按现有接口执行。真实分页响应为 data.list 和字符串 data.total，页面将总数转为数字后交给分页组件。

切换日志

页面位置：src/views/flowable/switchLog/index.vue

api.json 中存在“切换隐患流程等级”操作接口，但没有明确提供独立的隐患流程切换日志列表接口或切换日志模型。

目前可参考：

场景	接口名称	方法与路径	备注
执行切换	切换隐患流程等级	POST /gd_dataserver/flowable/hazard/switchLevel	参数：reportId、newHazardLevel、switchReason
尝试查询关联审计记录	按业务单号查询审计日志	GET /gd_dataserver/business/audit/log/biz/{bizId}	需后端确认流程等级切换是否写入审计日志，以及 bizId 是否等于隐患ID
通用审计分页	分页查询	GET /gd_dataserver/business/audit/log/getListByPage	当前 operationType 文档只列举审核通过、积分调整、兑换退款，没有流程切换类型

在后端补充/确认接口前，该页面只能保持空白或展示已确认写入审计日志的数据，不能假设存在切换日志字段。

商城相关接口

当前尚未创建独立商城页面，但“积分与商场”后续可能使用：

场景	接口名称	方法与路径	主要字段
Token查用户	根据Token获取用户信息	POST /gd_dataserver/mall/api/user/info	响应：id、userName、phone、email、sex、sap
Token查积分	根据Token获取用户积分信息	POST /gd_dataserver/mall/api/user/points	请求：sap；响应：integral 等用户信息
商城扣积分	扣减积分	POST /gd_dataserver/mall/api/points/deduct	sap、orderNum、integralValue，同一订单号幂等
商城退款积分	退还积分	POST /gd_dataserver/mall/api/points/refund	sap、orderNum、integralValue，同一订单号幂等

商城接口同时出现全局 X-Access-Token 和接口参数 token 请求头，实现前需确认是否都必须传。

后续页面开发约定

开发上述页面时同步完成：

1. 在 src/api/ 下按业务建立请求封装，不在 Vue 页面内直接写 URL。
2. 根据本映射选择接口，并回查对应模块文档与 schemas.md。
3. 搜索条件、表格列、详情字段优先采用接口中已有字段；UI 原型字段与接口不一致时明确记录映射。
4. 对 OpenAPI 定义不完整的接口（特别是积分手动调整、泛型响应）先标注并确认，不猜测请求结构。
5. 页面实现完成后同步更新本文件中的“页面建议字段”和实际接口使用情况。