hl-api-changelog/changelogs-v2/2026-09/16_7767_团车户与免车团户可终止行程-修改接口-管理后台.md

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

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7767	团车户与免车团户可终止行程，终止车费投影认可团车与整团免车	admin	wx(GIT)	修改接口	deployed	verified	verified	mmg	a2a4e2ddae0508de89e941e308ffde5b1d9944c5		2026-09-16	仅后端交付。新增错误码 584132 与修改的 584100 文案在源码与 API-SPEC 已核对；测试服验证见工单 #7767 验收评论。前端需补错误码 584132 的提示文案映射，误将两码混用则会给出不恰当的稍后重试建议。；前端 hl-admin a2a4e2dd 已实现：terminateRefund.js 补 584132 提示(等车务配车完成后再试)与 584100(稍后重试)语义区分,api docstring 同步,spec +1,checkpoint 全绿。	2026-09-16	dev-v3

order-v3: 团车户与免车团户可终止行程

存放目录: changelogs-v2/{YYYY-MM}/（管理后台，二期 order-v3）

服务: hl-order-service-v3 (端口 8083) PR: #7789 Issue: #7767 日期: 2026-09-16 影响范围: 终止行程接口新增错误码 584132；错误码 584100 文案修改，收窄适用场景

---

关键变化

1. 原本终止行程对团级配车户（GROUP_VEHICLE）和整团免车户恒返 584100——该两类户现已可成功终止。
2. 新增错误码 584132：用于"用车需求未完成"场景，与 584100"车费暂时不可用"语义分开。前端必须区别对待两个错误码：
   • 584132 → "等车务配车完成后再试"（需催车务处理）
   • 584100 → "暂时不可用，请稍后重试"（快照异常，应自己好转）

---

一、背景

#7441 新增了团级正式用车需求声明的端点，其后 #7445 给定制师逐户所报的用车需求引入"就绪状态"检查（DAILY_V3 契约版本）。此前团车户与免车户因为 assignment_contract_version 判据不满足而永久卡死在 584100 错误，无法终止。本次放行这两类户，同时将终止失败分成两个语义明确的错误码。

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	终止行程·退款预览	POST	/v3/admin/order/{orderId}/terminate-refund/preview	修改	新增错误码 584132；修改 584100 文案与适用范围
2	终止行程	POST	/v3/admin/order/{orderId}/terminate	修改	新增错误码 584132；修改 584100 文案与适用范围

---

三、接口详情

1. 终止行程·退款预览 POST /v3/admin/order/{orderId}/terminate-refund/preview

VO: (路径参数 → OrderTerminateRefundPreviewRespVO)

使用场景

出行中点击"终止行程"时的前置预览，展示本单若干今日已用、剩余天数、应退金额等。预览过程不做任何写入，失败也不影响后续正式终止接口调用。

入参字段表

字段	位置	类型	必填	约束	说明
orderId	Path	Long	是	-	订单 ID

出参字段表

字段	类型	说明
orderId	Long	订单 ID
orderNo	String	订单号
usedDays	Integer	已用天数（截至今日）
remainingDays	Integer	剩余天数（今日之后）
refundAmount	BigDecimal	应退总金额（含车费、房费等）
vehicleFeeRefund	BigDecimal	车费应退（拆分显示，供前端按业务决策）
houseFeeRefund	BigDecimal	房费应退

请求示例

GET /v3/admin/order/1934567890123456789/terminate-refund/preview

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "orderId": 1934567890123456789,
    "orderNo": "26-0503",
    "usedDays": 2,
    "remainingDays": 4,
    "refundAmount": "8000.00",
    "vehicleFeeRefund": "3200.00",
    "houseFeeRefund": "4800.00"
  },
  "success": true
}

空数据 / 降级响应

本接口无空数据场景（订单存在即可预览）。

错误响应

{
  "code": 584100,
  "message": "车务车辆总车费暂时不可用，请稍后重试",
  "success": false,
  "data": null
}

{
  "code": 584132,
  "message": "用车需求未完成，暂不能终止行程，请等车务配车完成后再试",
  "success": false,
  "data": null
}

错误响应

{
  "code": 581001,
  "message": "订单不存在",
  "success": false,
  "data": null
}

{
  "code": 583301,
  "message": "订单状态不允许此操作",
  "success": false,
  "data": null
}

业务边界

• 鉴权: 需 admin 权限，团期户与散客户均支持
• 状态机: 仅 TRAVELLING/TRANSFER 状态订单可预览，其他状态拒绝（401）
• 幂等: 无写入，重复调用返回一致结果
• 零副作用: 预览失败不作用任何表与缓存，安全重试
• 旧数据兼容: refundAmount 等字段在快照 JSON 损毁时可能为 null，前端需判空

