From 1175979e125aaeac3b94e227af47cd28f074f0bf Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Tue, 19 May 2026 16:26:29 +0800
Subject: [PATCH] =?UTF-8?q?docs(=C2=A71=20=E8=AE=A2=E5=8D=95=E6=A0=B8?=
 =?UTF-8?q?=E5=BF=83=E6=A8=A1=E5=9D=97):=20=E5=90=8C=E6=AD=A5=20HL@087c433?=
 =?UTF-8?q?1=20=E2=80=94=20=C2=A71.2=20=E5=8A=A0=20teamNo=20+=20=C2=A76.17?=
 =?UTF-8?q?=20=E4=B8=89=E5=85=83=E7=BB=84=E5=8C=96=20+=20=E5=8A=A0?=
 =?UTF-8?q?=E9=9D=9E=20transition=20=E6=AE=B5=E8=90=BD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

回应前端 mmg 在 #2 issue 提的 2 处契约空白：

§3.2 §1.2 OrderListItemRespVO
- 字段表 17 → 18 字段，新增 teamNo（订金支付成功时生成；列表"团号"展示用）
- 响应 JSON 示例同步加 teamNo 字段
- 前端不再从 displayOrderNo substr 解析团号

§6.17 transition eventCode
- 9 行平铺表 → 16 条规则三元组（事件 → 前置态 → 目标态）
- 显式标注 CONFIRM 复用 2 种语义：
  · CUSTOMIZING → PENDING_DEPARTURE = 确认锁单
  · REVIEWING → SETTLED = 核单通过 / 确认结算
