docs(§1 订单核心模块): 同步 HL@087c4331 — §1.2 加 teamNo + §6.17 三元组化 + 加非 transition 段落

回应前端 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: wx/HL#2614 (merged 087c4331)
- 前端 issue: #2
这个提交包含在:
yaosutu 2026-05-19 16:26:29 +08:00
父节点 a9228e7aa8
当前提交 1175979e12

查看文件

@ -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
---