From a47588b9a471928d8f829cd2850687b5fac37960 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Tue, 19 May 2026 11:10:11 +0800 Subject: [PATCH] =?UTF-8?q?docs(v3-order):=20=C2=A76.2/=C2=A76.3=20?= =?UTF-8?q?=E4=BA=8C=E6=AC=A1=E4=BF=AE=E8=AE=A2=20=E2=80=94=20OrderStatus/?= =?UTF-8?q?OrderFlowStatus=20=E5=AF=B9=E9=BD=90=20SRS?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 第一轮 commit 89a1938 按当时代码写了 §6.2 10 项（含 REFUNDING）+ §6.3 13 项支付术语， 但代码本身已偏离 SRS v5.48 设计。HL@PR #2589 完成代码回归 SRS 重构，本次同步修订 changelog： §6.2 orderStatus：10 → 9 项 - 删除 REFUNDING（SRS 决议：退款发起瞬间订单 order_status='CANCELLED'， 退款进度由 refund_status 子字段表达） - 保留 PENDING_BALANCE（业务上 SET_PENDING_BALANCE 事件支持重开尾款） §6.3 flowStatus：13 → 15 项 完全重写为业务术语 - 旧 13 项支付节奏视角（AWAITING_DEPOSIT / DEPOSIT_PAID_PENDING_CONFIRM / CONFIRMED_PENDING_HOTEL...）全废弃 - 新 15 项业务环节视角（AWAITING_PROFILE / AWAITING_HOTEL_SUBMIT / HOTEL_IN_PROGRESS / PENDING_CONFIRM...），与 SRS v5.48 §0.4 行 636 1:1 对齐 受影响的示例值同步修订（5 处）： - §3.1 创单 flowStatus 默认值 AWAITING_DEPOSIT → AWAITING_PROFILE - §3.2 列表示例 flowStatus CONFIRMED_PENDING_DEPARTURE → PENDING_DEPARTURE - §3.3 主聚合示例 flowStatus CONFIRMED_PENDING_DEPARTURE → PENDING_DEPARTURE - §3.11 取消预览业务边界粗状态集补 PENDING_BALANCE - §3.14 transition 出参示例 newFlowStatus CONFIRMED_PENDING_DEPARTURE → PENDING_DEPARTURE 关联 - Issue: https://git.1814.love:8443/wx/hl-api-changelog/issues/1 - 后端 PR: https://git.1814.love:8443/wx/HL/pulls/2589 - 第一轮 changelog commit: 89a1938（部分被本次覆盖） --- .../18_§1_订单核心模块-新增接口-管理后台.md | 49 ++++++++++--------- 1 file changed, 25 insertions(+), 24 deletions(-) diff --git a/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md b/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md index e11d75c..35504b6 100644 --- a/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md +++ b/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md @@ -87,7 +87,7 @@ | `orderNo` | String | 订单号，格式 `HL{yyyyMMddHHmmss}{3 位序号}` | | `displayOrderNo` | String | 展示订单号 = `orderNo + teamNo`；`teamNo` 为空时等同 `orderNo` | | `orderStatus` | String | 创单后固定 `PENDING_PAY`（枚举见 §6.2） | -| `flowStatus` | String | 创单后固定 `AWAITING_DEPOSIT`（枚举见 §6.3） | +| `flowStatus` | String | 创单后固定 `AWAITING_PROFILE`（枚举见 §6.3） | | `consultantId` | String | 实际绑定的定制师 ID | | `consultantSource` | String | 定制师来源（枚举见 §6.4） | | `tags` | List\ | 标签列表（含入参 tags + 系统自动标签） | @@ -165,7 +165,7 @@ Content-Type: application/json "orderNo": "HL20260518220000001", "displayOrderNo": "HL20260518220000001", "orderStatus": "PENDING_PAY", - "flowStatus": "AWAITING_DEPOSIT", + "flowStatus": "AWAITING_PROFILE", "consultantId": "50001234567890", "consultantSource": "DEFAULT_ASSIGNED", "tags": ["VIP 客户", "含儿童"], @@ -285,7 +285,7 @@ Authorization: Bearer {admin_jwt} "departureDate": "2026-06-01", "tripDays": 3, "orderStatus": "PENDING_DEPARTURE", - "flowStatus": "CONFIRMED_PENDING_DEPARTURE", + "flowStatus": "PENDING_DEPARTURE", "totalAmount": 8580.00, "paidAmount": 8580.00, "balanceAmount": 0.00, @@ -407,7 +407,7 @@ Authorization: Bearer {admin_jwt} "productName": "长白山天池3日深度游", "tierName": "经典档", "orderStatus": "PENDING_DEPARTURE", - "flowStatus": "CONFIRMED_PENDING_DEPARTURE", + "flowStatus": "PENDING_DEPARTURE", "totalAmount": 8580.00, "paidAmount": 8580.00, "balanceAmount": 0.00, @@ -1053,7 +1053,7 @@ Content-Type: application/json #### 业务边界 -- ✅ **适用**：订单粗状态 ∈ {PENDING_PAY, PENDING_COMPLETE, CUSTOMIZING, PENDING_DEPARTURE}（注：v3 状态机已删除「已确认」，由 CONFIRM event 直接迁到 PENDING_DEPARTURE） +- ✅ **适用**：订单粗状态 ∈ {PENDING_PAY, PENDING_COMPLETE, CUSTOMIZING, PENDING_DEPARTURE, PENDING_BALANCE}（v3 状态机：CONFIRM event 直接迁到 PENDING_DEPARTURE；尾款重开切到 PENDING_BALANCE） - ❌ **拒绝**：已取消 / 已完成 / 退款中 → `581050` - ⚠️ **`daysToDeparture` 负数**：已过出发日，前端应引导走 §3.13 出行中取消（on-trip）而非本接口预览 @@ -1303,7 +1303,7 @@ Content-Type: application/json "oldStatus": "CUSTOMIZING", "newStatus": "PENDING_DEPARTURE", "oldFlowStatus": "PENDING_CONFIRM", - "newFlowStatus": "CONFIRMED_PENDING_DEPARTURE", + "newFlowStatus": "PENDING_DEPARTURE", "triggeredEvents": ["ASYNC_CONTRACT_GENERATE", "ASYNC_INSURANCE_ISSUE"] }, "msg": "success" @@ -1483,7 +1483,7 @@ Authorization: Bearer {admin_jwt} **使用字段**：§3.1 出参 / §3.2 出参 / §3.3 main / §3.2 入参过滤 -> 后端 enum：`com.hulalv.order.core.enums.OrderStatus`，共 10 个值。**API 传/返均为英文枚举值（DB 存什么前端拿什么，前端自己映射中文标签）**。 +> 后端 enum：`com.hulalv.order.core.enums.OrderStatus`，共 **9 项**（v5.49 对齐 SRS：退款粗态已移除，退款发起瞬间订单 order_status 直接变为 `CANCELLED`，退款进度由 refund_status 子字段记录）。**API 传/返均为英文枚举值，中文标签前端自己映射**。 | 值 | 中文标签 | 说明 | |----|------|------| @@ -1491,34 +1491,35 @@ Authorization: Bearer {admin_jwt} | `PENDING_COMPLETE` | 待完善 | 订金到账后进入 | | `CUSTOMIZING` | 定制中 | 出行人 + 房车齐前 | | `PENDING_DEPARTURE` | 待出行 | 确认锁单后 | -| `PENDING_BALANCE` | 待付尾款 | 切到「待支付尾款」细状态时归此粗态（状态机粗态目标） | +| `PENDING_BALANCE` | 待付尾款 | 重开尾款场景（SET_PENDING_BALANCE 事件迁入） | | `TRAVELLING` | 出行中 | 已发车 | | `REVIEWING` | 核单中 | 出行结束待财务核算 | | `SETTLED` | 已结算 | 财务核算完成 | -| `REFUNDING` | 退款中 | 退款流程进行中（状态机粗态目标） | -| `CANCELLED` | 已取消 | — | +| `CANCELLED` | 已取消 | 含退款流程中的订单（refund_status 区分进度） | ### 6.3 flowStatus（订单细状态） **使用字段**：§3.1 出参 / §3.2 出参 / §3.3 main / §3.2 入参过滤 -> 后端 enum：`com.hulalv.order.core.enums.OrderFlowStatus`，共 13 个值。flow_status 列只承载流程细节，不喂状态机；粗态见 §6.2。 +> 后端 enum：`com.hulalv.order.core.enums.OrderFlowStatus`，共 **15 项**（v5.49 全量重写：原 13 项支付节奏视角已废，现采 SRS v5.48 §0.4 行 636 业务环节视角，与 SRS 中文 1:1 对齐）。flow_status 列只承载流程细节，不喂状态机；粗态见 §6.2。 | 值 | 中文标签 | 说明 | |----|------|------| -| `AWAITING_DEPOSIT` | 待支付订金 | 创单默认细状态 | -| `DEPOSIT_PAID_PENDING_CONFIRM` | 已付订金待确认 | — | -| `FULLY_PAID_PENDING_CONFIRM` | 已全款待确认 | — | -| `PENDING_CONFIRM` | 待确认 | — | -| `CONFIRMED_PENDING_HOTEL` | 已确认配房中 | — | -| `CONFIRMED_PENDING_VEHICLE` | 已确认配车中 | — | -| `CONFIRMED_PENDING_DEPARTURE` | 已确认待出行 | 确认锁单后默认细状态 | -| `DEPOSIT_PAID` | 已付订金 | — | -| `FULLY_PAID` | 已全款 | — | -| `REFUNDED` | 已退款 | — | -| `COMPLETED` | 已完成 | — | -| `TRAVELER_INCOMPLETE` | 出行人待完善 | — | -| `CANCELLED_BEFORE_PAY` | 未付款取消 | 取消时未支付任何金额走此值 | +| `AWAITING_PROFILE` | 待补全信息 | 订金到账后默认细态 | +| `AWAITING_HOTEL_SUBMIT` | 待提交房型 | 出行人齐全后等定制师提交房型需求 | +| `AWAITING_HOTEL_CLAIM` | 待抢房 | 房型需求提交后进入抢单池 | +| `HOTEL_IN_PROGRESS` | 房控处理中 | 房控已接单配置中 | +| `HOTEL_NEED_ADJUST` | 房控需调整 | 房控需求调整中 | +| `AWAITING_VEHICLE_SUBMIT` | 待提交用车 | 出行人齐全后等定制师提交用车需求 | +| `VEHICLE_IN_PROGRESS` | 车控处理中 | 车控已接单配置中 | +| `VEHICLE_NEED_ADJUST` | 车控需调整 | 车控需求调整中 | +| `PENDING_CONFIRM` | 待确认 | 房车齐后等定制师确认锁单 | +| `PENDING_DEPARTURE` | 待出行 | 确认锁单后默认细态 | +| `TRAVELLING` | 出行中 | 已发车 | +| `PENDING_REVIEW` | 待核单 | 出行结束等核单 | +| `REVIEWING` | 核单中 | 财务核单中 | +| `SETTLED` | 已结算 | 核单通过 | +| `CANCELLED` | 已取消 | 终态 | ### 6.4 consultantSource（定制师分配来源）