docs(changelog): 完成核单去转账/签字凭据采集（#5809 / PR #5813）

finalize 改无请求体；recon 入参与报账表出参各删 4 个凭据字段；
ReqVO ignoreUnknown=false，前后端必须同批上线。

changelogs-v2/2026-08/10_5809_完成核单去凭据-修改接口-管理后台.md

@@ -0,0 +1,328 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5809"
+title: "完成核单去转账/签字凭据采集：finalize 改无请求体，主报账对账与报账表删除凭据字段"
+consumer: "admin"
+change_type: "修改接口"
+author: "yaosutu(GIT)"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: ""
+updated_at: "2026-08-10"
+base: "dev-v3"
+---
+
+# 【⚠️ 修改接口·管理后台】完成核单去转账/签字凭据采集：finalize 改无请求体，recon 入参删 4 字段，报账表出参删 4 字段（#5809）
+
+> **PR**: [#5813](https://git.1814.love:8443/wx/HL/pulls/5813) | **服务**: hl-order-service-v3 | **更新时间**: 2026-08-10
+
+## 1. 接口背景
+
+核单流程此前在「完成核单」和「主报账对账保存」两个环节采集转账/签字凭据：转账日期、转账流水号、预支是否已处理、签字凭证文件（图片 + 备注）。产品上决定凭据采集不再挂在核单链路（核单只负责核算确认，凭据留档走线下或其他系统），因此本次把凭据相关字段从 3 个接口整体摘除：
+
+- **完成核单 finalize**：整个请求体删除，改为仅 Path 传 orderId 的无 body 接口；
+- **主报账对账保存 recon**：入参只保留 transferStatus，删 4 个凭据字段及其必填校验；
+- **主报账人报账表 GET**：出参删同样 4 个凭据字段，报账弹窗改纯展示。
+
+> ⚠️ 本次为**入参删字段 + 出参删字段的硬破坏契约**：相关 ReqVO 配置了 ignoreUnknown=false，前端若继续传已删字段会直接 400，**前后端必须同批上线**（详见 §11、§12）。
+
+## 2. 变更清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 前端动作 |
+|---|---|---|---|---|---|
+| 1 | 完成核单 | POST | /v3/admin/order/{orderId}/settlement/finalize | 删除整个请求体（原 SettlementSubmitReqVO：remark + reimbursementConfirmation 凭据对象） | 请求不再带 body；清理凭据表单/校验逻辑 |
+| 2 | 主报账对账保存 | PUT | /v3/admin/order/{orderId}/settlement/recon | 入参删 transferDate / transferRef / advanceSettledFlag / signedVoucher，仅保留 transferStatus | 请求体只传 transferStatus；清理凭据表单 |
+| 3 | 主报账人报账表 | GET | /v3/admin/order/{orderId}/settlement/reports/reimbursement | 出参删 transferDate / transferRef / advanceSettledFlag / signedVoucher | 停读 4 字段；报账弹窗删凭据展示区 |
+
+## 3. 接口详情
+
+- **使用场景**：
+  - finalize：管理后台核单页面对账完成后点击「完成核单」，把订单核算推进到终态（落 FINALIZED 快照）。
+  - recon：主报账对账弹窗保存转账状态（待转账 / 已转账）。
+  - reports/reimbursement：主报账人报账表弹窗，展示主报账人收付对账与转账结论。
+- **认证**：需要管理后台登录态（Bearer Token）；房务角色（HOUSE）被 OrderViewGuard 拦截。
+- **幂等性**：
+  - finalize：改为纯终态校验，已有 FINALIZED 快照且终态一致时直接返回原结果，**天然幂等**，重复点击无副作用。
+  - recon：同一 transferStatus 重复保存为覆盖写，幂等。
+  - reports/reimbursement：只读查询，天然幂等。
+- **限流**：未声明接口专属限流。
+
+## 4. 接口入参
+
+### 4.1 路径参数
+
+三个接口一致：
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| orderId | Long | 是 | 订单 ID，路径参数，必须大于 0 |
+
+### 4.2 请求体字段
+
+#### POST /v3/admin/order/{orderId}/settlement/finalize（完成核单）
+
+**无请求体**。原 SettlementSubmitReqVO 整体删除，被删字段如下（前端不得再传）：
+
+| 原字段 | 类型 | 原说明 | 现状 |
+|---|---|---|---|
+| remark | String | 核单整体备注 | 已删除；服务端不再写 settlement_summary.remark |
+| reimbursementConfirmation | Object | 凭据对象 | 已删除 |
+| reimbursementConfirmation.transferDate | String(yyyy-MM-dd) | 转账日期 | 已删除 |
+| reimbursementConfirmation.transferRef | String | 转账流水号 | 已删除 |
+| reimbursementConfirmation.advanceSettledFlag | Boolean | 预支是否已处理 | 已删除 |
+| reimbursementConfirmation.signedVoucher | Object | 签字凭证，含 files[{name,url}] + note | 已删除 |
+
+> 原「reporterNetAmount 非 0 时强制 transferDate / transferRef 必填」的服务端校验同步移除；原 finalize 凭据校验失败错误码 584317 在此接口不再触发。
+
+#### PUT /v3/admin/order/{orderId}/settlement/recon（主报账对账保存）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| transferStatus | String | 是 | 转账状态，枚举：PENDING（待转账）/ COMPLETED（已转账） |
+
+被删字段（前端不得再传，传了会 400）：
+
+| 原字段 | 类型 | 原说明 | 现状 |
+|---|---|---|---|
+| transferDate | String(yyyy-MM-dd) | 转账日期 | 已删除 |
+| transferRef | String | 转账流水号 | 已删除 |
+| advanceSettledFlag | Boolean | 预支是否已处理 | 已删除 |
+| signedVoucher | Object | 签字凭证，含 files[{name,url}] + note | 已删除 |
+
+> 原「transferStatus=COMPLETED 时 transferRef 必填」校验同步移除。
+
+#### GET /v3/admin/order/{orderId}/settlement/reports/reimbursement（主报账人报账表）
+
+无请求体、无 Query 参数，入参零变化。
+
+## 5. 出参字段
+
+### 5.1 POST finalize / PUT recon
+
+统一响应 Result 包装，data 为操作结果（成功 code=200）。出参结构无变化。
+
+### 5.2 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 | String | 转账状态（PENDING / COMPLETED），保留 |
+| ~~transferDate~~ | - | **已删除**，前端不再收到此字段 |
+| ~~transferRef~~ | - | **已删除** |
+| ~~advanceSettledFlag~~ | - | **已删除** |
+| ~~signedVoucher~~ | - | **已删除** |
+| generatedBy / generatedByName / generatedAt | - | 生成人 ID / 姓名 / 时间 |
+| confirmedBy / confirmedByName / confirmedAt | - | 确认人 ID / 姓名 / 时间 |
+
+> 除删除 4 个凭据字段外，其余字段名称、类型、语义均无变化。前端不要再读取这 4 个字段，读取结果恒为 undefined。
+
+## 6. 枚举 / 数据字典
+
+### transferStatus（recon 入参 + 报账表出参共用）
+
+| 值 | 含义 | 本次变化 |
+|---|---|---|
+| PENDING | 待转账 | 不变 |
+| COMPLETED | 已转账 | 不变（原「COMPLETED 时 transferRef 必填」联动校验移除） |
+
+其余枚举/字典（reportStatus、incomeLines[].type、channel、payType、paymentMethod、transferDirection 等）取值与语义均无变化。
+
+## 7. 错误码
+
+| 错误码 | 含义 | 本次变化 |
+|---|---|---|
+| 400（参数校验） | 请求体含未知字段 | **新增触发路径**：ReqVO ignoreUnknown=false，前端继续传已删凭据字段（recon / finalize）会直接返回 400 |
+| 584317 | 原 finalize 凭据校验失败（transferDate/transferRef 缺失等） | **此接口不再触发**（凭据校验整体移除） |
+
+其余既有错误码（订单不存在、双报告未生成保护 584311 / 584313、房务角色 403 等）行为不变。
+
+## 8. 示例
+
+### 8.1 典型成功（完成核单，无请求体）
+
+```http
+POST /v3/admin/order/2084000000000002978/settlement/finalize
+Authorization: Bearer <token>
+Content-Length: 0
+```
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": null,
+  "success": true
+}
+```
+
+> 注意：请求不带任何 body。幂等——已有 FINALIZED 快照且终态一致时重复调用直接返回原结果。
+
+主报账对账保存（只传 transferStatus）：
+
+```http
+PUT /v3/admin/order/2084000000000002978/settlement/recon
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{"transferStatus": "COMPLETED"}
+```
+
+```json
+{"code": 200, "message": "success", "data": null, "success": true}
+```
+
+### 8.2 边界（报账表出参已无凭据字段）
+
+```http
+GET /v3/admin/order/2084000000000002978/settlement/reports/reimbursement
+Authorization: Bearer <token>
+```
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "id": "8802",
+    "orderId": "2084000000000002978",
+    "reportStatus": "GENERATED",
+    "primaryReporterId": "7001",
+    "primaryReporterName": "司机甲",
+    "primaryReporterRole": "DRIVER",
+    "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": [],
+    "transferStatus": "PENDING",
+    "generatedBy": "1001",
+    "generatedByName": "张三",
+    "generatedAt": "2026-08-10 10:20:30",
+    "confirmedBy": null,
+    "confirmedByName": null,
+    "confirmedAt": null
+  },
+  "success": true
+}
+```
+
+> 响应中已无 transferDate / transferRef / advanceSettledFlag / signedVoucher 四个字段（不是返回 null，是字段不存在）。
+
+### 8.3 业务失败（前端仍传已删字段 → 400）
+
+```http
+PUT /v3/admin/order/2084000000000002978/settlement/recon
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{"transferStatus": "COMPLETED", "transferRef": "202608100001"}
+```
+
+```json
+{"code": 400, "message": "请求参数格式错误（含未识别字段 transferRef）", "data": null, "success": false}
+```
+
+> ReqVO ignoreUnknown=false，任何已删字段（transferDate / transferRef / advanceSettledFlag / signedVoucher / remark / reimbursementConfirmation）传入都会 400。这是本次最需要前端规避的失败路径。
+
+## 9. 业务边界
+
+- ✅ 完成核单只需订单处于可核单终态 + 双报告已生成（584311 / 584313 保护不变），不再要求任何凭据。
+- ✅ recon 只需选择转账状态（PENDING / COMPLETED），COMPLETED 也不再要求转账流水号。
+- ✅ 报账表弹窗改为纯展示核算数据 + 转账状态，无凭据上传/回填交互。
+- ❌ 不要在前端保留凭据采集表单（转账日期/流水号/预支处理标记/签字凭证上传），继续提交会 400。
+- ❌ 不要把本地缓存/草稿里的凭据数据回传到 finalize 或 recon。
+- ❌ 订单历史凭据数据仍在库中（零 DDL，列未删），但接口不再返回；不要依赖报账表接口读取历史凭据。
+
+## 10. 修改前后对比
+
+### 10.1 字段级对比
+
+| 接口 | 字段 | 原来 | 现在 |
+|---|---|---|---|
+| POST finalize | 请求体整体 | SettlementSubmitReqVO（remark + reimbursementConfirmation{transferDate, transferRef, advanceSettledFlag, signedVoucher{files[{name,url}], note}}） | **无请求体**，仅 Path 传 orderId |
+| PUT recon | transferDate / transferRef / advanceSettledFlag / signedVoucher | 入参（transferStatus=COMPLETED 时 transferRef 必填） | **已删除**，入参仅保留 transferStatus |
+| GET reports/reimbursement | transferDate / transferRef / advanceSettledFlag / signedVoucher | 出参 | **已删除**，其余出参不变 |
+
+### 10.2 行为级对比
+
+| 场景 | 原来 | 现在 |
+|---|---|---|
+| 完成核单时 reporterNetAmount 非 0 | 强制要求 transferDate / transferRef，缺失报 584317 | 无任何凭据校验，直接走终态确认 |
+| 完成核单提交备注 remark | 写入 settlement_summary.remark | 不再接收、不再写入 |
+| recon 保存 transferStatus=COMPLETED | transferRef 必填 | 仅保存 transferStatus |
+| 报账表弹窗 | 展示并可回填凭据区 | 纯展示，无凭据字段 |
+| finalize 终态快照比对 | 含凭据字段比对 | 不再比对凭据 |
+| finalize 重复调用 | 凭据差异可能导致非幂等 | 纯终态校验，终态一致直接返回原结果，天然幂等 |
+
+## 11. 影响评估 / 回滚
+
+### 11.1 影响评估
+
+- **是否破坏向后兼容**：**是，硬破坏**。finalize 请求体删除 + recon 入参删 4 字段 + 报账表出参删 4 字段；且 ReqVO ignoreUnknown=false，旧前端继续传凭据字段会直接 400（不是静默忽略）。
+- **前端是否必须同步上线**：**必须同批**。前端需先删掉凭据表单与字段读取，再与后端同批发布。
+- **上线顺序边界**：前后端同批发布；若必须分先后，**先上前端（停传/停读凭据字段），再上后端**。旧前端 + 新后端 = finalize / recon 直接 400，功能不可用。
+- **数据库侧**：**零 DDL**，数据库列未动，历史凭据数据保留在库中（接口不再读写），无数据迁移成本。
+
+### 11.2 回滚方案
+
+- 代码回滚即恢复原请求体/入参/出参与凭据校验；数据库无变更，历史数据完整，回滚无数据修复成本。
+- **回滚必须前后端同批回滚**：新前端（不传凭据）+ 旧后端（reporterNetAmount 非 0 强制凭据）会导致 finalize 报 584317 失败。
+
+## 12. 注意事项
+
+- **契约破坏红线**：相关 ReqVO 配置了 ignoreUnknown=false，前端**继续传任何已删字段都会 400**（不是忽略）。包括：finalize 的 remark / reimbursementConfirmation 整个对象，recon 的 transferDate / transferRef / advanceSettledFlag / signedVoucher。前后端必须同批上线。
+- 本次只动凭据采集相关字段；订单金额核算逻辑、reportStatus 枚举、双报告生成/确认保护（584311 / 584313）均未变化。
+- finalize 的 Swagger 描述中若残留凭据相关文案属文档残留，以本 changelog 为准。
+- 小程序端（/v3/mp/*）不涉及本次变更，无需任何改动。
+
+## 13. 关联 / 联系人
+
+### 13.1 链接
+
+- **Issue**: [#5809](https://git.1814.love:8443/wx/HL/issues/5809)
+- **PR**: [#5813](https://git.1814.love:8443/wx/HL/pulls/5813)
+- **Commit**: [0e2ee34d6d](https://git.1814.love:8443/wx/HL/commit/0e2ee34d6d)
+- **相关批次**: Issue [#5739](https://git.1814.love:8443/wx/HL/issues/5739) / PR [#5764](https://git.1814.love:8443/wx/HL/pulls/5764)（核单指纹下线，changelog 见 2026-08/09_5739）
+
+### 13.2 联系人
+
+- **后端负责人**: @yaosutu (yst) 腰苏图