# 页面与接口映射

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

> 接口路径按 `api.json` 原样记录。实际请求时需要结合项目 `VUE_APP_BASE_API` 判断是否移除重复的 `/gd_dataserver` 前缀。

## 隐患审核

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

| 场景 | 接口名称 | 方法与路径 | 页面建议字段 |
| --- | --- | --- | --- |
| 待办/已办分页列表 | 隐患流程待办/已办列表 | `GET /gd_dataserver/gd_dataserver/flowable/hazard/todoList` | `id`、`reportNo`、`hazardName`、`status/statusName`、`hazardLevelName`、`reporterName`、`departmentName`、`createTime`、`canApprove` |
| 查看审批详情 | 隐患流程详情 | `GET /gd_dataserver/gd_dataserver/flowable/hazard/detail/{id}` | 隐患完整字段、`flowStatus`、`canApprove`、`isInitiator` |
| 同意/驳回 | 审批隐患流程 | `POST /gd_dataserver/gd_dataserver/flowable/hazard/complete` | 请求体重点：`taskId`、`comment`、`result`；`result=1` 同意，`result=2` 退回 |
| 切换隐患等级 | 切换隐患流程等级 | `POST /gd_dataserver/gd_dataserver/flowable/hazard/switchLevel` | `reportId`、`newHazardLevel`、`switchReason` |
| 查看附件 | 按隐患ID查附件列表 | `GET /gd_dataserver/gd_dataserver/business/hazard/attachment/{reportId}` | `fileName`、`filePath`、`fileSize`、`fileType`、`attachmentType` |

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

## 隐患台账

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

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

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

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

## 积分管理

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

此名称可能指“账户余额管理”，也可能包含“积分流水”。建议页面使用账户列表为主表，流水放详情抽屉或页签。

| 场景 | 接口名称 | 方法与路径 | 页面建议字段 |
| --- | --- | --- | --- |
| 账户分页列表 | 分页查询 | `GET /gd_dataserver/gd_dataserver/business/points/balance/getListByPage` | `userId`、`availableBalance`、`frozenBalance`、`totalIncome`、`totalOutcome`、`updateTime`、`version` |
| 查询指定用户 | 查询用户积分账户 | `GET /gd_dataserver/gd_dataserver/business/points/balance/getByUserId/{userId}` | 用户积分账户全部字段 |
| 手动补发/扣减 | 手动调整积分（PC管理端） | `POST /gd_dataserver/gd_dataserver/business/points/balance/adjust` | 文档说明需要指定用户及 `points`，但 OpenAPI 请求体只声明单个整数，字段定义不完整；实现前必须与后端确认真实提交格式 |
| 流水分页列表 | 分页查询 | `GET /gd_dataserver/gd_dataserver/business/points/transaction/getListByPage` | `txnNo`、`userId`、`amount`、`beforeBalance`、`afterBalance`、`bizType`、`bizId`、`operator`、`status`、`createTime` |
| 积分冲正 | 积分冲正 | `POST /gd_dataserver/gd_dataserver/business/points/transaction/reverse/{logId}` | `logId` |
| 积分规则 | 分页查询 | `GET /gd_dataserver/gd_dataserver/business/points/rule/getListByPage` | `ruleCode`、`ruleName`、`hazardLevel`、`hazardCategory`、`points`、`priority`、`enabled` |

## 隐患流程配置

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

| 场景 | 接口名称 | 方法与路径 | 页面建议字段 |
| --- | --- | --- | --- |
| 配置分页列表 | 查询流程模板配置列表 | `GET /gd_dataserver/gd_dataserver/flowable/hazardFlowConfig/list` | `id`、`deptName`、`hazardLevelName`、`flowKey`、`flowName`、`status`、`createTime`、`updateTime` |
| 查看详情 | 获取流程模板配置详情 | `GET /gd_dataserver/gd_dataserver/flowable/hazardFlowConfig/{id}` | 配置模型全部字段 |
| 新增配置 | 新增流程模板配置 | `POST /gd_dataserver/gd_dataserver/flowable/hazardFlowConfig` | 必填：`deptId`、`hazardLevel`、`flowKey`；可填 `deptName`、`hazardLevelName`、`flowName`、`status` |
| 修改配置 | 修改流程模板配置 | `PUT /gd_dataserver/gd_dataserver/flowable/hazardFlowConfig` | 后端说明不可修改厂区ID和隐患等级，编辑时应禁用对应控件 |
| 停用配置 | 删除流程模板配置 | `DELETE /gd_dataserver/gd_dataserver/flowable/hazardFlowConfig/{id}` | 逻辑删除，页面操作文案建议使用“停用” |
| 当前厂区可用配置 | 获取当前厂区已配置的流程模板 | `GET /gd_dataserver/gd_dataserver/flowable/hazardFlowConfig/myFactoryConfigs` | 用于隐患上报时选择等级/流程 |

## 切换日志

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

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

目前可参考：

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

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

## 商城相关接口

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

| 场景 | 接口名称 | 方法与路径 | 主要字段 |
| --- | --- | --- | --- |
| Token查用户 | 根据Token获取用户信息 | `POST /gd_dataserver/gd_dataserver/mall/api/user/info` | 响应：`id`、`userName`、`phone`、`email`、`sex`、`sap` |
| Token查积分 | 根据Token获取用户积分信息 | `POST /gd_dataserver/gd_dataserver/mall/api/user/points` | 请求：`sap`；响应：`integral` 等用户信息 |
| 商城扣积分 | 扣减积分 | `POST /gd_dataserver/gd_dataserver/mall/api/points/deduct` | `sap`、`orderNum`、`integralValue`，同一订单号幂等 |
| 商城退款积分 | 退还积分 | `POST /gd_dataserver/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. 页面实现完成后同步更新本文件中的“页面建议字段”和实际接口使用情况。