6.0 KiB
6.0 KiB
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 | 5379 | 终止行程车辆退款改为 Fleet 服务日权威判定 | admin | 修改接口 | wx(GIT) | deployed | verified | claimed | Pi | 2026-08-03 | 后端实现完成：双模块 verify 通过（order 7402 全绿 / fleet 3010 仅 Docker 环境型 1 error），本单新增代码行覆盖率 91.7%，PR #5417+#5445 已合并 dev-v3 并部署 TEST（fleet→order-v3 顺序），网关已验证：预览成功路径（15 行 VEHICLE+terminateDate wire key）、终止提交成功（COMPLETED+PENDING_REVIEW+settlement refund 落库）、幂等重放（同 terminateRefundId）、阻断路径（581018 COMPLETED 拒绝/584100 费用不可用 fail-closed）、空集路径（无需求允许空车辆成本）；管理后台已由 Pi 领取并开始兼容适配。 | 2026-08-03 | dev-v3 |
订单: 终止行程车辆退款改为 Fleet 服务日权威判定
服务: hl-order-service-v3 PR: #5417 Issue: #5379 日期: 2026-08-03 影响范围: 管理后台订单终止退款预览及终止提交
⚠️ 关键变化
终止行程时，车辆是否已发生不再采用客户端提交的 vehicles[].used；后端按 Fleet 返回的 serviceDate 与 endDayNumber 对应终止日权威判定。vehicles[].used 仍为必填兼容字段，仅参与请求重放一致性校验。
变更接口
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 终止行程退款预览 | POST | /v3/admin/order/:id/terminate/refund-preview |
响应语义修改 | 车辆行 defaultUsed 仅供初始化展示，最终提交以后端权威事实为准 |
| 2 | 终止行程 | POST | /v3/admin/order/:id/terminate |
请求字段语义修改 | vehicles[].used 保持必填，但不再参与车辆退款金额计算 |
二、接口详情
1. 终止行程退款预览 POST /v3/admin/order/:id/terminate/refund-preview
出参: Result<OrderTerminateRefundPreviewRespVO>
| 字段 | 类型 | 说明 |
|---|---|---|
refundLines[].defaultUsed |
Boolean | 前端初始化展示值；车辆行最终是否已发生由提交时 Fleet serviceDate 与终止日重新判定 |
refundLines[].lineKey |
String | 提交 lineUsages 时原样回传 |
days[].terminateDate |
String(date) | 结束日期选项 wire key 固定为 terminateDate（原 date 字段改名），值 = departDate + (dayNumber-1)；dayNumber/label/isCurrent 不变 |
2. 终止行程 POST /v3/admin/order/:id/terminate
VO: OrderTerminateTripReqVO
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
endDayNumber |
Body | Integer | ✅ | 1-based，必须落在订单行程范围内 | 用于确定终止日；预览返回的 days[].terminateDate 即对应日期 |
vehicles[].refId |
Body | Long/String ID | ✅ | 有效配车记录 ID | 同段车跨天可重复 |
vehicles[].dayNumber |
Body | Integer | ✅ | >= 1 | 区分同段车辆的服务日 |
vehicles[].used |
Body | Boolean | ✅ | 不可省略 | 兼容及重放摘要字段，不参与车辆退款金额计算 |
lineUsages[].used |
Body | Boolean | ✅ | 非车辆资源按该值重算 | 不覆盖车辆 Fleet 事实 |
三、契约约束与正确调用方式
| 场景 | 后端行为 |
|---|---|
vehicles[].used 与 Fleet 服务日事实不同 |
车辆退款采用 Fleet 服务日事实；客户端值只保留在请求摘要中 |
| 相同终止边界和相同正文重试 | 返回既有终止结果 |
已终止订单以不同 endDayNumber 或不同正文重试 |
拒绝，错误码 581049 |
endDayNumber 超出订单行程 |
拒绝，错误码 581047 |
Fleet serviceDate 无法映射到订单行程 |
拒绝，错误码 581048 |
| Fleet 车辆事实不可用或不完整 | fail closed，错误码 584100，不按零车费继续 |
前端调用要求：
- 继续提交完整的
vehicles[].refId/dayNumber/used，不要删除used字段。 - 不要根据
vehicles[].used自行推导最终车辆退款金额；以接口返回的baselineRefund、finalRefund为准。 - 收到上述错误码时保留用户输入并提示重试或刷新事实，不要按“无车辆费用”继续。
四、边界行为与兼容性
- 请求字段、类型和必填性未删除，旧客户端 payload 可继续解析。
vehicles[].used的金额语义发生变化，但仍参与幂等重放摘要；重试时必须复用首次正文。- 非车辆资源仍按既有
lineUsages[].used规则处理。 - 后端修复尚未合并、部署或经网关验证；本文件不声明 TEST 环境可用。
验证证据
- 定向单元测试覆盖 Fleet 服务日权威判定、越界/不一致 fail-closed、重放冲突及车辆
used不覆盖事实。 - 真实独立 Redis 验证覆盖 owner-token 在事务提交前被替换时，订单状态、终止退款和 Fleet Outbox 三类本地写入全部回滚（SettlementFleetPlanLockCommitRedisIntegrationTest，本机 Redis 7.4 真实运行通过）。
- Fleet 真表 H2 IT 覆盖 reservation 生命周期与 terminate 截断隔离（5 个）；order-v3 真表 IT 覆盖 Outbox 最新命令因果查询。
- 双模块 reactor verify：order-v3 7334 全绿；fleet 2914，仅 #5374 Docker MySQL 测试环境型失败（本机无 Docker）。
- 本单核心新增代码 changed-line coverage 90.5%（≥90%）；evidence 包含 raw JaCoCo、provider receipts 与 SHA-256 索引。
- MySQL 8.0.33 gate 凭据不可恢复，未运行（如实记录，不冒充通过）。
- PR 合并、TEST 部署与网关验收仍待完成，因此
backend_status、gateway_status保持pending。
六、相关文档
- 关联 Issue: wx/HL#5379
- 关联 PR: wx/HL#5417