329 行
17 KiB
Markdown
329 行
17 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "5809"
|
||
title: "完成核单去转账/签字凭据采集：finalize 改无请求体，主报账对账与报账表删除凭据字段"
|
||
consumer: "admin"
|
||
change_type: "修改接口"
|
||
author: "yaosutu(GIT)"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "implemented"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "3993f15a"
|
||
target_release: ""
|
||
verified_at: "2026-08-11"
|
||
status_note: "前端已实现(3993f15a):finalize 改无请求体(仅 Path 传 orderId)——orderV2.finalizeSettlement 改单参 body=undefined,settlementService.completeSettlement 删 remark trim/校验与 reimbursementConfirmationPayload 组装改 completeSettlement(id);ReportModal 删转账日期/预支是否已结清/流水号/签字单凭证/备注整块凭据表单与相关 script,formulaText 改注记凭据摘除;detail.vue 删 ReportModal 凭据绑定、reimbursementConfirmation ref、askComplete 改单参、删路由 watch 重置块。测试同步:orderV2.spec finalize 用例改断言 body=undefined;settlementService.spec 重写 finalize payload 断言为 toHaveBeenCalledWith(ORDER_ID)、删「净额非零必须提交日期流水」用例、各 finalize 用例去 confirmation 第二参;ReportModal.spec 删两个凭据编辑用例与 FileUpload mock/helper。前端先上、后端随后(前后端需同批,后端上线前老前端传凭据字段会 400,已按排期先前端)。核单域四 spec 34+16 全过,checkpoint 7 文件全绿(ESLint/Vitest 全量/生产构建)。"
|
||
updated_at: "2026-08-11"
|
||
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) 腰苏图
|