---
schema: "hl-changelog/v2"
ticket: "5379"
title: "终止行程车辆退款改为 Fleet 服务日权威判定"
consumer: "admin"
change_type: "修改接口"
author: "wx(GIT)"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "claimed"
frontend_owner: "Pi"
frontend_ref: ""
target_release: ""
verified_at: "2026-08-03"
status_note: "后端实现完成：双模块 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 领取并开始兼容适配。"
updated_at: "2026-08-03"
base: "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`，不按零车费继续 |

前端调用要求：

1. 继续提交完整的 `vehicles[].refId/dayNumber/used`，不要删除 `used` 字段。
2. 不要根据 `vehicles[].used` 自行推导最终车辆退款金额；以接口返回的 `baselineRefund`、`finalRefund` 为准。
3. 收到上述错误码时保留用户输入并提示重试或刷新事实，不要按“无车辆费用”继续。

## 四、边界行为与兼容性

- 请求字段、类型和必填性未删除，旧客户端 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](https://git.1814.love:8443/wx/HL/issues/5379)
- 关联 PR: [wx/HL#5417](https://git.1814.love:8443/wx/HL/pulls/5417)