From 35a67a6264ee8a8aa0952ced6822dcfc69ce4556 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 16 Sep 2026 23:06:19 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20#7767=20=E8=A1=A5=E5=85=85=E7=AC=AC?= =?UTF-8?q?=E4=B8=89=E4=B8=AA=E6=8E=A5=E5=8F=A3=20transition=20=E8=AF=A6?= =?UTF-8?q?=E6=83=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 添加 POST /v3/admin/order/{id}/transition (eventCode=TERMINATE) 的完整接口文档， 说明该接口同样支持 584132/584100 错误码。 Co-Authored-By: Claude Haiku 4.5 --- ...户与免车团户可终止行程-修改接口-管理后台.md | 79 ++++++++++++++++++- 1 file changed, 78 insertions(+), 1 deletion(-) diff --git a/changelogs-v2/2026-09/16_7767_团车户与免车团户可终止行程-修改接口-管理后台.md b/changelogs-v2/2026-09/16_7767_团车户与免车团户可终止行程-修改接口-管理后台.md index b70c3a7e..b584d45d 100644 --- a/changelogs-v2/2026-09/16_7767_团车户与免车团户可终止行程-修改接口-管理后台.md +++ b/changelogs-v2/2026-09/16_7767_团车户与免车团户可终止行程-修改接口-管理后台.md @@ -50,6 +50,7 @@ base: "dev-v3" |---|------|------|------|----------|------| | 1 | 终止行程·退款预览 | POST | `/v3/admin/order/{id}/terminate/refund-preview` | 修改 | 新增错误码 584132；修改 584100 文案与适用范围 | | 2 | 终止行程 | POST | `/v3/admin/order/{id}/terminate` | 修改 | 新增错误码 584132；修改 584100 文案与适用范围 | +| 3 | 状态变更（通用） | POST | `/v3/admin/order/{id}/transition` | 修改 | 当 eventCode=TERMINATE 时同样触发上述两个错误码 | --- @@ -247,6 +248,82 @@ GET /v3/admin/order/1934567890123456789/terminate-refund/preview - **幂等**: 同一订单同一 endDayNumber 重复终止返 581049（已终止） - **团车户与免车户放行**: 现已支持，按 DAILY_V3 规则正常处理 + +### 3. 状态变更·通用 `POST /v3/admin/order/{id}/transition` + +**VO**: `OrderTransitionReqVO → OrderTransitionRespVO` + +#### 使用场景 + +通用状态机触发端点。当 `eventCode=TERMINATE` 时等价于调用终止接口，触发同样的错误码 584132/584100。 + +#### 入参字段表 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | - | 订单ID | +| eventCode | Body | String | ✅ | - | 事件码（本变更涉及 TERMINATE） | + +#### 出参字段表 + +| 字段 | 类型 | 说明 | +|------|------|------| +| success | Boolean | 是否成功 | +| oldStatus | String | 变更前粗状态 | +| newStatus | String | 变更后粗状态 | + +#### 请求示例 + +```json +{ + "eventCode": "TERMINATE", + "comment": "客户提前返程" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "data": { + "success": true, + "oldStatus": "TRAVELLING", + "newStatus": "COMPLETED" + }, + "success": true +} +``` + +#### 空数据 / 降级响应 + +无。 + +#### 错误响应 + +```json +{ + "code": 584132, + "message": "用车需求未完成，暂不能终止行程，请等车务配车完成后再试", + "success": false +} +``` + +```json +{ + "code": 584100, + "message": "车务车辆总车费暂时不可用，请稍后重试", + "success": false +} +``` + +#### 业务边界 + +- **eventCode=TERMINATE**：触发终止行程逻辑，返回同样的错误码 584132/584100 +- **失败回滚**：状态变更失败时不落库，可安全重试 + + --- ## 四、契约约束与正确调用方式 @@ -327,7 +404,7 @@ GET /v3/admin/order/1934567890123456789/terminate-refund/preview ## 八、测试环境已验证 ``` -POST /v3/admin/order/{id}/terminate-refund/preview → 200 ✓ +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 ✓ ```