From 28effce68e0006f33ff64842ce606b427aca3c69 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Thu, 17 Sep 2026 23:40:33 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E6=A0=B8=E5=8D=95=E5=A4=8D?= =?UTF-8?q?=E6=A0=B8=E5=87=BA=E5=8F=82=E5=8A=A0=E6=8A=A5=E8=B4=A6=E5=AD=97?= =?UTF-8?q?=E6=AE=B5=EF=BC=88Issue=20#7724=20/=20PR=20#7725=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...单复核出参加报账字段-修改接口-管理后台.md | 208 ++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 changelogs-v2/2026-09/17_7724_核单复核出参加报账字段-修改接口-管理后台.md diff --git a/changelogs-v2/2026-09/17_7724_核单复核出参加报账字段-修改接口-管理后台.md b/changelogs-v2/2026-09/17_7724_核单复核出参加报账字段-修改接口-管理后台.md new file mode 100644 index 00000000..421cec1a --- /dev/null +++ b/changelogs-v2/2026-09/17_7724_核单复核出参加报账字段-修改接口-管理后台.md @@ -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`，`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） +- 后端负责人: 腰苏图