docs(changelog): 6 域审核记录独立查询接口（#7801 PR-2 / PR #7814，前端）

2026-09-16 22:04:56 +08:00
@@ -0,0 +1,127 @@
+---
+schema: "hl-changelog/v2"
+ticket: "finance-review-logs-6domains"
+title: "6 域审核记录独立查询接口（详情弹窗「审核记录」独立 tab 数据源）"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "新增接口"
+backend_status: "merged"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-16"
+status_note: "6 单据域（应付款/预付款/报账款/员工借款/费用报销/业务外收支）各新增 1 个审核流水独立查询接口 GET /admin/finance/<域>/{id}/review-logs，6 域共用 FinReviewLogRespVO 8 字段，按审核发生时间升序、无记录空数组。配套原型：单据详情弹窗拆「详情信息/审核记录」两 tab（payex-detail 通用框架），审核记录 tab 数据走本接口。报账详情旧内嵌 reviewLogs 字段标 @Deprecated（保留向后兼容不回删，新接入走 §报账独立接口）。已合并 dev-v3（PR #7814）+ 部署测试服行为级验证 PASS（Flyway 6 表建齐、6 接口 200、approve 落痕可回放）。"
+updated_at: "2026-09-16"
+base: "dev-v3"
+---
+
+# 6 域审核记录独立查询接口
+
+> **服务**: hl-order-service-v3（hl-finance 模块）
+> **类型**: 🆕 新增接口（6 个只读端点；另：报账详情出参 `reviewLogs` 字段标 @Deprecated，向后兼容不回删）
+> **日期**: 2026-09-16
+> **关联**: Issue #7801（PR-2）/ PR #7814 · 原型 #7805 / #7808
+
+---
+
+## 🔴 一句话给前端
+
+6 类单据（应付款/预付款/报账款/员工借款/费用报销/业务外收支）的**审核记录**，从「详情接口内嵌字段」抽成**独立的审核流水接口**。单据详情弹窗拆成「**详情信息 / 审核记录**」两个 tab：详情信息仍走原详情接口，审核记录 tab 调本新接口。
+
+| | 之前 | 现在 |
+|---|---|---|
+| 审核记录来源 | 仅报账款有（内嵌详情出参 `reviewLogs`），其余 5 域无 | 6 域统一独立接口 `GET .../review-logs` |
+| 详情弹窗 | 审核记录混在详情里 | 「详情信息 / 审核记录」两 tab 分离 |
+| 报账 `reviewLogs` | 详情出参内嵌数组 | 标 @Deprecated（仍返回、不回删），新接入走独立接口 |
+
+---
+
+## 接口清单（6 个，结构完全一致）
+
+| # | 方法 | 路径 | 域 | 单据不存在错误码 |
+|---|---|---|---|---|
+| 1 | GET | `/admin/finance/payments/{id}/review-logs` | 应付款付款单 | `598801` |
+| 2 | GET | `/admin/finance/prepays/{id}/review-logs` | 预付款申请单 | `599001` |
+| 3 | GET | `/admin/finance/reimburses/{id}/review-logs` | 报账执行单 | `599201` |
+| 4 | GET | `/admin/finance/staff-loans/{id}/review-logs` | 员工借款单 | `599101` |
+| 5 | GET | `/admin/finance/expenses/{id}/review-logs` | 费用报销单 | `598701` |
+| 6 | GET | `/admin/finance/nonbiz-flows/{id}/review-logs` | 业务外收支单 | `598504` |
+
+**统一规格**：
+- 路径占位 `{id}` = 单据主键（Long，string 序列化）
+- 返回 `Result<List<FinReviewLogRespVO>>`，按审核发生时间 **升序**，无记录返回 **空数组 `[]`**（非 null、非 404）
+- 单据不存在/已软删 → 抛各域既有 NOT_FOUND 错误码（见上表），**零新增错误码**
+
+---
+
+## 出参（FinReviewLogRespVO，6 域共用）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `logId` | String | 流水 ID（Long，string 序列化防 JS 精度丢失） |
+| `action` | String | 审核动作（词表按域，见下） |
+| `operatorId` | String | 操作人 ID（Long string；无登录上下文时为 null） |
+| `operatorName` | String | 操作人真名快照（AdminContextUtil 取当前登录管理员；可空） |
+| `opinion` | String | 审核意见（可空） |
+| `fromStatus` | String | 操作前单据状态 |
+| `toStatus` | String | 操作后单据状态 |
+| `createTime` | String | 审核发生时间 `yyyy-MM-dd HH:mm:ss` |
+
+### action 词表（按域实证，前端按值渲染文案）
+
+| 域 | action 取值 |
+|---|---|
+| 应付款 / 预付款 / 员工借款 / 费用报销 | `APPROVE` 批准 / `REJECT` 驳回 |
+| 业务外收支 | 仅 `APPROVE` 批准（本域无驳回动作） |
+| 报账款 | `APPROVE` 批准 / `RETURN` 退回 / `UN_APPROVE` 反审（反向操作也留痕） |
+
+> 前端展示「操作」列建议：APPROVE=批准 / REJECT=驳回 / RETURN=退回 / UN_APPROVE=反审。配合 `fromStatus→toStatus` 可渲染「从 X 改为 Y」。
+
+---
+
+## 示例
+
+**请求**：`GET /admin/finance/payments/1962xxxxxxxxxx/review-logs`
+
+**典型（有记录）**：
+```json
+{
+  "code": 0,
+  "data": [
+    { "logId": "2101...", "action": "REJECT", "operatorId": "1962...", "operatorName": "王芳", "opinion": "金额与行程不符", "fromStatus": "SUBMITTED", "toStatus": "REJECTED", "createTime": "2026-09-15 10:20:00" },
+    { "logId": "2101...", "action": "APPROVE", "operatorId": "1962...", "operatorName": "王芳", "opinion": "重新核对无误", "fromStatus": "SUBMITTED", "toStatus": "APPROVED", "createTime": "2026-09-16 09:05:00" }
+  ],
+  "message": "success"
+}
+```
+
+**边界（无记录）**：
+```json
+{ "code": 0, "data": [], "message": "success" }
+```
+
+**异常（单据不存在）**：
+```json
+{ "code": 598801, "data": null, "message": "付款单不存在" }
+```
+
+---
+
+## 注意事项
+
+1. **详情两 tab 的数据分工**：详情信息 tab 仍调原详情接口；审核记录 tab 调本接口。两个接口独立，可并行/懒加载（切到审核记录 tab 再调）。
+2. **报账详情 `reviewLogs` 已 @Deprecated**：字段仍返回（向后兼容不回删），但新接入请改走 `GET /admin/finance/reimburses/{id}/review-logs`。字段语义与本接口一致。
+3. **追加写只增不删**：审核流水是完整历史轨迹（一张单反复审核/反审全程留痕），单据本体只留最终态。不要假设最多一条。
+4. **空态**：无审核记录返回空数组，前端「审核记录」tab 显示「暂无审核记录」占位即可。
+5. 审核动作在翻转单据状态的**同一事务**内落痕，状态翻转与留痕同生共死，不会出现「态已翻、痕没落」。
+
+---
+
+## 关联
+
+- Issue：https://git.1814.love:8443/wx/HL/issues/7801
+- PR：https://git.1814.love:8443/wx/HL/pulls/7814
+- 原型对齐：PR #7805（详情两 tab）/ #7808（查看纯只读权限分离）
+- 负责人：腰苏图