---
schema: "hl-changelog/v2"
ticket: "5460"
title: "终止行程接口幂等重放契约恢复：同正文重放返回既有结果，不同正文返回 581049"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: "2026-08-04"
status_note: "行为修复：恢复 #5379 已承诺的终止行程幂等重放语义（#5379 最终合并版丢失了早期迭代的幂等实现，导致首次终止成功后同正文重放被 581018 提前拦截、无法取回既有结果）。PR #5468 已合并 dev-v3 并部署 TEST，网关已验证：新订单首次终止 200、同正文重放返回既有 terminateRefundId/finalRefund、不同边界/正文返回 581049（修复前同场景实测 581018）。"
updated_at: "2026-08-04"
base: "dev-v3"
---

# 终止行程接口幂等重放契约恢复：同正文重放返回既有结果，不同正文返回 581049

> **服务**: hl-order-service-v3
> **PR**: #5468
> **Issue**: #5460
> **日期**: 2026-08-04
> **影响范围**: 管理后台订单终止行程（出行中终止）提交接口的重试/重放行为

---

## ⚠️ 关键变化

**#5379 契约承诺的幂等重放语义此前在 TEST 实测失效**：首次终止提交成功但响应丢失后，对同一订单原样重放同一请求，接口返回 `581018「出行中取消仅适用于出行中订单」`，而不是返回既有终止结果；用不同正文重试也返回 581018 而不是 `581049`。**现已修复**，行为与 #5379 changelog 契约一致：

| 场景 | 修复前实测 | 修复后 |
|------|-----------|--------|
| 相同正文重放（首次已成功） | 581018（错误） | `200`，返回既有终止结果（含 terminateRefundId / finalRefund） |
| 不同正文 / 不同终止边界重试 | 581018（错误） | `581049` 终止行程重试与首次终止边界或请求不一致 |

前端无需改动，但**超时/网络重试逻辑现在可以依赖该接口的幂等语义**：重试时原样复用首次请求正文即可取回既有结果，不要修改正文内容（包括 `vehicles[].used` 与 `lineUsages[].used`）。

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 终止行程 | POST | `/v3/admin/order/:id/terminate` | 行为修复 | 幂等重放语义恢复（契约不变，见 #5379） |

## 三、接口详情

### 1. 终止行程 `POST /v3/admin/order/:id/terminate`

**请求体**: `OrderTerminateTripReqVO`（字段、必填性、约束均不变，与 #5379 一致）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `endDayNumber` | Integer | ✅ | 停在第几天（1-based）；**重试必须与首次完全一致** |
| `cancelReason` | String | ✅ | 终止原因；重试必须与首次完全一致 |
| `adjustAmount` | BigDecimal | 否 | 人工调整额；重试必须与首次一致（0 与 null 视为等价） |
| `lineUsages[]` | Array | 否 | 统一资源行已用判定；重试必须与首次一致 |
| `rooms[]` / `tickets[]` / `services[]` / `supplies[]` | Array | 否 | 兼容分组入参；重试必须与首次一致 |
| `vehicles[]` | Array | 否 | 用车行（refId/dayNumber/used）；used 仍参与重放一致性校验，金额以后端 Fleet 事实为准 |

**业务边界（重放判定规则）**：

1. 订单为 TRAVELLING 时：正常执行首次终止 → `200`，订单变 COMPLETED。
2. 订单已 COMPLETED（已终止）时，**先判定重放身份**，不再直接返回 581018：
   - 同边界 + 同正文（请求指纹一致）→ `200`，返回既有终止结果：`terminateRefundId`、`baselineRefund`、`adjustAmount`、`finalRefund`、`settlementRefundId`、`newStatus=COMPLETED`、`newFlowStatus=PENDING_REVIEW`；不产生任何副作用（不重复写退款、不重复发事件）。
   - 同边界但正文不一致，或边界不一致（`endDayNumber` 等不同）→ `581049 终止行程重试与首次终止边界或请求不一致`。
   - 升级前已终止的订单（无指纹快照）：按主表与明细快照做语义等价校验，等价重放同样返回既有结果，不等价返回 581049。
3. `endDayNumber` 超出订单行程 → `581047`（不变）；车辆费用不可用 → `584100` fail closed（不变）。

**错误码**：

| 错误码 | 含义 | 触发条件 |
|--------|------|----------|
| 581018 | 出行中取消仅适用于出行中订单 | 订单非 TRAVELLING 且**从未终止**（自然结束/已取消等）时提交终止 |
| 581049 | 终止行程重试与首次终止边界或请求不一致 | 已终止订单以不同边界/不同正文重试 |
| 581047 | 终止行程：结束日不在订单行程范围内 | endDayNumber 越界 |
| 581044 | 终止行程：结束日之前的资源必须标记为已使用 | 结束日前资源 used=false |

**典型成功示例（同正文重放）**：

请求：

```json
POST /v3/admin/order/2084280231786430466/terminate
Authorization: Bearer <token>
Content-Type: application/json

{
  "cancelReason": "客户高反送医终止",
  "endDayNumber": 2,
  "adjustAmount": 0,
  "lineUsages": [
    { "lineKey": "HOTEL_ASSIGNMENT:96011:1", "used": true },
    { "lineKey": "ITINERARY_NODE:97010:1", "used": true }
  ],
  "vehicles": [
    { "refId": 9000004500000001, "dayNumber": 1, "used": true }
  ]
}
```

响应（首次终止与同正文重放均为此响应，重放时 terminateRefundId/finalRefund 与首次一致）：

```json
{
  "code": 200,
  "data": {
    "terminateRefundId": "2084497785524011009",
    "baselineRefund": "6500.00",
    "adjustAmount": "0.00",
    "finalRefund": "6500.00",
    "settlementRefundId": "2084497785561759746",
    "newStatus": "COMPLETED",
    "newFlowStatus": "PENDING_REVIEW"
  },
  "success": true
}
```

**异常示例（不同正文重试）**：

```json
{
  "code": 581049,
  "message": "终止行程重试与首次终止边界或请求不一致",
  "success": false
}
```

## 四、验证证据

- `mvn -pl hl-order-service-v3 -am verify` 全绿（含 spotless + 全部单元/集成测试；新增幂等重放回归：首次终止写指纹 → 同正文重放 → 不同正文冲突三态）。
- TEST 网关验证（wx 定制师，2026-08-04）：新订单首次终止 200 且写指纹；同正文重放返回同一 terminateRefundId/finalRefund；不同 endDayNumber 返回 581049；升级前已终止订单同语义重放返回既有 terminateRefundId/finalRefund、不同边界返回 581049（修复前同场景实测 581018）。
- 已部署 TEST（dev-v3 滚动部署，双实例健康）。

## 五、相关文档

- 关联 Issue: [wx/HL#5460](https://git.1814.love:8443/wx/HL/issues/5460)
- 关联 PR: [wx/HL#5468](https://git.1814.love:8443/wx/HL/pulls/5468)
- 契约基线: [03_5379_终止行程车辆退款权威口径-修改接口-管理后台.md](./03_5379_终止行程车辆退款权威口径-修改接口-管理后台.md)

## 关联 / 联系人

### 链接

- **Issue**: [#5460](https://git.1814.love:8443/wx/HL/issues/5460)
- **PR**: [#5468](https://git.1814.love:8443/wx/HL/pulls/5468)
- **Merge commit**: [316a7d2c29](https://git.1814.love:8443/wx/HL/commit/316a7d2c29)
### 联系人

- **后端负责人**: @wx