---
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: "not_required"
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）。[mmg 2026-09-17 判 not_required] 前端全仓无任何 settlement/confirm 调用点（grep 实证：路径/confirmSettlement/584065 均零命中），「待财务复核」仅 DetailHero 状态 tag 展示；changelog 建议的「成功提示带 reimburseNo + 跳转报账详情」以复核调用方存在为前提，本端不适用。报账款域已有独立复核管理页（finance/payable/reimburse，#7721/#7764 已交付）经自身列表/详情接口消费 reimburseNo，无需从复核出参跳转。纯出参新增向后兼容，不消费即无感。"
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）
- 后端负责人: 腰苏图