# 二期 v3：订单 orderStatus / flowStatus 字段补 label 中文映射

> **服务**: hl-order-service-v3
> **PR**: #3284
> **Issue**: #3283
> **日期**: 2026-05-30
> **影响**: 🟢 **非破坏性**新增字段。前端从前自行映射 `AWAITING_PROFILE → "待补全信息"` 等，现在后端直接给。老字段 `orderStatus` / `flowStatus`（英文枚举）保留不动，新增 `orderStatusName` / `flowStatusName` 中文 label 同时返回。

---

## 总览（前端 mmg 必读）

订单列表 / 详情 / 创建响应里的 `orderStatus` 和 `flowStatus` 字段历史上**只返英文枚举**（`CUSTOMIZING` / `AWAITING_PROFILE` 等），前端要查表自行翻译。本期后端直接拼好中文 label 返回，前端**直接用 `xxxStatusName` 字段展示**即可。

旧字段保留，前端老逻辑零改动。

---

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

### 1. 订单列表

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

**响应** `data.records[].xxx` 新增 2 字段：

```jsonc
{
  "orderStatus": "CUSTOMIZING",
  "orderStatusName": "定制中",            // 🆕 中文名
  "flowStatus": "AWAITING_PROFILE",
  "flowStatusName": "待补全信息"          // 🆕 中文名
}
```

### 2. 订单详情

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

**响应** `data.main` 同样新增 2 字段：

```jsonc
"main": {
  "orderStatus": "TRAVELLING",
  "orderStatusName": "出行中",            // 🆕
  "flowStatus": "TRAVELLING",
  "flowStatusName": "出行中"              // 🆕
}
```

### 3. 创建订单响应

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

**响应** `data` 新增 1 字段（`orderStatusName` 早期已有，本期补 `flowStatusName`）：

```jsonc
{
  "orderStatus": "PENDING_PAY",
  "orderStatusName": "待支付",
  "flowStatus": "AWAITING_PAY",
  "flowStatusName": "待支付"               // 🆕
}
```

---

## 状态枚举完整对照表

### `orderStatus`（粗状态 6 个）

| 枚举值 | 中文名 |
|---|---|
| `PENDING_PAY` | 待支付 |
| `CUSTOMIZING` | 定制中 |
| `PENDING_DEPARTURE` | 待出行 |
| `TRAVELLING` | 出行中 |
| `COMPLETED` | 已完成 |
| `CANCELLED` | 已取消 |

### `flowStatus`（细状态 16 个）

| 枚举值 | 中文名 |
|---|---|
| `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` | 已取消 |

> ⚠️ **注意**：本 PR 后紧跟的 PR #3286 改了其中 2 个 label —— `待提交房型 → 待提交配房需求`、`待提交用车 → 待配车需求`。**实际部署后看到的是 PR #3286 的新文案**，前端如果按这俩老文案做字符串硬比较需要更新（详见 PR #3286 changelog）。

---

## 容错（前端可忽略）

- 后端拿到 null 或未知枚举（历史脏数据）会回退：返回原值而不是抛 500，前端不会看到"待x"等乱码。
- 即便后端返回原英文枚举值（如未知 `XXXXX`），前端展示也能落 fallback。

---

## 业务边界

- 老字段 `orderStatus` / `flowStatus` 保留英文枚举（**契约不变**）
- 仅新增 `orderStatusName` / `flowStatusName` 中文
- 前端**老逻辑零改动**也能跑（旧字段还在）
- 改成展示 `xxxStatusName` 后，前端不需要自己维护英文 → 中文映射表

---

## 影响评估

- **后端**：仅 hl-order-service-v3 改了 5 个文件（3 VO + Converter + OrderService），无 DB 改动，重启服务后生效。
- **前端**：可选改造——把硬编码映射表删掉，直接用 `xxxStatusName`。改不改都不影响功能。
- **mp 端**：本 PR 暂未改 `OrderLookupMpService`（仍是 mock 假数据），真业务化时一起补。

---

## 注意事项

1. 如果你的前端代码有硬编码的英文→中文映射表（如 `{ AWAITING_PROFILE: "待补全信息" }`），建议删掉，改用 `flowStatusName` 字段，避免后端枚举改了文案前端跟不上。
2. 文案的"权威源"是后端枚举（`OrderStatus` / `OrderFlowStatus`），运营如果要求改文案直接改后端，前端无感跟随。

---

## 关联

- **Issue**: [#3283](https://git.1814.love:8443/wx/HL/issues/3283)
- **PR**: [#3284](https://git.1814.love:8443/wx/HL/pulls/3284) - fix(order-v3): orderStatus/flowStatus 补 label 中文映射
- **Commit**: [cb85f0f76](https://git.1814.love:8443/wx/HL/commit/cb85f0f76)
- **接续 PR**: [#3286](https://git.1814.love:8443/wx/HL/pulls/3286) - feat(order-v3): 8 步步骤条字段 + 修 2 文案（紧接本 PR，建议一起看）