---

2. 终止行程 POST /v3/admin/order/{orderId}/terminate

VO: OrderTerminateTripReqVO → OrderTerminateTripRespVO

使用场景

出行中因特殊原因（天气、医疗等）提前终止订单，订单进入 COMPLETED 状态。结算与房车资源释放在终止之后由结算流程异步处理。

入参字段表

字段	位置	类型	必填	约束	说明
orderId	Path	Long	是	-	订单 ID
cancelReason	Body	String	是	≤500 字符	终止原因（运营内部备注）
endDayNumber	Body	Integer	是	1 ≤ dayNumber ≤ 行程天数	终止日在行程中的序号（Day 1、Day 2 等）
vehicles	Body	List	否	-	旧客户端兼容字段，新客户端可不传

出参字段表

字段	类型	说明
orderId	Long	订单 ID
orderNo	String	订单号
status	String	订单状态（转移为 COMPLETED）
terminateRefundRecord	Object	退款记录快照
terminateRefundRecord.refundAmount	BigDecimal	实退总金额
terminateRefundRecord.createdAt	LocalDateTime	记录时刻

请求示例

{
  "cancelReason": "客户身体不适，需提前返程",
  "endDayNumber": 3
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "orderId": 1934567890123456789,
    "orderNo": "26-0503",
    "status": "COMPLETED",
    "terminateRefundRecord": {
      "refundAmount": "8000.00",
      "createdAt": "2026-09-16T14:30:00"
    }
  },
  "success": true
}

空数据 / 降级响应

本接口无空数据场景。

错误响应

{
  "code": 584132,
  "message": "用车需求未完成，暂不能终止行程，请等车务配车完成后再试",
  "success": false,
  "data": null
}

{
  "code": 584100,
  "message": "车务车辆总车费暂时不可用，请稍后重试",
  "success": false,
  "data": null
}

业务边界

• 鉴权: 需 admin 权限
• 状态机: 仅 TRAVELLING 状态可终止
• 幂等: 同一订单同一 endDayNumber 重复终止返 581049（已终止）
• 团车户与免车户放行: 现已支持，按 DAILY_V3 规则正常处理

---

四、契约约束与正确调用方式

场景	做法
出行中 Day 3 终止	先预览、再提交，endDayNumber=3
重复终止（幂等）	同一订单同 endDayNumber 重复 POST，返 200 或 581049
错误码 584132	"等车务配车完成"，需催车务处理
错误码 584100	"暂时不可用"，稍后重试

---

五、数据库行为

操作	order_main.order_status	order_terminate_refund	房车资源释放
终止成功	TRAVELLING → COMPLETED	INSERT 一行	异步触发
终止失败	无变更	无新增	无

---

六、边界行为

• 未登录 → 401
• 无权限 → 403
• 订单不存在 → 404
• 状态非 TRAVELLING → 583301
• 结束日越界 → 581047
• 车费快照异常 → 584100
• 用车需求未配车 → 584132

---

六.5、枚举

订单状态 (status 字段)

所属字段: OrderTerminateTripRespVO.status | 类型: String

值	中文	说明
TRAVELLING	出行中	使用终止接口前的状态
COMPLETED	已完成	终止成功后的状态

---

六.6、修改前后对比

错误码对比

错误码	改前	改后
584100	对所有车费投影缺失的户统一返回	收窄为仅覆盖 DAILY_V3 契约版本但快照未就绪的户
584132	不存在	新增，覆盖非 DAILY_V3 且未配车的户

---

六.7、影响评估

• 是否破坏向后兼容: 是（团车户和免车户原本失败，现已成功）
• 前端是否必须同步上线: 是（需处理新错误码 584132）
• 前端 workaround 清理点: 删除硬编码的"团车户无法终止"逻辑

---

七、不影响范围

• 仅影响: 管理后台出行中订单的终止功能
• 零影响:
  • C 端应用
  • 其他状态订单的操作
  • 房费结算
  • 用车需求声明等其他模块

---

八、测试环境已验证

POST /v3/admin/order/{id}/terminate-refund/preview → 200 ✓
POST /v3/admin/order/{id}/terminate (GROUP_VEHICLE) → 200 ✓
POST /v3/admin/order/{id}/terminate (免车户) → 200 ✓

---

十、相关文档

• Issue: #7767
• PR: #7789
• Merge commit: 42dea4c36

关联 / 联系人

链接

• Issue: #7767
• PR: #7789
• Merge commit: 42dea4c36

联系人

• 后端负责人: @wx