---
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) 腰苏图