From 172ab448006dda8f8c32fdca891f390770015481 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Mon, 18 May 2026 16:47:10 +0800 Subject: [PATCH] =?UTF-8?q?docs(order-v3):=20=C2=A71=20changelog=20?= =?UTF-8?q?=E8=A1=A5=20=C2=A71B=20+=20=C2=A71C=20=E5=85=B1=205=20=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=EF=BC=8C=C2=A71=20=E6=A8=A1=E5=9D=97=2015=20=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=E4=B8=80=E6=AC=A1=E6=8E=A8=E5=85=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按用户反馈，§1B 取消订单 + §1C 状态机+锁单 与 §1A 一起推送（不分批）： 新增接口： - §3.11 §1.5.0 GET /v3/admin/order/{id}/cancel-preview 取消预览（只读） - §3.12 §1.5.1 POST /v3/admin/order/{id}/cancel/pre-trip 取消出行前（企微 OA + 退款） - §3.13 §1.5.2 POST /v3/admin/order/{id}/cancel/on-trip 取消出行中（仅登记返还） - §3.14 §1.7 POST /v3/admin/order/{id}/transition 状态机通用入口 - §3.15 §1.8 GET /v3/admin/order/{id}/confirm-checklist 锁单前置 5 项校验 每个接口按"自含"结构：使用场景 / 认证 / 入参 / 出参 / 错误码 / 业务边界 / 示例（请求+响应）。 §6 枚举新增： - §6.17 transition eventCode 9 个状态机事件 - §6.18 transition triggeredEvents 6 个副作用事件 - §6.19 checklist item code 5 项前置校验 - §6.20 customerChannel 通知渠道 3 值 §0 / §2 / §11 / §12 同步更新："待补" 移除，全部 ✅；变更清单加 5 行；注意事项加取消订单分支说明 + CONFIRM 锁单约束。 文件从 1235 行 → 1730 行（diff +506 / -11）。 --- .../18_§1_订单核心模块-新增接口-管理后台.md | 517 +++++++++++++++++- 1 file changed, 506 insertions(+), 11 deletions(-) diff --git a/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md b/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md index 9c8c74b..aadac21 100644 --- a/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md +++ b/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md @@ -8,13 +8,12 @@ ## 0. 模块全貌 -| 子模块 | 含接口 | 接口数 | 推送状态 | +| 子模块 | 含接口 | 接口数 | 状态 | |---|---|---|---| -| **§1A 订单 CRUD + 详情** | §1.1 创建 / §1.2 列表 / §1.3.1 详情主聚合 / §1.3.2~§1.3.7 6 Tab 子接口 / §1.4 修改 | **10** | ✅ **本次推送** | -| §1B 取消订单 | §1.5.0 预览 / §1.5.1 出行前 / §1.5.2 出行中 | 3 | 📝 待补 | -| §1C 状态机 + 锁单 | §1.7 transition / §1.8 confirm-checklist | 2 | 📝 待补 | - -> 📌 本文件为 §1 模块**累计** changelog，后续 §1B / §1C 落地时通过追加 commit 扩充同一文件。 +| **§1A 订单 CRUD + 详情** | §1.1 创建 / §1.2 列表 / §1.3.1 详情主聚合 / §1.3.2~§1.3.7 6 Tab 子接口 / §1.4 修改 | **10** | ✅ | +| **§1B 取消订单** | §1.5.0 预览 / §1.5.1 出行前 / §1.5.2 出行中 | **3** | ✅ | +| **§1C 状态机 + 锁单** | §1.7 transition / §1.8 confirm-checklist | **2** | ✅ | +| **§1 合计** | — | **15** | ✅ 本次推送 | --- @@ -22,7 +21,7 @@ 订单服务 v3（hl-order-service-v3 全新二期）的订单核心模块 §1 core 提供订单管理基础能力，覆盖定制师 B 端代下单 / 多维度筛选列表 / 订单详情（首屏主聚合 + 6 个 Tab 独立懒加载）/ 非关键字段修改。 -本次（§1A）推送 10 个接口，对应管理后台原型 F8-F20（订单列表+创建+详情主体）、F22-F26（详情各 Tab 单刷新）、F37（修改订单字段）。 +本次推送 §1 模块**全 15 个接口**，对应管理后台原型 F8-F20（订单列表+创建+详情主体）、F22-F26（详情各 Tab 单刷新）、F37（修改订单字段）、F30-F32（取消订单弹框+出行前/出行中）、F33-F34（确认锁单 checklist + 状态机操作）。 --- @@ -40,6 +39,11 @@ | 8 | 1.3.6 | 退款明细 Tab | GET | `/v3/admin/order/{id}/refund` | | 9 | 1.3.7 | 服务标准 Tab | GET | `/v3/admin/order/{id}/service-standard` | | 10 | 1.4 | 修改订单字段 | PUT | `/v3/admin/order/{id}` | +| 11 | 1.5.0 | 取消订单预览 | GET | `/v3/admin/order/{id}/cancel-preview` | +| 12 | 1.5.1 | 取消订单（出行前） | POST | `/v3/admin/order/{id}/cancel/pre-trip` | +| 13 | 1.5.2 | 取消订单（出行中） | POST | `/v3/admin/order/{id}/cancel/on-trip` | +| 14 | 1.7 | 状态变更操作（状态机） | POST | `/v3/admin/order/{id}/transition` | +| 15 | 1.8 | 确认锁单前置 Checklist | GET | `/v3/admin/order/{id}/confirm-checklist` | --- @@ -1011,6 +1015,443 @@ Content-Type: application/json --- +### 3.11 §1.5.0 取消订单预览（只读） + +**路径**：`GET /v3/admin/order/{id}/cancel-preview` +**使用场景**：定制师点击「取消订单」按钮，弹框打开瞬间调用，展示退款金额 + 扣费 + 退款政策 +**认证**：JWT（admin 角色） | **幂等性**：是（只读不入库） | **限流**：无 +**金额规则**：严格按订单创建时冻结的 `RefundPolicy` 快照计算，不接受人工覆盖 + +#### 入参 + +`id` (path, Long) — 订单 ID + +#### 出参（`Result`） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `refundAmount` | BigDecimal | 退款金额（按 RefundPolicy 计算） | +| `paidAmount` | BigDecimal | 客户已付金额 | +| `deductAmount` | BigDecimal | 扣费金额 = `paidAmount - refundAmount` | +| `daysToDeparture` | Integer | 距出发天数（今天 - 出发日；负数表已过出发日） | +| `refundPolicy` | RefundPolicyVO | 退款政策快照（结构同 §3.9 `refundPolicy`） | + +#### 错误码 + +| code | 含义 | +|------|------| +| `581020` | 订单不存在 | +| `581021` | 无权访问该订单 | +| `581050` | 订单状态不允许取消（已取消 / 已完成 / 退款中等） | + +#### 业务边界 + +- ✅ **适用**：订单粗状态 ∈ {待支付, 待完善, 定制中, 已确认, 待出行} +- ❌ **拒绝**：已取消 / 已完成 / 退款中 → `581050` +- ⚠️ **`daysToDeparture` 负数**：已过出发日，前端应引导走 §3.13 出行中取消（on-trip）而非本接口预览 + +#### 示例 + +**典型（出行前 12 天） - 请求**： + +```http +GET /v3/admin/order/60123456789012/cancel-preview +Authorization: Bearer {admin_jwt} +``` + +**典型 - 响应**： + +```json +{ + "code": 200, + "data": { + "refundAmount": 6864.00, + "paidAmount": 8580.00, + "deductAmount": 1716.00, + "daysToDeparture": 12, + "refundPolicy": { + "policyId": 50001, + "policyName": "标准退改政策", + "tiers": [ + {"minDays": 15, "refundRatio": 100, "label": "出发前 15 天 100%退"}, + {"minDays": 7, "refundRatio": 80, "label": "出发前 7-14 天 80%退"}, + {"minDays": 3, "refundRatio": 50, "label": "出发前 3-6 天 50%退"}, + {"minDays": 0, "refundRatio": 0, "label": "出发前 2 天内不退"} + ] + } + }, + "msg": "success" +} +``` + +--- + +### 3.12 §1.5.1 取消订单 - 出行前（pre-trip） + +**路径**：`POST /v3/admin/order/{id}/cancel/pre-trip` +**使用场景**：定制师代客取消出行前订单。走企微 OA 审批 + 通道退款 +**认证**：JWT（admin 角色） | **幂等性**：否（提交企微 OA + 创建退款申请） | **限流**：无 +**金额规则**：严格按 `RefundPolicy` 计算，不接受人工覆盖（金额由 §3.11 预览给定） + +#### 入参（`OrderCancelPreTripReqVO`） + +| 字段 | 类型 | 必填 | 说明 | 校验规则 | +|------|------|:----:|------|----------| +| `cancelReason` | String | ✅ | 取消原因（前端可选下拉 + 自由填写） | `@NotBlank` | +| `cancelDetail` | String | ❌ | 详细说明 | — | + +#### 出参（`Result`） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `refundApplicationId` | Long | 退款申请 ID（已提企微 OA） | +| `refundAmount` | BigDecimal | 退款金额（按 RefundPolicy 政策计算） | +| `pendingApprovalMsg` | String | 审批中提示文案 | +| `newStatus` | String | 取消后订单状态（如 `退款中`） | + +#### 错误码 + +| code | 含义 | +|------|------| +| `581020` | 订单不存在 | +| `581021` | 无权访问该订单 | +| `581050` | 订单状态不允许取消（已取消 / 已完成 / 退款中） | +| `581051` | 订单已过出发日，需走 §3.13 on-trip 取消 | +| `581052` | 企微 OA 提交失败 | + +#### 业务边界 + +- ✅ **适用**：订单状态可取消 + `daysToDeparture` ≥ 0 +- ❌ **拒绝**：出发日过 / 状态不可取消 +- ⚠️ **不可重复提交**：同一订单存在 PENDING 退款申请时第二次调用返 `581050` + +#### 示例 + +**典型 - 请求**： + +```http +POST /v3/admin/order/60123456789012/cancel/pre-trip +Authorization: Bearer {admin_jwt} +Content-Type: application/json + +{ + "cancelReason": "客户临时有事无法出行", + "cancelDetail": "客户家属突发疾病需照顾" +} +``` + +**典型 - 响应**： + +```json +{ + "code": 200, + "data": { + "refundApplicationId": 95001234567890, + "refundAmount": 6864.00, + "pendingApprovalMsg": "已提交企微审批，预计 2 小时内完成", + "newStatus": "退款中" + }, + "msg": "success" +} +``` + +--- + +### 3.13 §1.5.2 取消订单 - 出行中（on-trip） + +**路径**：`POST /v3/admin/order/{id}/cancel/on-trip` +**使用场景**：定制师代客取消出行中订单。**仅登记返还金额**，不走支付通道（返还金额在核单 Step 5 自动拉取结算） +**认证**：JWT（admin 角色） + +#### 入参（`OrderCancelOnTripReqVO`） + +| 字段 | 类型 | 必填 | 说明 | 校验规则 | +|------|------|:----:|------|----------| +| `cancelReason` | String | ✅ | 取消原因 | `@NotBlank` | +| `returnAmount` | BigDecimal | ✅ | 定制师手填的返还金额（不走政策算） | `@NotNull` `@DecimalMin(0, exclusive)` | +| `returnRemark` | String | ✅ | 返还金额备注（说明已用成本扣除项） | `@NotBlank` | + +#### 出参（`Result`） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `settlementRefundId` | Long | 返还登记 ID | +| `returnAmount` | BigDecimal | 已登记的返还金额（= 入参回显） | +| `newStatus` | String | 取消后状态（`已取消`） | + +#### 错误码 + +| code | 含义 | +|------|------| +| `581020` | 订单不存在 | +| `581021` | 无权访问该订单 | +| `581053` | 订单未出发，不能走 on-trip 取消 | +| `581054` | 订单已完成，不能取消 | +| `581055` | `returnAmount` 大于 `paidAmount` | + +#### 业务边界 + +- ✅ **适用**：订单粗状态 = `出行中` 或 `已确认` 但已过出发日 +- ❌ **拒绝**：未出发 → `581053`；已完成 → `581054`；返还金额超额 → `581055` +- ⚠️ **不走支付通道**：本接口**只登记**返还金额，不发起实退；实退在核单 Step 5 走 + +#### 示例 + +**典型 - 请求**： + +```http +POST /v3/admin/order/60123456789012/cancel/on-trip +Authorization: Bearer {admin_jwt} +Content-Type: application/json + +{ + "cancelReason": "客户中途突发疾病", + "returnAmount": 2500.00, + "returnRemark": "已用 2 天住宿+用车+导游，扣除 5880 元" +} +``` + +**典型 - 响应**： + +```json +{ + "code": 200, + "data": { + "settlementRefundId": 96001234567890, + "returnAmount": 2500.00, + "newStatus": "已取消" + }, + "msg": "success" +} +``` + +--- + +### 3.14 §1.7 状态变更操作（通用状态机） + +**路径**：`POST /v3/admin/order/{id}/transition` +**使用场景**：所有由状态机驱动的操作统一走此接口。例如「确认锁单」「关闭订单」「触发尾款支付」等 +**认证**：JWT（admin 角色） | **幂等性**：否（写 `order_status_log`） +**副作用**：根据 `eventCode` 触发不同副作用（生成合同 / 投保 / 通知司机等），副作用列表在响应 `triggeredEvents` 中返回 + +#### 入参（`OrderTransitionReqVO`） + +| 字段 | 类型 | 必填 | 说明 | 校验规则 | +|------|------|:----:|------|----------| +| `eventCode` | String | ✅ | 状态机事件代码（枚举见 §6.17） | `@NotBlank` | +| `reason` | String | ❌ | 操作原因（按 event 强制要求时必填） | — | +| `payload` | Map\ | ❌ | 事件相关额外数据（不同 event 含义不同） | — | + +#### 出参（`Result`） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `success` | Boolean | 是否成功 | +| `oldStatus` | String | 变更前粗状态 | +| `newStatus` | String | 变更后粗状态 | +| `oldFlowStatus` | String | 变更前细状态 | +| `newFlowStatus` | String | 变更后细状态 | +| `triggeredEvents` | List\ | 副作用事件列表（枚举见 §6.18） | + +#### 错误码 + +| code | 含义 | +|------|------| +| `581020` | 订单不存在 | +| `581021` | 无权访问该订单 | +| `581060` | `eventCode` 枚举非法 | +| `581061` | 当前状态不允许该 event（状态机迁移非法） | +| `581062` | `reason` 必填但未传（如 `CANCEL` event） | +| `581063` | 前置 checklist 未全通过（如 `CONFIRM` event 时需 §3.15 全 ✅） | + +#### 业务边界 + +- ✅ **状态机驱动**：触发条件由后端状态机定义，前端只传 `eventCode`，不需要懂迁移规则 +- ⚠️ **`CONFIRM` event 强约束**：调用前必须先调 §3.15 confirm-checklist 且 `allPassed=true`，否则返 `581063` +- ⚠️ **副作用异步**：`triggeredEvents` 中 `ASYNC_*` 前缀的事件是异步执行的，本接口返回时副作用可能未完成（用 status-log Tab §3.7 跟踪） + +#### 示例 + +**典型（确认锁单） - 请求**： + +```http +POST /v3/admin/order/60123456789012/transition +Authorization: Bearer {admin_jwt} +Content-Type: application/json + +{ + "eventCode": "CONFIRM", + "reason": "定制师确认所有前置条件已完成", + "payload": {} +} +``` + +**典型 - 响应**： + +```json +{ + "code": 200, + "data": { + "success": true, + "oldStatus": "定制中", + "newStatus": "待出行", + "oldFlowStatus": "待确认", + "newFlowStatus": "待出行", + "triggeredEvents": ["ASYNC_CONTRACT_GENERATE", "ASYNC_INSURANCE_ISSUE"] + }, + "msg": "success" +} +``` + +**异常（checklist 未通过 581063） - 请求**：（同上 `eventCode=CONFIRM`，但订单存在未完善出行人） + +**异常 - 响应**： + +```json +{ "code": 581063, "data": null, "msg": "前置 checklist 未全通过：出行人信息未完善 1/3" } +``` + +--- + +### 3.15 §1.8 确认锁单前置 Checklist + +**路径**：`GET /v3/admin/order/{id}/confirm-checklist` +**使用场景**：定制师点击「确认订单」按钮时调用。 +- 返回 5 项前置校验明细（决定按钮是否可点） +- 通过时返回"确认行程"弹框预览数据（行程概览 + 自动副作用 + 通知项） +- 不通过时 `preview=null`，前端展示 5 项 `failReason` 列表 + `actionPath` 跳转引导 + +**认证**：JWT（admin 角色） | **幂等性**：是（只读不入库） + +#### 入参 + +`id` (path, Long) — 订单 ID + +#### 出参（`Result`） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `allPassed` | Boolean | 是否全部通过（任一项不通过则 false） | +| `items` | List\ | 5 项详细结果 | +| `preview` | PreviewVO? | 确认行程弹框预览（仅 `allPassed=true` 时返回） | + +`ChecklistItemVO`： +| 字段 | 类型 | 说明 | +|------|------|------| +| `code` | String | 检查项代码（枚举见 §6.19） | +| `passed` | Boolean | 是否通过 | +| `failReason` | String? | 未通过原因（通过时 null） | +| `actionPath` | String? | 引导操作路径（如配房页跳转；通过时 null） | + +`PreviewVO`（仅 `allPassed=true` 时存在）： +| 字段 | 类型 | 说明 | +|------|------|------| +| `departureDate` | LocalDate | 出发日期 | +| `totalPeopleCount` | Integer | 总出行人数（4 类相加） | +| `driverName` | String | 司机姓名 | +| `driverPhoneMasked` | String | 司机手机（脱敏） | +| `hotels` | List\<{cityName, hotelName}\> | 酒店列表（按行程城市分组） | +| `contractAutoAction.planName` | String | 合同方案名（产品快照） | +| `contractAutoAction.autoSign` | Boolean | 是否自动发送给客户线上签署 | +| `insuranceAutoAction.planName` | String | 保险产品名 | +| `insuranceAutoAction.peopleCount` | Integer | 投保人数（= `totalPeopleCount`） | +| `insuranceAutoAction.effectiveDescription` | String | 生效时间描述 | +| `notifications.notifyDriver` | Boolean | 是否通知司机 | +| `notifications.notifyHotel` | Boolean | 是否通知酒店确认房态 | +| `notifications.notifyCustomer` | Boolean | 是否向客户发送出行提醒 | +| `notifications.customerChannel` | String | 客户通知渠道（`WX` / `SMS` / `MIXED`） | + +#### 错误码 + +| code | 含义 | +|------|------| +| `581020` | 订单不存在 | +| `581021` | 无权访问该订单 | + +#### 业务边界 + +- ✅ **前置校验**：5 项 checklist 用于阻止用户点【确认订单】按钮在前置条件未满足时 +- ⚠️ **`actionPath` 引导**：前端建议按字面值跳转（如 `/admin/order/orders/{id}?tab=overview`），不是后端约定渲染 +- ⚠️ **`preview` 条件返回**：`allPassed=false` 时 `preview` 为 null，前端不渲染预览区 +- ⚠️ **`preview` 数据是预演**：本接口返回的合同方案 / 保险方案是「点击确认后会执行什么」的预演，**不**意味着已经执行（实际执行由 §3.14 `eventCode=CONFIRM` 触发） + +#### 示例 + +**典型（未通过） - 请求**： + +```http +GET /v3/admin/order/60123456789012/confirm-checklist +Authorization: Bearer {admin_jwt} +``` + +**典型（未通过） - 响应**： + +```json +{ + "code": 200, + "data": { + "allPassed": false, + "items": [ + {"code": "TRAVELER_COMPLETE", "passed": false, "failReason": "出行人信息未完善 1/3 (小明缺证件号)", "actionPath": "/admin/order/orders/60123456789012?tab=overview"}, + {"code": "PAYMENT_OK", "passed": true, "failReason": null, "actionPath": null}, + {"code": "HOTEL_DONE", "passed": true, "failReason": null, "actionPath": null}, + {"code": "VEHICLE_DONE", "passed": true, "failReason": null, "actionPath": null}, + {"code": "CONTRACT_TEMPLATE_OK", "passed": true, "failReason": null, "actionPath": null} + ], + "preview": null + }, + "msg": "success" +} +``` + +**典型（全通过） - 请求**：（同上） + +**典型（全通过） - 响应**： + +```json +{ + "code": 200, + "data": { + "allPassed": true, + "items": [ + {"code": "TRAVELER_COMPLETE", "passed": true, "failReason": null, "actionPath": null}, + {"code": "PAYMENT_OK", "passed": true, "failReason": null, "actionPath": null}, + {"code": "HOTEL_DONE", "passed": true, "failReason": null, "actionPath": null}, + {"code": "VEHICLE_DONE", "passed": true, "failReason": null, "actionPath": null}, + {"code": "CONTRACT_TEMPLATE_OK", "passed": true, "failReason": null, "actionPath": null} + ], + "preview": { + "departureDate": "2026-05-30", + "totalPeopleCount": 14, + "driverName": "扎西师傅", + "driverPhoneMasked": "1398761****", + "hotels": [ + {"cityName": "拉萨", "hotelName": "瑞吉度假酒店"}, + {"cityName": "林芝", "hotelName": "悦榕庄"} + ], + "contractAutoAction": { + "planName": "标准跟团方案 v3.2", + "autoSign": true + }, + "insuranceAutoAction": { + "planName": "安联境内旅行险 · 尊享版", + "peopleCount": 14, + "effectiveDescription": "出发前 24h 内生效" + }, + "notifications": { + "notifyDriver": true, + "notifyHotel": true, + "notifyCustomer": true, + "customerChannel": "WX" + } + } + }, + "msg": "success" +} +``` + +--- + ## 6. 枚举 / 数据字典 > 跨接口共享枚举集中列出，按字段分组，标注「使用字段在哪里」。 @@ -1201,13 +1642,66 @@ Content-Type: application/json `OrderMainVO.exceptionBadges` 9 类布尔标识 / `progressStepper.nodes[].key` / `progressStepper.nodes[].status` 字段含义已在 §3.3 出参说明中列出。 +### 6.17 transition eventCode（状态机事件代码） + +**使用字段**：§3.14 入参 `eventCode` + +| 值 | 说明 | +|----|------| +| `PAY_DEPOSIT` | 客户支付订金 | +| `PAY_FULL` | 客户支付全款 | +| `SET_PENDING_BALANCE` | 切到「待支付尾款」细状态 | +| `SET_PENDING_DEPARTURE` | 切到「待出行」细状态（系统时机到达） | +| `CONFIRM` | 定制师确认锁单（需先通过 §3.15 checklist） | +| `INITIATE_REFUND` | 发起退款 | +| `CANCEL` | 取消订单 | +| `DEPART` | 标记出发（订单进入「出行中」） | +| `FINISH` | 标记完成 | + +### 6.18 transition triggeredEvents（状态机副作用事件） + +**使用字段**：§3.14 出参 `triggeredEvents[]` + +| 值 | 说明 | +|----|------| +| `ASYNC_CONTRACT_GENERATE` | 异步生成电子合同 | +| `ASYNC_INSURANCE_ISSUE` | 异步出保单 | +| `NOTIFY_DRIVER` | 通知司机 | +| `NOTIFY_HOTEL` | 通知酒店确认房态 | +| `NOTIFY_CUSTOMER` | 向客户发出行提醒 | +| `ASYNC_REFUND_APPLY` | 异步发起退款申请 | + +> 副作用异步执行，本接口返回时可能未完成；用 §3.7 status-log Tab 跟踪进度。 + +### 6.19 checklist item code（确认锁单前置 5 项） + +**使用字段**：§3.15 出参 `items[].code` + +| 值 | 说明 | +|----|------| +| `TRAVELER_COMPLETE` | 出行人信息完整（姓名 + 证件 + 手机 + 证件类型齐） | +| `PAYMENT_OK` | 支付状态满足（订金或全款到账） | +| `HOTEL_DONE` | 配房完成（hotel_stage = DONE） | +| `VEHICLE_DONE` | 配车完成（vehicle_stage = DONE） | +| `CONTRACT_TEMPLATE_OK` | 合同模板就绪（产品快照含合同方案） | + +### 6.20 customerChannel（客户通知渠道） + +**使用字段**：§3.15 出参 `preview.notifications.customerChannel` + +| 值 | 说明 | +|----|------| +| `WX` | 仅企微 / 微信 | +| `SMS` | 仅短信 | +| `MIXED` | 双通道（企微 + 短信） | + --- ## 11. 影响评估 - **是否破坏向后兼容**：否（v3 全新二期，前端 v3 项目仓库首次消费） - **前端是否必须同步上线**：是 -- **本次推送范围**：§1A 10 接口；§1B 取消订单 / §1C 状态机后续 commit 追加 +- **本次推送范围**：§1 模块全 15 接口（§1A 10 接口 + §1B 取消 3 接口 + §1C 状态机+锁单 2 接口），覆盖订单核心全生命周期入口 --- @@ -1217,6 +1711,8 @@ Content-Type: application/json - **§3.8 / §3.9 条件显示**：`data=null` 时前端不渲染对应 Tab - **首屏 vs 单 Tab 刷新**：详情页打开用 §3.3 主聚合（一次拿 main + tags + overview）；Tab 切换 / 单 Tab 操作完按需调 §3.4 ~ §3.9 - **公司隔离 581021**：所有 §1 接口均带跨公司隔离校验，前端无需自行过滤 +- **取消订单分支**：出行前走 §3.12 走政策算金额 + 企微 OA 审批；出行中走 §3.13 仅登记返还金额（核单 Step 5 自动拉取实退）；前端按 §3.11 预览的 `daysToDeparture` 决定走哪个入口 +- **CONFIRM 锁单**：前端点【确认订单】按钮**必须**先调 §3.15 checklist 拿 `allPassed=true` 再调 §3.14 `eventCode=CONFIRM`，否则后端拒绝（`581063`） --- @@ -1229,7 +1725,6 @@ Content-Type: application/json --- -## 📝 §1B / §1C 推送计划 +## 📝 后续追加计划 -- **§1B 取消订单**（§1.5.0 + §1.5.1 + §1.5.2）：业务联调通过后 commit 追加本文件 -- **§1C 状态机 + 锁单**（§1.7 + §1.8）：状态机完整测试通过后 commit 追加 +§1 模块 15 接口全部首推完毕。后续若有接口字段调整 / 错误码新增 / 业务边界变化，通过追加 commit 扩充本文件。