- FINISH 仅用于 TRAVELLING → REVIEWING（结团，不是结算）
- 新增 §6.17.2「非 transition 业务路径」段落：
  · 核单结算走独立 6 步接口 /settlement/step{1-6}/*，Step 6 submit 内部自动推 REVIEWING → SETTLED，前端不 fire eventCode
  · 退款走独立退款接口
  · 「申请解锁」v3 已砍，前端隐藏对应按钮

§13 关联链接 v5.49 → v5.50（同步 PR #2614 升的设计文档版本号）

关联：
- HL PR: https://git.1814.love:8443/wx/HL/pulls/2614 (merged 087c4331)
- 前端 issue: https://git.1814.love:8443/wx/hl-api-changelog/issues/2
---
 .../18_§1_订单核心模块-新增接口-管理后台.md   | 56 +++++++++++++------
 1 file changed, 40 insertions(+), 16 deletions(-)

diff --git a/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md b/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md
index 35504b6..813acde 100644
--- a/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md
+++ b/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md
@@ -222,12 +222,13 @@ Content-Type: application/json
 
 `PageResult` 字段：`list: List<OrderListItemRespVO>` / `total: Long` / `page` / `pageSize`
 
-`OrderListItemRespVO`（17 字段）：
+`OrderListItemRespVO`（18 字段）：
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `id` | String | 订单 ID |
 | `orderNo` | String | 订单号 |
+| `teamNo` | String? | 团号（订金支付成功时生成，创单时为 null）|
 | `displayOrderNo` | String | 完整展示订单号 |
 | `productName` | String | 产品名（快照） |
 | `productCoverImg` | String | 产品封面 URL |
@@ -275,6 +276,7 @@ Authorization: Bearer {admin_jwt}
       {
         "id": "60123456789012",
         "orderNo": "HL20260510143025001",
+        "teamNo": "20260601A",
         "displayOrderNo": "HL20260510143025001-T20260601A",
         "productName": "长白山天池3日深度游",
         "productCoverImg": "https://oss.hulalv.com/p/changbai-cover.jpg",
@@ -1665,19 +1667,41 @@ Authorization: Bearer {admin_jwt}
 
 **使用字段**：§3.14 入参 `eventCode`
 
-> 后端 enum：`com.hulalv.order.core.enums.OrderEvent`，共 9 个值。状态机由 `OrderStateMachineConfig` 16 条 transition 规则驱动。
+> 后端 enum：`com.hulalv.order.core.enums.OrderEvent`，共 **9 个值**。
+> 状态机由 `OrderStateMachineConfig` **16 条规则**驱动。
 
-| 值 | 说明 |
-|----|------|
-| `PAY_DEPOSIT` | 客户支付订金 |
-| `PAY_FULL` | 客户支付全款 |
-| `SET_PENDING_BALANCE` | 切到「待支付尾款」细状态 |
-| `SET_PENDING_DEPARTURE` | 切到「待出行」细状态（系统时机到达） |
-| `CONFIRM` | 定制师确认锁单（需先通过 §3.15 checklist） |
-| `INITIATE_REFUND` | 发起退款 |
-| `CANCEL` | 取消订单 |
-| `DEPART` | 标记出发（订单进入「出行中」） |
-| `FINISH` | 标记完成 |
+#### 6.17.1 完整规则表（事件 → 前置态 → 目标态）
+
+| 事件 | 前置态（orderStatus） | 目标态（orderStatus） | 业务语义 |
+|------|---|---|---|
+| `PAY_DEPOSIT` | `PENDING_PAY` | `CUSTOMIZING` | 客户支付订金 |
+| `PAY_FULL` | `PENDING_PAY` | `CUSTOMIZING` | 客户支付全款 |
+| `CANCEL` | `PENDING_PAY` | `CANCELLED` | 未付款取消 |
+| `CONFIRM` ⚠️ | `CUSTOMIZING` | `PENDING_DEPARTURE` | **确认锁单**（语义 ①，需先通过 §3.15 checklist）|
+| `SET_PENDING_BALANCE` | `PENDING_DEPARTURE` | `PENDING_BALANCE` | 重新开放尾款 / 调整价格 |
+| `DEPART` | `PENDING_DEPARTURE` | `TRAVELLING` | 开始出行 |
+| `SET_PENDING_DEPARTURE` | `PENDING_BALANCE` | `PENDING_DEPARTURE` | 尾款补齐 |
+| `FINISH` | `TRAVELLING` | `REVIEWING` | 结团（进入核单）|
+| `CONFIRM` ⚠️ | `REVIEWING` | `SETTLED` | **核单通过 / 确认结算**（语义 ②）|
+| `CANCEL` | `CUSTOMIZING` | `CANCELLED` | 定制中取消 |
+| `CANCEL` | `TRAVELLING` | `CANCELLED` | 出行中取消 |
+| `INITIATE_REFUND` | `CUSTOMIZING` | `CANCELLED` | 定制中发起退款 |
+| `INITIATE_REFUND` | `PENDING_DEPARTURE` | `CANCELLED` | 待出行发起退款 |
+| `INITIATE_REFUND` | `PENDING_BALANCE` | `CANCELLED` | 待付尾款发起退款 |
+| `INITIATE_REFUND` | `REVIEWING` | `CANCELLED` | 核单中发起退款 |
+| `INITIATE_REFUND` | `SETTLED` | `CANCELLED` | 已结算售后退款 |
+
+⚠️ **`CONFIRM` 事件复用 2 种语义**：状态机以「当前粗态 + 事件」找规则，不会冲突，但前端按钮文案要按当前状态判断（CUSTOMIZING 下叫"确认锁单"，REVIEWING 下叫"确认结算"）。
+
+#### 6.17.2 非 transition 业务路径（不走本接口）
+
+下列业务**不走** `POST /v3/admin/order/{id}/transition`，前端按对应独立接口调用：
+
+| 业务 | 独立接口 | 备注 |
+|---|---|---|
+| **核单结算（6 步）** | `PUT /v3/admin/order/{id}/settlement/step1` ~ `step4`<br>`GET / POST / DELETE /v3/admin/order/{id}/settlement/step5/*`<br>`POST /v3/admin/order/{id}/settlement/step6/submit`<br>`GET /v3/admin/order/{id}/settlement/summary` | Step 6 submit 内部事务自动推 `REVIEWING → SETTLED`，前端**不要**自己 fire `eventCode` |
+| **退款发起** | 退款专用接口（详见 refund 模块 changelog） | `INITIATE_REFUND` 是 transition 事件，但前端入口走独立退款按钮 |
+| **申请解锁** | **v3 已砍** | 原型 UnlockModal 按钮 v3 不实现；前端隐藏对应按钮 |
 
 ### 6.18 transition triggeredEvents（状态机副作用事件）
 
@@ -1739,9 +1763,9 @@ Authorization: Bearer {admin_jwt}
 
 ## 13. 关联
 
-- **API 设计文档**: `docs/order-v3/api/API-SPEC-V5.49.html` §1.1 ~ §1.4
-- **SRS 业务规格**: `docs/order-v3/srs/order-cloud-v3-srs-v5.49.html` §F1 创单 / §1.0i 模型 / §1.3 创单流程
-- **数据库 Schema**: `docs/order-v3/database/DATABASE-SCHEMA-V5.49.html` §1.1 order_main / §1.2 order_tag
+- **API 设计文档**: `docs/order-v3/api/API-SPEC-V5.50.html` §1.1 ~ §1.4
+- **SRS 业务规格**: `docs/order-v3/srs/order-cloud-v3-srs-v5.50.html` §F1 创单 / §1.0i 模型 / §1.3 创单流程
+- **数据库 Schema**: `docs/order-v3/database/DATABASE-SCHEMA-V5.50.html` §1.1 order_main / §1.2 order_tag
 - **后端负责人**: @yaosutu
 
 ---