From 46035981161bee92f901774763099b352ecb75b8 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Mon, 3 Aug 2026 18:19:23 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20#5379=20=E7=BB=88=E6=AD=A2=E8=A1=8C?=
 =?UTF-8?q?=E7=A8=8B=E8=BD=A6=E8=BE=86=E9=80=80=E6=AC=BE=E6=94=B9=E4=B8=BA?=
 =?UTF-8?q?=20Fleet=20=E6=9C=8D=E5=8A=A1=E6=97=A5=E6=9D=83=E5=A8=81?=
 =?UTF-8?q?=E5=88=A4=E5=AE=9A=EF=BC=88=E5=90=8E=E7=AB=AF=E5=AE=9E=E7=8E=B0?=
 =?UTF-8?q?=E5=AE=8C=E6=88=90=EF=BC=8C=E5=BE=85=E5=90=88=E5=B9=B6=E9=83=A8?=
 =?UTF-8?q?=E7=BD=B2=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...止行程车辆退款权威口径-修改接口-管理后台.md | 100 ++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 changelogs-v2/2026-08/03_5379_终止行程车辆退款权威口径-修改接口-管理后台.md

diff --git a/changelogs-v2/2026-08/03_5379_终止行程车辆退款权威口径-修改接口-管理后台.md b/changelogs-v2/2026-08/03_5379_终止行程车辆退款权威口径-修改接口-管理后台.md
new file mode 100644
index 0000000..aec2421
--- /dev/null
+++ b/changelogs-v2/2026-08/03_5379_终止行程车辆退款权威口径-修改接口-管理后台.md
@@ -0,0 +1,100 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5379"
+title: "终止行程车辆退款改为 Fleet 服务日权威判定"
+consumer: "admin"
+change_type: "修改接口"
+backend_status: "pending"
+gateway_status: "pending"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端实现完成：双模块 verify 通过（order 7334 全绿 / fleet 2914 仅 Docker 环境型 1 error），本单核心新增代码行覆盖率 90.5%，contract-review 完成（openapi not_configured 人工回退 + internal feign 显式契约测试 passed）；PR 待合并，尚未部署或完成网关验收"
+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` 时原样回传 |
+
+### 2. 终止行程 `POST /v3/admin/order/:id/terminate`
+
+**VO**: `OrderTerminateTripReqVO`
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| `endDayNumber` | Body | Integer | ✅ | 1-based，必须落在订单行程范围内 | 用于确定终止日 |
+| `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)