hl-api-changelog/changelogs-v2/2026-05/30_3285_订单接口加8步步骤条字段_PR3286.md

# 二期 v3：订单接口加 flowStep / flowStepTotal / flowDisplayText 步骤条字段 + 修 2 个文案

> **服务**: hl-order-service-v3
> **PR**: #3286
> **Issue**: #3285
> **日期**: 2026-05-30
> **影响**: 🟡 **非破坏性**新增字段 + **文案修订**。前端从前自己拼 `"1/8 · 待补全信息"`，现在后端直接给 `flowStep` / `flowStepTotal` / `flowDisplayText` 三字段，前端拿着就显示。同时修了 2 个枚举 label 文案。

---

## 总览（前端 mmg 必读）

接续 PR #3284（status label 中文），本期把"订单步骤条"所需数据全部下沉到后端：

```jsonc
{
  "flowStep": 1,                     // 🆕 当前步序号 0=待支付前, 1-8=进行中, null=终态/未知
  "flowStepTotal": 8,                // 🆕 总步数固定 8
  "flowDisplayText": "待补全信息"     // 🆕 中文文案,只中文不带"X/8 · ",前端按需自拼
}
```

前端从前的 `currentStep / totalSteps + 自己映射中文` 逻辑全部可删，直接用本期 3 字段。

**同时**：修了 2 个 `OrderFlowStatus` 枚举 label 文案（影响 `flowStatusName` 字段返回）：

| 枚举值 | 旧文案 | 新文案 |
|---|---|---|
| `AWAITING_HOTEL_SUBMIT` | 待提交房型 | **待提交配房需求** |
| `AWAITING_VEHICLE_SUBMIT` | 待提交用车 | **待配车需求** |

---

## 接口清单（3 个响应增字段）

### 1. 订单列表

```
GET /v3/admin/order
```

**响应** `data.records[].xxx` 在 PR #3284 基础上再加 3 字段：

```jsonc
{
  "orderStatus": "CUSTOMIZING",
  "orderStatusName": "定制中",
  "flowStatus": "AWAITING_PROFILE",
  "flowStatusName": "待补全信息",
  "flowStep": 1,                    // 🆕
  "flowStepTotal": 8,               // 🆕
  "flowDisplayText": "待补全信息"     // 🆕
}
```

### 2. 订单详情

```
GET /v3/admin/order/{id}/detail
```

**响应** `data.main` 同样加 3 字段（位置和列表相同）。

### 3. 创建订单响应

```
POST /v3/admin/order
```

**响应** 加 3 字段；创单初态固定：

```jsonc
{
  "flowStep": 0,
  "flowStepTotal": 8,
  "flowDisplayText": "待支付"
}
```

---

## 8 步映射表（16 → 8）

**优先级**：`orderStatus` 终态 > `flowStatus` 步骤映射

| 触发条件 | `flowStep` | `flowDisplayText` |
|---|---|---|
| `orderStatus = CANCELLED` | `null` | "已取消" |
| `orderStatus = COMPLETED` | `null` | "已完成" |
| `flowStatus = AWAITING_PAY` | `0` | "待支付" |
| `flowStatus = AWAITING_PROFILE` | `1` | "待补全信息" |
| `flowStatus = AWAITING_HOTEL_SUBMIT` | `2` | **"待提交配房需求"** |
| `flowStatus = AWAITING_HOTEL_CLAIM` | `2` | "待抢房" |
| `flowStatus = HOTEL_IN_PROGRESS` | `2` | "房控处理中" |
| `flowStatus = HOTEL_NEED_ADJUST` | `2` | "房控需调整" |
| `flowStatus = AWAITING_VEHICLE_SUBMIT` | `3` | **"待配车需求"** |
| `flowStatus = VEHICLE_IN_PROGRESS` | `3` | "车控处理中" |
| `flowStatus = VEHICLE_NEED_ADJUST` | `3` | "车控需调整" |
| `flowStatus = PENDING_CONFIRM` | `4` | "待确认" |
| `flowStatus = PENDING_DEPARTURE` | `5` | "待出行" |
| `flowStatus = TRAVELLING` | `6` | "出行中" |
| `flowStatus = PENDING_REVIEW` | `7` | "待核单" |
| `flowStatus = REVIEWING` | `8` | "核单中" |
| `flowStatus = SETTLED` | `8` | "已结算" |

**说明**：

