# 二期 v3：订单列表 状态 / 进度字段 —— 前端选用说明

> **服务**: hl-order-service-v3
> **端**: 管理后台
> **接口**: `GET /v3/admin/order`（订单列表）
> **类型**: 📘 字段使用说明（**非接口改动**，字段早已在出参里，本文只讲"前端该用哪个"）
> **日期**: 2026-06-02
> **关联**: Issue #3283（状态中文名）+ Issue #3285（8 步步骤条）

---

## 一句话结论

订单列表里和"状态 / 进度"有关的字段，前端**只用下面 5 个**即可：

```
orderStatus / orderStatusName   —— 订单大状态（6 态）
flowStatus  / flowStatusName    —— 流程细状态（16 态）
flowStep / flowStepTotal / flowDisplayText  —— 8 步进度步骤条
```

> `progress`（"3/10"）和 `flowItems` 这两个字段**列表不用，前端忽略**（出参里可能还在，是历史字段，不要再消费）。

---

## 字段选用对照表（看这张就够）

| 你要展示什么 | 用哪个字段 | 说明 |
|---|---|---|
| 订单**大状态**（列表标签 / Tab 筛选） | 展示用 `orderStatusName`，逻辑判断用 `orderStatus` | 6 个粗状态 |
| 订单**流程细状态**（当前所处环节文字） | 展示用 `flowStatusName`，逻辑判断用 `flowStatus` | 16 个细状态 |
| **进度步骤条**（第几步 / 共几步） | `flowStep` + `flowStepTotal` | 如 `5` / `8` → "5/8" |
| **步骤条当前步文案**（即"流程进度名称"） | `flowDisplayText` | 如 "待出行"；前端自拼 "5/8 · 待出行" |
| ~~节点完成度 "3/10"~~ | ~~`progress`~~ | ❌ 列表不用，忽略 |
| ~~并行未完成项列表~~ | ~~`flowItems`~~ | ❌ 列表不用，忽略 |

---

## 字段详解

### 1. 订单大状态 `orderStatus` / `orderStatusName`（6 态）

| `orderStatus` | `orderStatusName` |
|---|---|
| `PENDING_PAY` | 待支付 |
| `CUSTOMIZING` | 定制中 |
| `PENDING_DEPARTURE` | 待出行 |
| `TRAVELLING` | 出行中 |
| `COMPLETED` | 已完成 |
| `CANCELLED` | 已取消 |

### 2. 流程细状态 `flowStatus` / `flowStatusName`（16 态）

| `flowStatus` | `flowStatusName` |
|---|---|
| `AWAITING_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` | 已结算 |
| `COMPLETED` | 已完成 |
| `CANCELLED` | 已取消 |

### 3. 8 步进度步骤条 `flowStep` / `flowStepTotal` / `flowDisplayText`

- `flowStepTotal`：固定 **8**。
- `flowStep`：当前第几步，由 `(orderStatus, flowStatus)` 后端算好：

  | `flowStep` 值 | 含义 | 对应 `flowStatus` |
  |---|---|---|
  | `0` | 待支付（步骤条尚未开始） | `AWAITING_PAY` |
  | `1` | 补全信息 | `AWAITING_PROFILE` |
  | `2` | 配房 | `AWAITING_HOTEL_SUBMIT` / `AWAITING_HOTEL_CLAIM` / `HOTEL_IN_PROGRESS` / `HOTEL_NEED_ADJUST` |
  | `3` | 配车 | `AWAITING_VEHICLE_SUBMIT` / `VEHICLE_IN_PROGRESS` / `VEHICLE_NEED_ADJUST` |
  | `4` | 确认 | `PENDING_CONFIRM` |
  | `5` | 待出行 | `PENDING_DEPARTURE` |
  | `6` | 出行 | `TRAVELLING` |
  | `7` | 核单 | `PENDING_REVIEW` |
  | `8` | 结算 | `REVIEWING` / `SETTLED` |
  | `null` | **终态或未知**（已完成 / 已取消 / 脏数据） | `COMPLETED` / `CANCELLED` 等 |

  > ⚠️ `flowStep` 可能为 **null**（终态/脏数据），前端步骤条渲染需对 null 兜底（如直接显示 `flowDisplayText`，不画进度条）。

- `flowDisplayText`：步骤条当前步的中文文案（即你说的"流程进度名称"）。规则：
  - 终态优先：`orderStatus`=已取消 → "已取消"；已完成 → "已完成"
  - 非终态：等于当前 `flowStatus` 的中文名
  - 只给中文，**不带** "X/8 · " 前缀，需要的话前端自拼。

---

## `flowDisplayText` 与 `flowStatusName` 的区别（容易混）

- **非终态**：两者**完全相同**（都是 `flowStatus` 的中文名）。
- **终态**：
  - `flowDisplayText` 走**粗状态**：固定 "已取消" / "已完成"。
  - `flowStatusName` 走**细状态**：是 `flowStatus` 字段本身的 label。
- **建议**：步骤条文案用 `flowDisplayText`（终态展示更干净）；纯流程状态文字用 `flowStatusName`。

---

## 响应示例（列表单条，只列状态/进度相关字段）

```jsonc
{
  "orderStatus": "PENDING_DEPARTURE",
  "orderStatusName": "待出行",
  "flowStatus": "PENDING_DEPARTURE",
  "flowStatusName": "待出行",
  "flowStep": 5,
  "flowStepTotal": 8,
  "flowDisplayText": "待出行"
  // progress / flowItems 即使返回也请忽略
}
```

终态示例（已取消）：

```jsonc
{
  "orderStatus": "CANCELLED",
  "orderStatusName": "已取消",
  "flowStatus": "CANCELLED",
  "flowStatusName": "已取消",
  "flowStep": null,            // 终态无步骤，前端兜底
  "flowStepTotal": 8,
  "flowDisplayText": "已取消"
}
```

---

## 业务边界 / 注意事项

1. 文案**权威源是后端枚举**（`OrderStatus` / `OrderFlowStatus`），运营改文案后端改枚举即可，前端不要硬编码英文→中文映射。
2. `flowStep` 可能为 `null`（终态/脏数据），步骤条渲染必须兜底。
3. `progress`（"3/10"）/ `flowItems` 是历史字段，**列表场景不要消费**；后续可能下线，提前别依赖。
4. 本文不改任何接口契约，纯字段选用约定，**后端无需重启**。

---

## 关联

- **状态中文名**: Issue [#3283](https://git.1814.love:8443/wx/HL/issues/3283) / PR [#3284](https://git.1814.love:8443/wx/HL/pulls/3284)
- **8 步步骤条**: Issue [#3285](https://git.1814.love:8443/wx/HL/issues/3285) / PR [#3286](https://git.1814.love:8443/wx/HL/pulls/3286)
- **接口**: `GET /v3/admin/order`