wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-07/07_4780_核单submit收口-修改接口-管理后台.md

5.2 KiB
原始文件 Blame 文件历史

核单 Step 6 submit 收口务 (修改接口)

  • 变更日期: 2026-07-07
  • 端类型: 管理后台
  • 变更类型: 修改接口
  • Issue: wx/HL#4780
  • PR: wx/HL#4783

1. 接口背景

核单 epic PR5。 Step 6 submit (POST /v3/admin/order/{orderId}/settlement/step6/submit) 有两项修改：

  1. 出参新增 warnings 字段（软预警列表）: 软预警不阻塑提交，提交定制师补传凭证
  2. orderStatusAfter 値变更: 将 "已结算" 改为 "待财务复核"

submit 阈条件新增 (任一不满即返错误）:

  • 584081: recon 对账数据不完整 (财务人员要地接确认尾款）)
  • 584082: 尾款未收全 (customerCashCollectedFlag=false 时)
  • 584083: 转账未完成 (transferStatus != COMPLETED 时)
  • 584084: 预支未冲扣 (advanceSettledFlag=false 时)
  • 584085: payout 未全部 COMPLETED （有人员尚未抨款）)

2. 变更清单

变更项 内容
orderStatusAfter "已结算" -> "待财务复核" （❗ 破坏兆容）
新增 warnings List, 软预警列表，不阻塑，可空
submit 阈条件 584081/084082/584083/584084/584085 新增

3. 接口详情

项 说明
方法 POST
路径 /v3/admin/order/{orderId}/settlement/step6/submit
认证 JWT Bearer(管理端)
幂等性 非幂等（重复提交不幂)
核单状态 settlement_status=IN_PROGRESS

4. 接口入参

4.1 路径参数

| orderId | Long | 是 | 订单 ID |

4.2 请求体

无 (空请求体)

5. 出参字段（SettlementSubmitRespVO）

字段 类型 说明
summaryId Long settlement_summary 主键
orderId Long 订单 ID
settledAt LocalDateTime 核单完成时间
totalAmount BigDecimal 订单总金额快照
paidAmount BigDecimal 已付金额快照
balanceAmount BigDecimal 尾款金额
roomCost BigDecimal 住宿实际成本
ticketCost BigDecimal 门票实际成本
staffCost BigDecimal 人员费用实际成本
subsidyCost BigDecimal 补助实际成本
insurancePremium BigDecimal 保险实际保费
totalActualCost BigDecimal 总实际成本=四子表+保险
driverTransferAmount BigDecimal 给司机转账金额
profitAmount BigDecimal 公司毛利
profitRate BigDecimal 毛利率（小数）
orderStatusAfter String ❗ 广报 "待财务复核" (修改前: "已结算")
mqTriggered Boolean OrderSettledEvent 是否触发成功
warnings List ✨ 新增: 软预警, 不阻塑, null=无预警

6. 枚举/数据字典

无枚举字段。 orderStatusAfter 是文本展示.

7. 错误码

错误码 含义 触发场景
584081 recon 对账数据不完整 未完全填写 recon 数据
584082 尾款未收 customerCashCollectedFlag=false
584083 转账未完成 transferStatus != COMPLETED
584084 预支未冲扣 advanceSettledFlag=false
584085 payout 未封 COMPLETED 有人员尚未抨款

8. 示例

8.1 典型成功 -- 提交后带 warnings

{
  "code": 200,
  "data": {
    "summaryId": 9600000000001,
    "orderId": 1234567890123456,
    "orderStatusAfter": "待财务复核",
    "totalAmount": 24800.00,
    "paidAmount": 24800.00,
    "balanceAmount": 0.00,
    "totalActualCost": 23120.00,
    "profitAmount": 1680.00,
    "profitRate": 0.0677,
    "mqTriggered": true,
    "warnings": ["住宿 D2 现付缺凭证"]
  }
}

8.2 边界 -- warnings 为空，全部验完整

{
  "code": 200,
  "data": {
    "orderStatusAfter": "待财务复核",
    "mqTriggered": true,
    "warnings": null
  }
}

8.3 业务失败 -- recon 未完全填写触发 584081

{
  "code": 584081,
  "msg": "对账数据不完整，请先完善 recon 信息"
}

9. 业务边界

适用: settlement_status=IN_PROGRESS 不适用: 已提交或已结算 特殊边界:

  • warnings 列表不为空时，定制师详阅并处理（如补传凭证）

10. 修改前后对比

字段 / 行为 修改前 修改后
orderStatusAfter "已结算" "待财务复核"
warnings 无 List （可空，软预警列表）
submit 阈条件 仅 SETTLEMENT_STATUS_NOT_IN_PROGRESS +584081~584085

11. 影响评估/回滚

破坏兆容: orderStatusAfter 变为 "待财务复核" -- 前端如果硬编 "已结算" 却仅需更新判断逻辑。

前端同步上线:

  • 提交后状态按 "待财务复核" 展示，不再 "已结算"
  • warnings 非空时展示提示，建议定制师补传凯缺凭证

回滚方案: 无需回滚，状态变更属正常业务流程变更。

12. 注意事酹

  • orderStatusAfter 修改是 破坏兆容变更，前端需更新判断逻辑
  • warnings 列表需备意 null (展示套带信息或展示 toast)

13. 关联/联系人