hl-api-changelog/changelogs-v2/2026-08/11_5816_主报账对账去transferStatus-修改接口-管理后台.md

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	5816	主报账对账 transferStatus 彻底下线：报账表出参删字段，recon 读/写路径正式声明下线（404）	admin	修改接口	yaosutu(GIT)	deployed	not_required	verified	mmg	b22d6c14		2026-09-18	前端已实现(b22d6c14):实证 transferStatus 在视图层零引用、getSettlementRecon/saveSettlementRecon 无生产调用方(转账状态流转不再走核单链路),删 orderV2.js 这两个 recon 死导出及 jsdoc,改下线注记;reconNetAmount 等派生金额由报账表接口透出不受影响,报账表 jsdoc 补 #5816 出参再删 transferStatus 说明。软破坏(少字段不报错),前端不读即兼容。orderV2.spec 13 全过,checkpoint 单文件全绿(ESLint/Vitest 全量/生产构建)。[mmg 2026-09-18 批量复核翻 verified] ref b22d6c14 可达且为 v2.1 祖先;交付文件 HEAD 均在;关联 spec 批量 891 例全绿。	2026-09-18	dev-v3

【⚠️ 修改接口·管理后台】主报账对账 transferStatus 彻底下线：报账表出参删 transferStatus，recon 读/写路径正式声明下线（#5816）

PR: #5826 | 服务: hl-order-service-v3 | 更新时间: 2026-08-11

1. 接口背景

主报账对账（recon）的「转账状态」（待转账 PENDING / 已转账 COMPLETED）此前挂在核单链路维护：主报账人报账表出参带 transferStatus，配套有 recon 读 / 写两个接口。产品上决定转账状态流转不再由核单链路承载，本次把 transferStatus 从对外契约彻底摘除，并清理 recon 幽灵接口的残留死代码：

• 主报账人报账表（GET reports/reimbursement）：出参删除 transferStatus 字段（#5809 批次删凭据字段时该字段曾保留，本次一并下线）；
• recon 写接口（PUT /v3/admin/order/{orderId}/settlement/recon）：正式声明下线。该路径自 2026-07-22 核单接口收口起已无服务端入口，本次清理其入参类与写路径死代码，调用返回 404；
• recon 读接口（GET /v3/admin/order/{orderId}/settlement/recon）：同样早已无服务端入口（404），其派生金额数据（reconNet 等）仍通过报账表接口内嵌透出，不受本次变更影响。

2. 变更清单

#	接口	方法	路径	变更类型	前端动作
1	主报账人报账表	GET	/v3/admin/order/{orderId}/settlement/reports/reimbursement	出参删 transferStatus	停读该字段；清理转账状态展示 / workaround
2	主报账对账保存	PUT	/v3/admin/order/{orderId}/settlement/recon	接口下线（早已无入口，本次清死代码正式声明）	停调；调用返回 404
3	主报账对账查询	GET	/v3/admin/order/{orderId}/settlement/recon	接口下线（同上，早已无入口）	停调；调用返回 404

3. 接口详情

• 使用场景：管理后台核单页「主报账人报账表」弹窗，展示主报账人收付对账与净额结论（reconNetAmount 等派生金额保留不变）。
• 认证：需要管理后台登录态（Bearer Token）；房务角色（HOUSE）被 OrderViewGuard 拦截。
• 幂等性：只读查询，天然幂等。
• 限流：未声明接口专属限流。
• 网关：无网关路由变更。

4. 接口入参

入参零变化。

4.1 路径参数

参数	类型	必填	说明
orderId	Long	是	订单 ID，路径参数，必须大于 0

4.2 请求体字段

无请求体、无 Query 参数。

5. 出参字段

GET /v3/admin/order/{orderId}/settlement/reports/reimbursement，统一响应 Result 包装，data 字段如下（仅列关键字段 + 本次删除项）：

