# 二期 v3：订单进度模型重构 —— 派生线性 6 步 + 嵌套 progressStepper

> **服务**: hl-order-service-v3 ｜ **端**: 管理后台
> **接口**: `GET /v3/admin/order`（列表）、`GET /v3/admin/order/{id}`（详情）、`POST /v3/admin/order`（创建）
> **Issue**: #3365 / #3368 ｜ **PR**: #3366（扁平）+ #3369（嵌套）
> **日期**: 2026-06-03
> **影响**: ⚠️ **破坏性**——删字段 + 改结构。订单进度展示统一为「派生线性 6 步 + 嵌套 progressStepper」。

---

## 一、背景

订单进度此前两套打架：列表用 8 步 `flowStep`，详情用 10 节点 `progressStepper`，同一订单两页进度刻度对不上。本次统一为**派生双层模型**（底层一份数据派生两视图），并修正了核单/结算判定 bug。

---

## 二、变更清单

| 变更 | 说明 |
|---|---|
| ❌ 删 `flowItems` | 列表不再返回 |
| ❌ 删 `progress`("X/8") | 列表不再返回 |
| 🔄 `flowStep` 语义改 | 8 步指针 → **线性 6 步**当前步序号 |
| 🔄 `flowStepTotal` | 8 → **6** |
| 🆕 `flowStepCode` | 当前步英文枚举（列表+详情） |
| 🆕 `flowStepStatus` | 当前步状态（列表+详情） |
| 🆕 `currentSubFlows`（列表） | 当前步=资源准备时的 4 子流程数组 |
| 🔄 `progressStepper`（详情） | 扁平 9 节点 → **嵌套 6 主节点**，加 `code`/`isCurrent`/`subFlows`，删 `parallel` |

> `orderStatus`/`orderStatusName`/`flowStatus`/`flowStatusName` **不变**。

---

## 三、出参字段（进度部分）

### 列表 `GET /v3/admin/order`（`data.records[]`，当前步散字段）

| 字段 | 类型 | 说明 |
|---|---|---|
| `flowStep` | Integer | 当前第几步（1-6；待支付=0；已取消=null） |
| `flowStepTotal` | Integer | 总步数，固定 **6** |
| `flowStepCode` | String | 当前步英文枚举（见枚举表） |
| `flowDisplayText` | String | 当前步中文名 |
| `flowStepStatus` | String | 当前步状态：`DONE`/`PROCESSING`/`WAITING` |
| `currentSubFlows` | Array\<SubFlow\> | **仅当前步=资源准备时非空**，否则 `null` |

### 详情 `GET /v3/admin/order/{id}`（`data.main`）

列表那 6 个散字段**全有**，外加完整 `progressStepper`：

| 字段 | 类型 | 说明 |
|---|---|---|
| `progressStepper` | Array\<Node\> | 完整 6 主节点（嵌套） |

**Node 结构**：`step`(Integer) / `code`(String) / `name`(String) / `status`(String) / `isCurrent`(Boolean) / `subFlows`(Array\<SubFlow\>，仅资源准备非空)
**SubFlow 结构**：`code`(String) / `name`(String) / `status`(String) / `label`(String)

---

## 四、枚举 / 数据字典

### 主步 `code`（6 步）

| code | name | 完成判定 |
|---|---|---|
| `PROFILE` | 补全信息 | 已支付 |
| `RESOURCE` | 资源准备 | 配房完成（降级，见业务边界） |
| `CONFIRM` | 确认 | 订单已确认 |
| `DEPART` | 出行 | 已出行 |
| `REVIEW` | 核单 | 已核单 |
| `SETTLE` | 结算 | 已结算 |

### 子流程 `code`（资源准备下，4 条）

| code | name |
|---|---|
| `HOTEL` | 配房 |
| `VEHICLE` | 配车 |
| `GUIDE` | 领队 |
| `PHOTOGRAPHER` | 摄影 |

### `status`（主步 + 子流程通用）

| status | 含义 |
|---|---|
| `DONE` | 已完成 |
| `PROCESSING` | 处理中 |
| `WAITING` | 待开始 |

