changelog-filename-gate / validate (push) Failing after 2s

详情

chore(changelog): #5809 #5781 前端 implemented(3993f15a)

2026-08-11 09:36:12 +08:00

17 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, change_type, author, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	change_type	author	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	5809	完成核单去转账/签字凭据采集：finalize 改无请求体，主报账对账与报账表删除凭据字段	admin	修改接口	yaosutu(GIT)	deployed	verified	implemented	mmg	3993f15a		2026-08-11	前端已实现(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 全量/生产构建)。	2026-08-11	dev-v3

【⚠️ 修改接口·管理后台】完成核单去转账/签字凭据采集：finalize 改无请求体，recon 入参删 4 字段，报账表出参删 4 字段（#5809）

PR: #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 典型成功（完成核单，无请求体）

POST /v3/admin/order/2084000000000002978/settlement/finalize
Authorization: Bearer <token>
Content-Length: 0

{
  "code": 200,
  "message": "success",
  "data": null,
  "success": true
}

注意：请求不带任何 body。幂等——已有 FINALIZED 快照且终态一致时重复调用直接返回原结果。

主报账对账保存（只传 transferStatus）：

PUT /v3/admin/order/2084000000000002978/settlement/recon
Authorization: Bearer <token>
Content-Type: application/json

{"transferStatus": "COMPLETED"}

{"code": 200, "message": "success", "data": null, "success": true}

8.2 边界（报账表出参已无凭据字段）

GET /v3/admin/order/2084000000000002978/settlement/reports/reimbursement
Authorization: Bearer <token>

{
  "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）

PUT /v3/admin/order/2084000000000002978/settlement/recon
Authorization: Bearer <token>
Content-Type: application/json

{"transferStatus": "COMPLETED", "transferRef": "202608100001"}

{"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
PR: #5813
Commit: 0e2ee34d6d
相关批次: Issue #5739 / PR #5764（核单指纹下线，changelog 见 2026-08/09_5739）

13.2 联系人

后端负责人: @yaosutu (yst) 腰苏图

17 KiB 原始文件 Blame 文件历史 Unescape Escape