884f52e2e1
PR #3273 (Issue #3272): 资源退费说明 CRUD 模块 - hl-resource-service 新建表 resource_refund_note + 3 admin 接口 - 给运营在景区/活动详情下维护退费说明 - 后续 PR 接入产品快照 + PDF + 核单 Step 5 PR #3284 (Issue #3283): orderStatus/flowStatus 补 label 中文映射 - 订单列表/详情/创单响应新增 orderStatusName + flowStatusName - 非破坏性,前端可选改造删掉自己的映射表 PR #3286 (Issue #3285): 订单接口加 8 步步骤条字段 + 修 2 个文案 - 新增 flowStep/flowStepTotal/flowDisplayText (16→8 步映射 + 中文文案) - 修订 2 个枚举 label: 待提交房型→待提交配房需求, 待提交用车→待配车需求 - 前端请确认有无按老文案做字符串硬比较 3 PR 已全部 squash 合并到 dev-v3, 等部署后生效。
150 行
4.8 KiB
Markdown
150 行
4.8 KiB
Markdown
# 二期 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，建议一起看）
|