changelog(#5816): 主报账对账 transferStatus 彻底下线——报账表出参删字段 + recon 读/写路径声明下线（PR #5826）

2026-08-11 12:04:57 +08:00 · 2026-08-11 12:04:57 +08:00 · 036f1558a1
--- a/changelogs-v2/2026-08/11_5816_主报账对账去transferStatus-修改接口-管理后台.md
+++ b/changelogs-v2/2026-08/11_5816_主报账对账去transferStatus-修改接口-管理后台.md
@ -0,0 +1,330 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5816"
+title: "主报账对账 transferStatus 彻底下线：报账表出参删字段，recon 读/写路径正式声明下线（404）"
+consumer: "admin"
+change_type: "修改接口"
+author: "yaosutu(GIT)"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "pending"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-08-11"
+status_note: ""
+updated_at: "2026-08-11"
+base: "dev-v3"
+---
+
+# 【⚠️ 修改接口·管理后台】主报账对账 transferStatus 彻底下线：报账表出参删 transferStatus，recon 读/写路径正式声明下线（#5816）
+
+> **PR**: [#5826](https://git.1814.love:8443/wx/HL/pulls/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）
+
+```http
+GET /v3/admin/order/2084000000000002978/settlement/reports/reimbursement
+Authorization: Bearer <token>
+```
+
+```json
+{
+  "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）
+
+```http
+GET /v3/admin/order/2084000000000002999/settlement/reports/reimbursement
+Authorization: Bearer <token>
+```
+
+```json
+{
+  "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）
+
+```http
+PUT /v3/admin/order/2084000000000002978/settlement/recon
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{"transferStatus": "COMPLETED"}
+```
+
+```json
+{"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 删前 / 删后）
+
+删前（旧版响应尾部片段）：
+
+```json
+{
+  "reconNetAmount": "-600.00",
+  "transferDirection": "COMPANY_TO_REPORTER",
+  "transferAmount": "600.00",
+  "vehicleLines": [],
+  "transferStatus": "PENDING",
+  "generatedBy": "1001"
+}
+```
+
+删后（新版响应同位置片段）：
+
+```json
+{
+  "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](https://git.1814.love:8443/wx/HL/issues/5816)
+- **PR**: [#5826](https://git.1814.love:8443/wx/HL/pulls/5826)
+- **Commit**: [253dc795e](https://git.1814.love:8443/wx/HL/commit/253dc795e)
+- **相关批次**: Issue [#5809](https://git.1814.love:8443/wx/HL/issues/5809) / PR [#5813](https://git.1814.love:8443/wx/HL/pulls/5813)（完成核单去凭据，changelog 见 2026-08/10_5809）
+
+### 13.2 联系人
+
+- **后端负责人**: @yaosutu (yst) 腰苏图