docs(changelog): 核单复核出参加报账字段（Issue #7724 / PR #7725）

2026-09-17 23:40:33 +08:00
@@ -0,0 +1,208 @@
+---
+schema: "hl-changelog/v2"
+ticket: "settlement-confirm-add-reimburse-fields"
+title: "核单复核确认结算出参新增报账字段（reimburseId / reimburseNo）"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "修改接口"
+backend_status: "merged"
+gateway_status: "pending"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-17"
+status_note: "POST /v3/admin/order/{orderId}/settlement/confirm 出参 ConfirmSettlementRespVO 纯新增 2 字段（reimburseId 字符串化 Long / reimburseNo BZ- 单号），复核通过同事务直连 hl-finance 生成 BZ 报账执行单；入参/既有出参/错误码零变化，非破坏性。后端已合并 dev-v3（PR #7725）。"
+updated_at: "2026-09-17"
+base: "dev-v3"
+---
+
+# 核单复核确认结算出参新增报账字段（管理后台）
+
+> **服务**: hl-order-service-v3（settlement 模块）
+> **类型**: 🔧 修改接口（出参纯新增字段，向后兼容）
+> **日期**: 2026-09-17
+> **影响范围**: 管理后台财务域「核单 / 结算复核」确认动作；配套「付款管理 / 报账款」详情跳转
+> **关联**: Issue #7724 / PR #7725 / Epic #7721 PR-2
+
+---
+
+## 一、接口背景
+
+「财务复核确认结算」是订单结算链路的最后一步：财务在管理后台核对终态快照无误后调用本接口，订单 `settlement_status` 由 `PENDING` → `COMPLETED`、`flow_status` 由 `PENDING_SETTLE` → `SETTLED`，结算完成。
+
+Epic #7721 PR-2 起，复核通过的**同一事务内**后端直连 hl-finance 生成 BZ 报账执行单（付款管理 / 报账款域）。本次在该接口出参中补出报账执行单 ID 与报账单号，前端复核成功后可直接提示「已生成报账单 BZ-xxx」并跳转报账款详情页。
+
+## 二、变更清单
+
+| # | 类型 | 接口 | 变更点 |
+|---|------|------|--------|
+| 1 | 🔧 修改接口 | `POST /v3/admin/order/{orderId}/settlement/confirm` | 出参 `ConfirmSettlementRespVO` 新增 2 字段：`reimburseId`（字符串化 Long）、`reimburseNo`（BZ- 单号） |
+
+入参、路径、既有出参字段、错误码**零变化**，属非破坏性出参新增。
+
+## 三、接口详情
+
+| 项 | 值 |
+|---|---|
+| 方法 + 路径 | `POST /v3/admin/order/{orderId}/settlement/confirm` |
+| 接口名 | 财务复核确认结算 |
+| 使用场景 | 订单核单完成（`review_status=COMPLETED`）且待财务复核（`settlement_status=PENDING`、`flow_status=PENDING_SETTLE`）时，财务确认结算 |
+| 认证 | 管理后台 JWT；复核人身份走请求头 `X-Admin-Id` / `X-Admin-RealName`（网关注入，不在 body 重复）；服务端校验财务写权限 |
+| 幂等性 | **非幂等**。重复调用第二次命中错误码 584065（结算状态已非 PENDING） |
+| 限流 | 走网关默认限流规则，无接口级特殊限流 |
+
+## 四、接口入参
+
+### 4.1 路径参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `orderId` | Long | 是 | 订单 ID |
+
+### 4.2 请求体字段（ConfirmSettlementReqVO）
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `confirmRemark` | String | 否 | 复核备注 | `核对无误，确认结算` |
+
+## 五、出参字段
+
+返回 `Result<ConfirmSettlementRespVO>`，`data` 字段表（✨ = 本次新增）：
+
+| 字段 | 类型 | 说明 | 示例 |
+|------|------|------|------|
+| `orderId` | Long(number) | 订单 ID | `12345678901234` |
+| `settlementStatus` | String | 结算状态，成功固定 `COMPLETED` | `COMPLETED` |
+| `settledAt` | String(LocalDateTime) | 结算完成时间 | `2026-09-17T10:30:25` |
+| `flowStatus` | String | 结算后流程状态，成功固定 `SETTLED` | `SETTLED` |
+| `reimburseId` ✨ | **String**（Long 已 `@JsonSerialize(ToStringSerializer)` 字符串化，防 JS 精度丢失） | 报账执行单 ID，复核通过同事务生成 | `"19567890123456"` |
+| `reimburseNo` ✨ | String | 报账单号，格式 `BZ-` + `yyyyMMdd` + 4 位序号 | `BZ-202609150001` |
+
+## 六、枚举 / 数据字典
+
+| 字段 | 取值 | 说明 |
+|------|------|------|
+| `settlementStatus` | `COMPLETED` | 本接口成功响应固定值（前置状态为 `PENDING`） |
+| `flowStatus` | `SETTLED` | 本接口成功响应固定值（前置状态为 `PENDING_SETTLE`） |
+| `reimburseNo` 格式 | `BZ-yyyyMMddNNNN` | 例 `BZ-202609150001`，按日自增 4 位序号 |
+
+## 七、错误码
+
+| 错误码 | 含义 | 触发条件 |
+|--------|------|----------|
+| 584065 | 当前结算状态为「{0}」，不允许执行财务复核，必须为「待财务复核」 | `settlement_status` 非 PENDING（含重复复核） |
+| 584066 | 订单流程状态不一致（流程状态与结算阶段不匹配），操作已回滚 | `flow_status` 非 `PENDING_SETTLE`，CAS 推进失败 |
+| 584321 | 当前订单缺少核单终态快照，请重新完成核单 | 无当前终态快照 |
+| 584326 | 核单终态快照已变化，请刷新后重试 | 快照漂移 / 核单审核状态非 COMPLETED |
+
+另有：**报账推送失败时整个复核事务回滚**（fail-fast，不留「已结算无报账单」尾巴），订单停留在 `PENDING` 可修正后重试；此时按返回的业务错误码提示处理。
+
+## 八、示例
+
+### 8.1 典型成功
+
+请求：
+
+```http
+POST /v3/admin/order/12345678901234/settlement/confirm
+Content-Type: application/json
+
+{
+  "confirmRemark": "核对无误，确认结算"
+}
+```
+
+响应：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "orderId": 12345678901234,
+    "settlementStatus": "COMPLETED",
+    "settledAt": "2026-09-17T10:30:25",
+    "flowStatus": "SETTLED",
+    "reimburseId": "19567890123456",
+    "reimburseNo": "BZ-202609170001"
+  },
+  "msg": "success"
+}
+```
+
+### 8.2 边界情况（应收应付净额 = 0）
+
+净额为 0 的订单**也会生成**报账执行单（BALANCED 两清单，不进出纳队列），`reimburseId` / `reimburseNo` 照常返回，前端无需对净额 0 做特殊分支：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "orderId": 12345678901235,
+    "settlementStatus": "COMPLETED",
+    "settledAt": "2026-09-17T11:02:10",
+    "flowStatus": "SETTLED",
+    "reimburseId": "19567890123500",
+    "reimburseNo": "BZ-202609170002"
+  },
+  "msg": "success"
+}
+```
+
+### 8.3 业务失败（重复复核，命中 584065）
+
+请求同 8.1（订单已结算完成后再次调用）。响应：
+
+```json
+{
+  "code": 584065,
+  "data": null,
+  "msg": "当前结算状态为「已结算」，不允许执行财务复核，必须为「待财务复核」"
+}
+```
+
+## 九、业务边界
+
+- **适用**：订单 `settlement_status=PENDING` 且 `review_status=COMPLETED` 且 `flow_status=PENDING_SETTLE`，且存在当前生效的核单终态快照（`snapshot_status=FINALIZED` 且 `current_flag=1`）
+- **不适用**：已结算订单（584065）、终态快照缺失（584321）、快照已漂移或核单被反确认（584326）
+- **特殊**：报账推送与复核状态写库在**同一事务**，推送失败整体回滚，订单停留 `PENDING`，修正后可安全重试，不会产生半提交状态
+
+## 十、修改前后对比
+
+### 10.1 字段级对比（ConfirmSettlementRespVO）
+
+| 字段 | 修改前 | 修改后 |
+|------|--------|--------|
+| `orderId` / `settlementStatus` / `settledAt` / `flowStatus` | 有 | 有（不变） |
+| `reimburseId` | 无 | ✨ 新增，String（字符串化 Long） |
+| `reimburseNo` | 无 | ✨ 新增，String，`BZ-yyyyMMddNNNN` |
+
+### 10.2 行为级对比
+
+| 维度 | 修改前 | 修改后 |
+|------|--------|--------|
+| 复核通过副作用 | 仅更新订单结算状态 + 状态流水 | 同一事务额外直连 hl-finance 生成 BZ 报账执行单 |
+| 报账生成失败 | 不涉及 | 复核整体回滚（fail-fast），订单停留 PENDING 可重试 |
+| 净额 = 0 订单 | 不涉及 | 也生成 BALANCED 报账单（不进出纳队列），出参照常返回 |
+
+## 十一、影响评估 / 回滚
+
+- **兼容性**：非破坏性纯出参新增，前端不改动可正常工作
+- **前端建议**：复核成功提示中带出 `reimburseNo`；如「报账款」详情页已上线，可用 `reimburseId` / `reimburseNo` 跳转
+- **是否需同步上线**：否，前端可按自己的节奏接入
+- **回滚方案**：后端回退 PR #7725 后 2 个新字段消失，前端读取需判空（`resp.data.reimburseNo ?? ''`）
+
+## 十二、注意事项
+
+1. `reimburseId` 是**字符串化 Long**（防 JS Number 精度丢失），请按字符串接收，不要 `Number()` 转换后传回后端
+2. `reimburseNo` 格式固定 `BZ-` + 8 位日期 + 4 位序号，可直接展示
+3. 复核成功但报账推送失败时**整个复核失败回滚**（接口返回错误），前端按错误提示引导财务重试即可，不会出现「结算成功但没报账单」
+4. 复核备注 `confirmRemark` 可选，不传也能成功
+
+## 十三、关联 / 联系人
+
+- Issue: https://git.1814.love:8443/wx/HL/issues/7724
+- PR: https://git.1814.love:8443/wx/HL/pulls/7725
+- Commit: https://git.1814.love:8443/wx/HL/commit/40f08d9be4
+- Epic: https://git.1814.love:8443/wx/HL/issues/7721（报账款 PR-2）
+- 后端负责人: 腰苏图