wx/hl-api-changelog

派生 0

文件

T

Mimingguang 778d618ef4

changelog-filename-gate / validate (push) Failing after 1s

详情

chore(changelog): #7724 核单复核出参判 not_required(前端无复核调用点)

2026-09-17 23:52:43 +08:00

9.5 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	settlement-confirm-add-reimburse-fields	核单复核确认结算出参新增报账字段（reimburseId / reimburseNo）	admin	yst(GIT)	修改接口	merged	pending	not_required				2026-09-17	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，无需从复核出参跳转。纯出参新增向后兼容，不消费即无感。	2026-09-17	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 典型成功

请求：

POST /v3/admin/order/12345678901234/settlement/confirm
Content-Type: application/json

{
  "confirmRemark": "核对无误，确认结算"
}

响应：

{
  "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 做特殊分支：

{
  "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（订单已结算完成后再次调用）。响应：

{
  "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 ?? ''）

十二、注意事项

reimburseId 是字符串化 Long（防 JS Number 精度丢失），请按字符串接收，不要 Number() 转换后传回后端
reimburseNo 格式固定 BZ- + 8 位日期 + 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）
后端负责人: 腰苏图

9.5 KiB 原始文件 Blame 文件历史 Unescape Escape