### `flowStep` 序号

`0`=待支付（步骤条未开始）｜`1-6`=对应主步｜`null`=已取消（前端不画进度条）

---

## 五、示例

### 列表（定制中、配房完成、配车进行中）

```jsonc
{
  "orderStatus": "CUSTOMIZING", "orderStatusName": "定制中",
  "flowStep": 2, "flowStepTotal": 6,
  "flowStepCode": "RESOURCE", "flowDisplayText": "资源准备", "flowStepStatus": "PROCESSING",
  "currentSubFlows": [
    {"code":"HOTEL","name":"配房","status":"DONE","label":"已完成"},
    {"code":"VEHICLE","name":"配车","status":"PROCESSING","label":"处理中"},
    {"code":"GUIDE","name":"领队","status":"WAITING","label":"待开始"},
    {"code":"PHOTOGRAPHER","name":"摄影","status":"WAITING","label":"待开始"}
  ]
}
```

### 详情 progressStepper（同一订单）

```jsonc
"progressStepper": [
  {"step":1,"code":"PROFILE","name":"补全信息","status":"DONE","isCurrent":false,"subFlows":null},
  {"step":2,"code":"RESOURCE","name":"资源准备","status":"PROCESSING","isCurrent":true,"subFlows":[
    {"code":"HOTEL","name":"配房","status":"DONE","label":"已完成"},
    {"code":"VEHICLE","name":"配车","status":"PROCESSING","label":"处理中"},
    {"code":"GUIDE","name":"领队","status":"WAITING","label":"待开始"},
    {"code":"PHOTOGRAPHER","name":"摄影","status":"WAITING","label":"待开始"}
  ]},
  {"step":3,"code":"CONFIRM","name":"确认","status":"WAITING","isCurrent":false,"subFlows":null},
  {"step":4,"code":"DEPART","name":"出行","status":"WAITING","isCurrent":false,"subFlows":null},
  {"step":5,"code":"REVIEW","name":"核单","status":"WAITING","isCurrent":false,"subFlows":null},
  {"step":6,"code":"SETTLE","name":"结算","status":"WAITING","isCurrent":false,"subFlows":null}
]
```

### 已取消订单

```jsonc
{ "flowStep": null, "flowStepCode": null, "flowDisplayText": "已取消",
  "flowStepStatus": null, "currentSubFlows": null }
// 详情 progressStepper 返回空数组 []
```

---

## 六、业务边界 / 前端注意

1. **当前步两个口子都能拿**：列表用 `flowStep`；详情用 `isCurrent==true` 的节点（和 `flowStep` 指向同一步）。
2. **⚠️ 降级现状**：资源准备步现**只判配房**——配车/领队/摄影的子状态回写链路尚未接通，所以 `VEHICLE` 子流程恒 `PROCESSING`、`GUIDE`/`PHOTOGRAPHER` 恒 `WAITING`，暂不会变 `DONE`。资源准备只要配房 `DONE` 即整步完成。回写接通后会纳入 4 线全 DONE。
3. **⚠️ 进度展示请用 `flowStep`/`flowDisplayText`，不要用 `flowStatusName`**——`flowStatus` 在"定制中"阶段恒为 `AWAITING_PROFILE`（待补全信息）不流转，用它展示进度会一直显示"待补全信息"，不准。
4. `currentSubFlows`/`subFlows` 只在资源准备步有值，其余步为 `null`，前端渲染需判空。

---

## 七、关联

- **Issue**: [#3365](https://git.1814.love:8443/wx/HL/issues/3365)、[#3368](https://git.1814.love:8443/wx/HL/issues/3368)
- **PR**: [#3366](https://git.1814.love:8443/wx/HL/pulls/3366)（派生 6 步 + 修 reviewStatus bug）、[#3369](https://git.1814.love:8443/wx/HL/pulls/3369)（嵌套 progressStepper）
- **设计文档**: ORDER-STATE-MACHINE V1.1 §2.2、API-SPEC v5.56