wx/hl-api-changelog

派生 0

文件

T

Mimingguang 84c22ea77a

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

详情

docs(changelogs-v2): #5955 verified(前端 9 卡尾款三口径适配)

2026-08-14 14:27:46 +08:00

19 KiB

原始文件 Blame 文件历史

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

schema	ticket	title	consumer	change_type	author	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	5955	主报账表baseInfo尾款口径透出三新字段+outstandingAmount下线	admin	修改接口	yst	deployed	verified	verified	mmg	c2783946		2026-08-14	PR #5958 已合并 dev-v3（commit cb40e197cb）。破坏性契约变化：baseInfo 删除 outstandingAmount（整单未收尾款），新增 receivableBalanceAmount（应收尾款）/ paidBalanceAmount（实收尾款）/ reporterPaidBalanceAmount（报账人实收尾款）；reporterNetAmount 保留为唯一带正负净额字段。仅出参变化，无入参/枚举/DDL 变化。	2026-08-14	dev-v3

【修改接口·管理后台】主报账表 baseInfo 尾款口径透出三新字段 + outstandingAmount 下线（#5955）

1. 接口背景

主报账人报账表（reimbursement）是管理后台订单核单页查看主报账人（通常是司机）代收、垫付支出、预支与净额结算情况的只读报表，baseInfo 块承载全部汇总金额。

此前 baseInfo 用 outstandingAmount（整单未收尾款，口径同核单应收财务总览）一个字段表达尾款情况，前端无法区分「应收多少尾款」「实际已收多少尾款」「其中主报账人线下代收了多少尾款」，做尾款对账展示时信息不够。

本次变更把尾款口径拆成三个权威字段直接透出，同时删除 outstandingAmount：未收尾款改由前端以「应收尾款 − 实收尾款」自算。报账人净额 reporterNetAmount 保留为唯一带正负的净额字段（正=报账人应转回公司，负=公司应补报账人），不再单出绝对值字段。

2. 变更清单

#	位置	变更	类型
1	baseInfo.outstandingAmount	字段删除：整单未收尾款不再透出，前端读到 undefined/键不存在	⚠️ 破坏性删除
2	baseInfo.receivableBalanceAmount	新增：应收尾款（调整后应收合计 − 已退 − 订金实收，负截 0）	✨ 新增字段
3	baseInfo.paidBalanceAmount	新增：实收尾款（payType∈{BALANCE,FULL} 已收：线上 SUCCESS 流水 + 线下手工收款）	✨ 新增字段
4	baseInfo.reporterPaidBalanceAmount	新增：报账人实收尾款（主报账人 channel=DRIVER_CASH 且 payType∈{BALANCE,FULL} 的线下收款合计）	✨ 新增字段
5	baseInfo.reporterNetAmount	保留，口径不变；强调其为唯一带正负净额字段，绝对值展示（如「公司应补报账人」）由前端按符号渲染	📝 口径声明（数值零漂移）
6	baseInfo.primaryReporterCollectedAmount	保留，口径不变（所有 channel=DRIVER_CASH 收款行合计）；与 reporterPaidBalanceAmount（仅其 BALANCE/FULL 尾款子集）语义不同	📝 口径声明（数值零漂移）

无入参变化、无新接口、无枚举/字典变化、无 DDL。组报 / finalize 门禁内部的 outstandingAmount 计算口径不受影响（仅本接口出参不再透出）。

3. 接口详情

