diff --git a/changelogs-v2/2026-08/11_5816_主报账对账去transferStatus-修改接口-管理后台.md b/changelogs-v2/2026-08/11_5816_主报账对账去transferStatus-修改接口-管理后台.md new file mode 100644 index 0000000..8ab6a8c --- /dev/null +++ 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 +``` + +```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 +``` + +```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 +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) 腰苏图