字段	类型	说明
id	String(Long)	报表记录 ID；未落库时可为 null
orderId	String(Long)	订单 ID
reportStatus	String	报表状态：GENERATED / CONFIRMED
primaryReporterId	String(Long)	主报账人人员安排 ID
primaryReporterName	String	主报账人姓名
primaryReporterRole	String	主报账人角色（如 DRIVER）
reportVersion	Integer	报表版本号
driverCollectedTailAmount	String(BigDecimal)	司机代收尾款
approvedAdvanceAmount	String(BigDecimal)	已审批预支金额
reportablePaidCostAmount	String(BigDecimal)	可报账已付成本
reporterNetAmount	String(BigDecimal)	报账人净额
primaryReporterCollectedAmount	String(BigDecimal)	主报账人已收款
publicPrepaidAmount	String(BigDecimal)	对公预付金额
primaryReporterDueAmount	String(BigDecimal)	主报账人应结金额
advanceOutstandingAmount	String(BigDecimal)	预支未销余额
reconNetAmount	String(BigDecimal)	对账净额（保留不变）
transferDirection	String	转账方向
transferAmount	String(BigDecimal)	转账金额
incomeLines	Array	收款行；每项含 type / typeName / receiptId / amount / channel / channelName / payType / payTypeName / collectorStaffId / collectorName / collectorRole / collectorRoleName / receivedAt / remark
expenseLines	Array	支出行；每项含 kind / category / categoryName / amount / paymentMethod / paymentMethodName / voucherUrls / remark + 类别扩展字段
advanceLines	Array	预支行
vehicleLines	Array	已确认车辆逐日费用明细；无数据固定返回空数组
transferStatus	-	已删除，前端不再收到此字段（不是返回 null，是字段不存在）
generatedBy / generatedByName / generatedAt	-	生成人 ID / 姓名 / 时间
confirmedBy / confirmedByName / confirmedAt	-	确认人 ID / 姓名 / 时间

除删除 transferStatus 外，其余字段名称、类型、语义均无变化。金额 / 收款派生字段（reconNetAmount、driverCollectedTailAmount 等）保留不变。

6. 枚举 / 数据字典

transferStatus（本次从对外契约彻底消失）

值	原含义	本次变化
PENDING	待转账	随字段一起从出参消失，不再有任何接口返回
COMPLETED	已转账	随字段一起从出参消失，不再有任何接口返回

其余枚举/字典（reportStatus、incomeLines[].type、channel、payType、paymentMethod、transferDirection 等）取值与语义均无变化。

7. 错误码

错误码	含义	本次变化
404	路径不存在	旧 recon 路径触发：PUT / GET /v3/admin/order/{orderId}/settlement/recon 早已无服务端入口，调用返回 404
-	原 transferStatus 校验相关错误码	不再触发（码位保留下线、不复用，对外契约不删号）

其余既有错误码（订单不存在、双报告未生成保护 584311 / 584313、房务角色 403 等）行为不变。

8. 示例

8.1 典型成功（报账表出参已无 transferStatus）

GET /v3/admin/order/2084000000000002978/settlement/reports/reimbursement
Authorization: Bearer <token>

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "8802",
    "orderId": "2084000000000002978",
    "reportStatus": "CONFIRMED",
    "primaryReporterId": "7001",
    "primaryReporterName": "司机甲",
    "primaryReporterRole": "DRIVER",
    "reportVersion": 2,
    "driverCollectedTailAmount": "500.00",
    "approvedAdvanceAmount": "200.00",
    "reportablePaidCostAmount": "300.00",
    "reporterNetAmount": "-600.00",
    "primaryReporterCollectedAmount": "500.00",
    "publicPrepaidAmount": "300.00",
    "primaryReporterDueAmount": "600.00",
    "advanceOutstandingAmount": "200.00",
    "reconNetAmount": "-600.00",
    "transferDirection": "COMPANY_TO_REPORTER",
    "transferAmount": "600.00",
    "incomeLines": [
      {
        "type": "DRIVER_CASH",
        "typeName": "司机代收",
        "receiptId": "9001",
        "amount": "500.00",
        "channel": "CASH",
        "channelName": "现金",
        "payType": "TAIL",
        "payTypeName": "尾款",
        "collectorStaffId": "7001",
        "collectorName": "司机甲",
        "collectorRole": "DRIVER",
        "collectorRoleName": "司机",
        "receivedAt": "2026-08-10 15:20:30",
        "remark": null
      }
    ],
    "expenseLines": [],
    "advanceLines": [],
    "vehicleLines": [],
    "generatedBy": "1001",
    "generatedByName": "张三",
    "generatedAt": "2026-08-10 10:20:30",
    "confirmedBy": "1001",
    "confirmedByName": "张三",
    "confirmedAt": "2026-08-11 09:00:00"
  },
  "success": true
}

响应中已无 transferStatus 字段（不是返回 null，是字段不存在）。

8.2 边界（无收款 / 无报表记录，出参仍无 transferStatus）

GET /v3/admin/order/2084000000000002999/settlement/reports/reimbursement
Authorization: Bearer <token>

{
  "code": 200,
  "message": "success",
  "data": {
    "id": null,
    "orderId": "2084000000000002999",
    "reportStatus": "GENERATED",
    "primaryReporterId": null,
    "primaryReporterName": null,
    "primaryReporterRole": null,
    "reportVersion": 1,
    "driverCollectedTailAmount": "0.00",
    "approvedAdvanceAmount": "0.00",
    "reportablePaidCostAmount": "0.00",
    "reporterNetAmount": "0.00",
    "primaryReporterCollectedAmount": "0.00",
    "publicPrepaidAmount": "0.00",
    "primaryReporterDueAmount": "0.00",
    "advanceOutstandingAmount": "0.00",
    "reconNetAmount": "0.00",
    "transferDirection": null,
    "transferAmount": "0.00",
    "incomeLines": [],
    "expenseLines": [],
    "advanceLines": [],
    "vehicleLines": [],
    "generatedBy": null,
    "generatedByName": null,
    "generatedAt": null,
    "confirmedBy": null,
    "confirmedByName": null,
    "confirmedAt": null
  },
  "success": true
}

