331 行
14 KiB
Markdown
331 行
14 KiB
Markdown
---
|
||
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: "implemented"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "b22d6c14"
|
||
target_release: ""
|
||
verified_at: "2026-08-11"
|
||
status_note: "前端已实现(b22d6c14):实证 transferStatus 在视图层零引用、getSettlementRecon/saveSettlementRecon 无生产调用方(转账状态流转不再走核单链路),删 orderV2.js 这两个 recon 死导出及 jsdoc,改下线注记;reconNetAmount 等派生金额由报账表接口透出不受影响,报账表 jsdoc 补 #5816 出参再删 transferStatus 说明。软破坏(少字段不报错),前端不读即兼容。orderV2.spec 13 全过,checkpoint 单文件全绿(ESLint/Vitest 全量/生产构建)。"
|
||
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) 腰苏图
|