项	值
方法 + 路径	GET /v3/admin/order/{orderId}/settlement/reports/reimbursement
接口名	查询主报账人报账表
使用场景	管理后台订单核单页，查看主报账人代收/垫付/预支/净额结算报表（含尾款三口径）
认证	管理后台 JWT（/v3/admin/* 走网关鉴权）
角色限制	房务角色（HOUSE）不可访问，调了会被 403 拦截
幂等性	只读查询，幂等
限流	走网关默认限流，无接口级特殊限流

4. 接口入参

4.1 路径参数

参数	类型	必填	说明
orderId	Long	是	订单 ID，必须大于 0（否则 400「订单 ID 必须大于 0」）

4.2 请求体 / Query

无请求体、无 Query 参数。

5. 出参字段

返回 Result<SettlementReimbursementReportRespVO>。顶层 4 个字段不变：baseInfo / incomeLines / expenseLines / advanceLines。本次仅 baseInfo 金额区变化，incomeLines / expenseLines / advanceLines 结构零变化。

5.1 baseInfo 全量字段表（变化字段加粗）

字段	类型	说明
id	Long(String)	核单记录 ID（settlement_recon.recon_id）；未生成时不输出该键
orderId	Long(String)	订单 ID
orderNo	String	订单号
teamNo	String	团号（订金未支付为 null，不输出该键）
productName	String	产品名
productType	String	产品类型枚举（如 CORE）
productTypeName	String	产品类型中文名（字典 product_type 回填）
customerName	String	客户姓名
departDate	String	出团日期，格式 yyyy-MM-dd
returnDate	String	返回日期，格式 yyyy-MM-dd
consultantName	String	定制师姓名
travelerCount	Integer	出行人总数（成人+儿童+幼童+婴儿，空档按 0 计）
travelerComposition	String	出行人构成（数量为 0 的档不显示，全空为 null），如「2大 1儿童 1幼童」
primaryReporterId	Long(String)	主报账人人员安排 ID
primaryReporterName	String	主报账人姓名
primaryReporterRole	String	主报账人角色（如 DRIVER）
primaryReporterCollectedAmount	BigDecimal	主报账人代收金额：所有 channel=DRIVER_CASH 收款行合计（含订金性质现金，不含 OTHER_INCOME 其他收入展示行），保留两位小数
approvedAdvanceAmount	BigDecimal	已审批预支金额（预支行合计），保留两位小数
reportablePaidCostAmount	BigDecimal	可报账已付成本（仅 CASH_PAID 现金垫付支出行合计，含 OTHER_EXPENSE 分类中的 CASH_PAID 行），保留两位小数
reporterNetAmount	BigDecimal	报账人净额 = 代收 + 预支 − 支出，保留两位小数；正=报账人应转回公司，负=公司应补报账人，0=两清。唯一净额字段，带正负
~~outstandingAmount~~	—	已删除：整单未收尾款不再透出（见 §10）
receivableBalanceAmount	BigDecimal	新增·应收尾款 = 调整后应收合计 − 已退 − 订金实收，负值截 0，保留两位小数。其中：订金实收 = 线上 SUCCESS 支付流水 + 线下手工收款中 payType=DEPOSIT 部分；调整后应收合计/已退口径同核单应收财务总览 adjustedReceivableAmount / actualRefundedAmount
paidBalanceAmount	BigDecimal	新增·实收尾款 = 已收且 payType∈{BALANCE, FULL} 的合计（线上 SUCCESS 支付流水 + 线下手工收款），保留两位小数。FULL 全款单无订金概念，首笔即全收，计入实收尾款
reporterPaidBalanceAmount	BigDecimal	新增·报账人实收尾款 = 主报账人 channel=DRIVER_CASH 且 payType∈{BALANCE, FULL} 且 collectorStaffId=主报账人的线下收款合计；无主报账人时为 0，保留两位小数

5.2 三新字段的派生关系（前端对账用）

receivableBalanceAmount（应收尾款）= 调整后应收合计 − 已退 − 订金实收（DEPOSIT 已收），负截 0
paidBalanceAmount（实收尾款）     = Σ 已收且 payType∈{BALANCE,FULL}（线上 SUCCESS + 线下手工）
reporterPaidBalanceAmount         = paidBalanceAmount 中「主报账人 DRIVER_CASH 线下代收」的子集
未收尾款（前端自算）              = max(0, receivableBalanceAmount − paidBalanceAmount)

与 primaryReporterCollectedAmount 的区别：代收（collected）含主报账人所有 DRIVER_CASH 收款（含 payType=DEPOSIT 的订金现金）；reporterPaidBalanceAmount 只算其中 BALANCE/FULL 尾款部分。订单存在「主报账人代收订金现金」时两者会分叉，属预期。

6. 枚举 / 数据字典

本次无新增枚举/字典。涉及的既有枚举（仅用于理解口径，不在 baseInfo 出参里）：

枚举	取值	说明
PayType（款项类型）	DEPOSIT（订金）/ FULL（全款）/ BALANCE（尾款）	实收尾款口径 = BALANCE + FULL；订金实收口径 = DEPOSIT
收款渠道	DRIVER_CASH（报账人现金）/ BANK_TRANSFER / CONSULTANT_COLLECTION	reporterPaidBalanceAmount 只算 DRIVER_CASH 且收款人=主报账人

7. 错误码

本次无新增错误码，沿用既有：

code	message	触发场景
400	订单 ID 必须大于 0	orderId 路径参数校验失败
403	无权限访问	房务角色（HOUSE）JWT 调用
581007	订单不存在	orderId 查不到订单

8. 示例

8.1 典型成功（订金单部分付尾款，含主报账人 DRIVER_CASH 尾款代收）

场景：调整后应收 10000，已退 0，订金实收 2000（线上 SUCCESS）→ 应收尾款 8000；尾款已收 2200（线上 1700 + 主报账人现金代收 500）。

GET /v3/admin/order/2087088947225038849/settlement/reports/reimbursement

{
  "code": 200,
  "message": "成功",
  "data": {
    "baseInfo": {
      "id": "6001",
      "orderId": "2087088947225038849",
      "orderNo": "HL20260730001",
      "teamNo": "T20260730001",
      "productName": "呼伦贝尔草原 5 日游",
      "productType": "CORE",
      "productTypeName": "核心产品",
      "customerName": "张三",
      "departDate": "2026-07-30",
      "returnDate": "2026-08-03",
      "consultantName": "李四",
      "travelerCount": 4,
      "travelerComposition": "2大 2儿童",
      "primaryReporterId": "7001",
      "primaryReporterName": "司机甲",
      "primaryReporterRole": "DRIVER",
      "primaryReporterCollectedAmount": 500.00,
      "approvedAdvanceAmount": 300.00,
      "reportablePaidCostAmount": 100.00,
      "reporterNetAmount": 700.00,
      "receivableBalanceAmount": 8000.00,
      "paidBalanceAmount": 2200.00,
      "reporterPaidBalanceAmount": 500.00
    },
    "incomeLines": [
      {
        "type": "DRIVER_CASH_RECEIPT",
        "typeName": "司机现金收款",
        "receiptId": "8001",
        "amount": 500.00,
        "channel": "DRIVER_CASH",
        "channelName": "报账人收款",
        "payType": "BALANCE",
        "payTypeName": "尾款",
        "collectorStaffId": "7001",
        "collectorName": "司机甲",
        "collectorRole": "DRIVER",
        "collectorRoleName": "司机",
        "receivedAt": "2026-07-30 18:20:30",
        "remark": "尾款现金"
      }
    ],
    "expenseLines": [],
    "advanceLines": []
  },
  "success": true
}

前端展示：未收尾款 = max(0, 8000 − 2200) = 5800.00（自算）；reporterNetAmount=700.00>0 → 「报账人应转回公司 700.00」。

8.2 边界情况（FULL 全款单，首笔即全收 + 全额已付后再部分退款）

场景：FULL 全款单 5000 线上一次付清，无订金概念。应收尾款 = 5000 − 0 − 0（无 DEPOSIT 实收）= 5000；实收尾款 = 5000（FULL 计入）；未收尾款自算 = 0。若此后部分退款 1000，应收尾款冲减为 4000、实收仍 5000，自算未收尾款为负 → 前端必须 max(0, ·) 截 0 展示：

{
  "baseInfo": {
    "orderId": "2087088947225038849",
    "orderNo": "HL20260801002",
    "primaryReporterName": "司机乙",
    "primaryReporterRole": "DRIVER",
    "primaryReporterCollectedAmount": 0.00,
    "approvedAdvanceAmount": 0.00,
    "reportablePaidCostAmount": 0.00,
    "reporterNetAmount": 0.00,
    "receivableBalanceAmount": 4000.00,
    "paidBalanceAmount": 5000.00,
    "reporterPaidBalanceAmount": 0.00
  }
}

边界要点：reporterNetAmount=0 → 两清；reporterPaidBalanceAmount=0（主报账人没有线下代收尾款）；未收尾款展示 0.00（负值截 0）。

8.3 业务失败（字段已删——历史代码读 outstandingAmount 拿到 undefined）

修改后 baseInfo 不再包含 outstandingAmount 键（不是 null，是键不存在）。前端旧代码 baseInfo.outstandingAmount 读到 undefined，若直接参与渲染/计算会出现「undefined元」或 NaN——必须改为三新字段：

{
  "baseInfo": {
    "orderId": "2087088947225038849",
    "reporterNetAmount": 700.00,
    "receivableBalanceAmount": 8000.00,
    "paidBalanceAmount": 2200.00,
    "reporterPaidBalanceAmount": 500.00
  }
}

另附通用业务失败响应（与修改前一致）：

{ "code": 403, "message": "无权限访问", "success": false }

{ "code": 581007, "message": "订单不存在", "success": false }

9. 业务边界

适用：

核单页查看主报账人结算全貌 + 尾款三口径（应收/实收/报账人实收），未收尾款由前端自算展示。

不适用：

组报 / finalize 门禁判断 —— 内部仍用 outstandingAmount 口径，但那是服务端逻辑，前端无需关心，也不要再试图从本接口读它。

特殊边界（前端必知）：

outstandingAmount 已删，不是 null 是键不存在：VO 带 @JsonInclude(NON_NULL)，删除后该键彻底不下发。旧代码读到 undefined，必须改。
历史 finalize 快照无新三字段：查看本次上线前生成的旧结算快照时，receivableBalanceAmount / paidBalanceAmount / reporterPaidBalanceAmount 三键为 null（不下发），前端需容忍空态展示（如「--」）。
前端自算未收尾款可为负：「全额已付后再部分退款」场景下应收尾款−实收尾款为负，展示时必须 max(0, ·)。
净额方向：reporterNetAmount > 0 → 报账人欠公司（应转回）；< 0 → 公司欠报账人（应补）；= 0 → 两清。界面「公司应补报账人」等绝对值文案由前端按符号渲染，后端不再单出绝对值字段。
代收 ≠ 报账人实收尾款：primaryReporterCollectedAmount 含订金性质现金（DEPOSIT）；reporterPaidBalanceAmount 只含 BALANCE/FULL。两者在「主报账人代收过订金现金」时分叉，属预期，不要互相校验相等。

10. 修改前后对比

10.1 字段级对比

位置	字段	修改前	修改后
baseInfo	outstandingAmount	整单未收尾款（口径同财务总览）	已删除（键不再下发）
baseInfo	receivableBalanceAmount	无	新增：应收尾款（调整后应收 − 已退 − 订金实收，负截 0）
baseInfo	paidBalanceAmount	无	新增：实收尾款（BALANCE/FULL 已收，线上 SUCCESS + 线下手工）
baseInfo	reporterPaidBalanceAmount	无	新增：报账人实收尾款（主报账人 DRIVER_CASH 的 BALANCE/FULL 子集）
baseInfo	reporterNetAmount	报账人净额（带正负）	口径不变，明确为唯一净额字段
baseInfo	primaryReporterCollectedAmount	主报账人代收	口径不变
baseInfo	其余字段	原样	零变化

10.2 行为级对比

场景	修改前	修改后
未收尾款展示	直接读 baseInfo.outstandingAmount	前端自算 max(0, receivableBalanceAmount − paidBalanceAmount)
FULL 全款单尾款口径	outstandingAmount 一个数，无细分	应收=调整后应收（无订金可减），实收含 FULL 首笔全额，自算未收=0
主报账人代收了多少尾款	无法区分（代收含订金现金混在一起）	reporterPaidBalanceAmount 直接给出 BALANCE/FULL 子集
历史 finalize 快照	含 outstandingAmount	旧快照无新三字段（键为 null 不下发），前端空态容忍

11. 影响评估 / 回滚

11.1 影响评估

破坏兼容性：⚠️ 破坏性变更。baseInfo 删除 outstandingAmount 字段，凡读取该字段的前端代码必须改造；新增三字段对不读旧字段的页面无影响。
前端是否必须同步上线：是（针对 outstandingAmount 消费点）。后端上线后 outstandingAmount 立即消失，读它的界面会显示 undefined/空白，前端三新字段改造需与后端同窗口上线。
改造点清单：
1. 删 baseInfo.outstandingAmount 的所有读取，未收尾款改自算 max(0, receivableBalanceAmount − paidBalanceAmount)；
2. 新增应收尾款 / 实收尾款 / 报账人实收尾款三处展示（按产品 UI 需要）；
3. 「公司应补报账人」等绝对值展示按 reporterNetAmount 符号渲染；
4. 历史快照空态容忍（三新字段键可能不存在）。
无 DDL、无枚举、无字典变更，无其他服务依赖。

11.2 回滚方案

后端回滚 = revert PR #5958 的 commit（cb40e197cb），重启 hl-order-service-v3，outstandingAmount 恢复透出、三新字段消失。
前端若已按新字段上线而后端回滚，三新字段读到 undefined → 前端回滚需同步；建议前后端同窗口切换。
零 DDL / 零数据迁移，回滚无数据残留风险。

12. 注意事项

NON_NULL 省略：baseInfo 带 @JsonInclude(NON_NULL)，null 字段不下发该键（不是下 null）；旧快照的三新字段、未生成核单的 id、未付订金的 teamNo 都是「键不存在」，前端读取必须兜底。
Long 主键序列化为字符串（id / orderId / primaryReporterId 等），前端按 string 处理，不要 Number() 转换。
金额保留两位小数，BigDecimal JSON 输出为 number（如 8000.00），前端展示格式化自行处理。
汇总只读 baseInfo：三新字段与 reporterNetAmount 都是后端算好的权威值，前端不要拿 incomeLines 数组自算尾款（收款行还含 DEPOSIT，口径不同必然对不上）。
组报 / finalize 门禁内部 outstandingAmount 口径不受本变更影响，无需前端配合。
本变更只影响 reimbursement 报账表的 baseInfo；incomeLines / expenseLines / advanceLines 结构零变化，单团核算表（reports/group）不受影响。

13. 关联 / 联系人

Issue #5955：https://git.1814.love:8443/wx/HL/issues/5955
PR #5958：https://git.1814.love:8443/wx/HL/pulls/5958
Commit：https://git.1814.love:8443/wx/HL/commit/cb40e197cb
服务：hl-order-service-v3（端口 8086）
后端负责人：yst（腰苏图）

14. 验证证据

后端单测：SettlementReportFlowServiceTest / SettlementControllerTest 补 FULL 全款单、部分退款、混合拆分类边界用例（实收尾款含 FULL、应收尾款负截 0、报账人 DRIVER_CASH+BALANCE/FULL 子集口径），PR #5958 已合并 dev-v3（commit cb40e197cb）。
代码已合并 dev-v3 并部署测试服。
前端联调验证点：旧 outstandingAmount 消费点全部改造；§8.1 典型场景未收尾款自算 = 5800.00；§8.2 FULL 单部分退款后自算负值截 0 展示；历史快照三新字段空态不报错。

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