- 配房 4 个并行子态（`AWAITING_HOTEL_SUBMIT` / `_CLAIM` / `HOTEL_IN_PROGRESS` / `_NEED_ADJUST`）都归到 step 2
- 配车 3 个并行子态都归到 step 3
- `REVIEWING` 和 `SETTLED` 都归到 step 8（结算后整体收尾）
- `CANCELLED` / `COMPLETED` 是终态，不在 8 步串行里，`flowStep` 返 null
- 未知 / 历史脏数据：`flowStep=null`, `flowDisplayText=` 原英文值（fallback 不抛错）

---

## 前端如何用（推荐）

### 推荐方式 1：只显示 `flowDisplayText`（最简单）

```html
<div class="status">{{ order.flowDisplayText }}</div>
<!-- 渲染结果: 待补全信息 / 出行中 / 已取消 等 -->
```

### 推荐方式 2：进度条 + 中文（拼分子分母）

```html
<div v-if="order.flowStep !== null">
  {{ order.flowStep }}/{{ order.flowStepTotal }} · {{ order.flowDisplayText }}
</div>
<div v-else>
  {{ order.flowDisplayText }}  <!-- 终态不带 X/8 -->
</div>
<!-- 渲染示例: "1/8 · 待补全信息" / "已取消" -->
```

### 推荐方式 3：步骤条 UI（按 flowStep 高亮）

如果有 8 段步骤条 UI 组件，按 `flowStep` 高亮当前段：

```jsonc
const stepNames = ["待支付", "补全信息", "配房需求", "配车需求",
                   "确认", "出行准备", "出行", "核单"];
// 用 flowStep 高亮 stepNames[flowStep - 1]
```

---

## 文案变更详情（重点关注）

| 字段 | 旧值 | 新值 |
|---|---|---|
| `flowStatusName`（PR #3284 字段）| "待提交房型" | "待提交配房需求" |
| `flowStatusName` | "待提交用车" | "待配车需求" |
| `flowDisplayText`（本 PR 字段）| - | 同上 |

**前端需要确认的事**：

1. 如果有按 **"待提交房型"** / **"待提交用车"** 老文案做字符串硬比较（如 `if (status === "待提交房型")`），需要改成新文案或改用枚举值比较。
2. 如果只是 **展示**（不做逻辑判断），无需改动——文案直接显示新值即可。

我们后端搜了一遍**未发现**前端这个老文案的硬比较，但前端代码后端看不到，**请前端 mmg 自己 grep 确认**。

---

## 容错（前端可忽略）

- `flowStatus` 是历史脏数据（枚举里没有）→ `flowStep = null`, `flowDisplayText = 原始值`
- `orderStatus = null` → `flowStep = null`, `flowDisplayText = "未知"`
- 前端按 `flowStep === null` 判断终态/未知，按 `flowDisplayText` 兜底展示，绝不会拿到空字符串。

---

## 业务边界

- 老字段 `flowStatus` / `flowStatusName` 保留（契约不变）
- 仅新增 3 字段 + 修订 2 个枚举 label 文案
- 8 步是**前端展示概念**，后端的 `OrderFlowStatus` 仍是 16 个细状态（DB 落地不变）
- 步骤条只是**展示视角**的简化，业务逻辑仍按 16 个 `flowStatus` 跑

---

## 影响评估

- **后端**：hl-order-service-v3 改了 7 个文件（枚举 + Converter + 3 VO + Service + 测试），无 DB 改动，重启服务后生效。
- **前端**：可选改造——把"1/8"拼接逻辑改用后端 3 字段。改不改都不影响功能（老逻辑还能跑）。
- **mp 端**：本 PR 暂未改 mp（mock service），真业务化时一并补。

---

## 注意事项

1. **文案修订是契约变更**：如果前端按老文案做字符串硬比较，必须改。展示用的话无影响。
2. **flowStep 可能为 null**：终态（已取消/已完成/历史脏数据）时为 null，前端按 null 处理"不显示分子"或"显示终态文案"。
3. **创单后立即调列表**：会看到 `flowStep=0` + `flowDisplayText="待支付"`，符合"还没开始走流程"语义。

---

## 关联

- **Issue**: [#3285](https://git.1814.love:8443/wx/HL/issues/3285)
- **PR**: [#3286](https://git.1814.love:8443/wx/HL/pulls/3286) - feat(order-v3): 订单接口加 8 步步骤条字段 + 修 2 个文案
- **Commit**: [fd533fdaa](https://git.1814.love:8443/wx/HL/commit/fd533fdaa)
- **前置 PR**: [#3284](https://git.1814.love:8443/wx/HL/pulls/3284) - status label 中文（建议一起看）