# 页面与接口映射

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

> 接口路径按 `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. 页面实现完成后同步更新本文件中的“页面建议字段”和实际接口使用情况。