全空 / 零金额边界下同样不返回 transferStatus。

8.3 业务失败（调用旧 recon 写路径返回 404）

PUT /v3/admin/order/2084000000000002978/settlement/recon
Authorization: Bearer <token>
Content-Type: application/json

{"transferStatus": "COMPLETED"}

{"code": 404, "message": "请求路径不存在", "data": null, "success": false}

旧写路径（PUT /recon）与旧读路径（GET /recon）均已无服务端入口，任何调用一律 404。前端若残留「保存转账状态」逻辑需整体移除。

9. 业务边界

• ✅ 报账表弹窗展示核算数据 + 转账方向 / 金额结论（transferDirection / transferAmount 保留），不再有「转账状态」展示位。
• ✅ reconNet 等金额 / 收款派生逻辑保留不变，报账表数据口径与上一版一致。
• ❌ 不要在前端保留 transferStatus 的读取、展示（待转账 / 已转账标签、下拉框）或本地缓存。
• ❌ 不要调用 PUT / GET /v3/admin/order/{orderId}/settlement/recon，两条路径均已 404。
• ❌ 订单历史 transferStatus 数据仍在库中（零 DDL，列未删），但接口不再返回；不要依赖任何接口读取历史转账状态。

10. 修改前后对比

10.1 字段级对比

接口	字段	原来	现在
GET reports/reimbursement	transferStatus	出参（PENDING / COMPLETED）	已删除，其余出参不变
PUT /settlement/recon	整个接口	保存转账状态（入参 transferStatus）	已下线，调用返回 404
GET /settlement/recon	整个接口	查询对账 + 转账状态	已下线，调用返回 404（派生金额改由报账表接口透出）

10.2 出参 JSON 对照（transferStatus 删前 / 删后）

删前（旧版响应尾部片段）：

{
  "reconNetAmount": "-600.00",
  "transferDirection": "COMPANY_TO_REPORTER",
  "transferAmount": "600.00",
  "vehicleLines": [],
  "transferStatus": "PENDING",
  "generatedBy": "1001"
}

删后（新版响应同位置片段）：

{
  "reconNetAmount": "-600.00",
  "transferDirection": "COMPANY_TO_REPORTER",
  "transferAmount": "600.00",
  "vehicleLines": [],
  "generatedBy": "1001"
}

10.3 行为级对比

场景	原来	现在
报账表读取转账状态	出参带 transferStatus	字段不存在，读取恒为 undefined
保存转账状态	PUT /settlement/recon	接口 404，无替代接口（该能力整体下线）
查询对账详情	GET /settlement/recon	接口 404；派生金额从报账表接口读取

11. 影响评估 / 回滚

11.1 影响评估

• 是否破坏向后兼容：软破坏。出参少一个字段不会导致请求失败（区别于 #5809 入参删字段传了会 400），但前端若依赖 transferStatus 做展示 / 判断会拿到 undefined。
• 前端是否必须同步上线：建议同批。前端需删除 transferStatus 相关展示与逻辑，并对 recon 旧路径的残留调用做清理（调用即 404）。
• 上线顺序边界：先后端上前端无报错风险（仅少字段）；若前端先删引用、后端后上，旧后端仍返回 transferStatus，前端不读即可，两个方向均不阻塞。
• 数据库侧：零 DDL，transfer_status 列保留在库，无数据迁移成本。

11.2 回滚方案

• 代码回滚即恢复出参 transferStatus；数据库无变更，历史数据完整，回滚无数据修复成本。
• 前端已删引用的前提下回滚后端，出参会多一个字段，前端不读不受影响。

12. 注意事项

• 本次出参删字段与 #5809（入参删字段传了 400）不同：不会因为字段缺失而报错，前端唯一的坑是继续读 transferStatus 得到 undefined。
• 转账状态维护能力整体下线，没有替代接口；产品上该流程不再走核单链路。
• transferStatus 相关历史错误码码位保留但不再触发（对外契约不删号），前端错误码映射表可保留无需清理。
• 小程序端（/v3/mp/*）不涉及本次变更，无需任何改动。

13. 关联 / 联系人

13.1 链接

• Issue: #5816
• PR: #5826
• Commit: 253dc795e
• 相关批次: Issue #5809 / PR #5813（完成核单去凭据，changelog 见 2026-08/10_5809）

13.2 联系人

• 后端负责人: @yaosutu (yst) 腰苏图