# 出参字段 flowDisplayText 重命名为 flowStepName — 修改接口 — 管理后台

> **变更类型**：修改接口（出参字段改名，⚠️ 破坏性变更）
> **端类型**：管理后台
> **生效日期**：2026-06-18
> **影响接口数**：3 个（创建订单 / 订单列表 / 订单详情）

---

## 一、接口背景

订单流程进度条的「当前步中文名」字段原名 `flowDisplayText`，现统一重命名为 `flowStepName`（#3967）。

字段语义、取值、派生逻辑**完全不变**，仅字段名变。  
前端需将所有对 `flowDisplayText` 的引用替换为 `flowStepName`，旧字段名已从响应中删除。

---

## 二、变更清单

| 序号 | 端点 | 变更类型 | 影响字段 |
|---|---|---|---|
| 1 | `POST /v3/admin/order` | ⚠️ 出参字段改名 | `flowDisplayText` → `flowStepName` |
| 2 | `GET /v3/admin/order/list` | ⚠️ 出参字段改名 | `flowDisplayText` → `flowStepName` |
| 3 | `GET /v3/admin/order/{id}` | ⚠️ 出参字段改名 | `flowDisplayText` → `flowStepName` |

---

## 三、接口详情

### 3.1 创建订单

| 项目 | 说明 |
|---|---|
| 方法 | `POST` |
| 路径 | `/v3/admin/order` |
| 认证 | 需要 JWT Token（管理后台登录态） |
| 幂等性 | 否（每次调用创建新订单） |
| 限流 | 无特殊限流 |

### 3.2 订单列表

| 项目 | 说明 |
|---|---|
| 方法 | `GET` |
| 路径 | `/v3/admin/order/list` |
| 认证 | 需要 JWT Token（管理后台登录态） |
| 幂等性 | 是（纯查询） |
| 限流 | 无特殊限流 |

### 3.3 订单详情

| 项目 | 说明 |
|---|---|
| 方法 | `GET` |
| 路径 | `/v3/admin/order/{id}` |
| 认证 | 需要 JWT Token（管理后台登录态） |
| 幂等性 | 是（纯查询） |
| 限流 | 无特殊限流 |

---

## 四、接口入参

三个接口的入参均无变化，略。

---

## 五、出参字段（仅列出受影响字段及其上下文）

以下为含 `flowStepName` 的完整流程进度字段组，三个接口均包含此字段组（OrderCreateRespVO / OrderListItemRespVO / OrderMainVO）：

| 字段名 | 类型 | 说明 |
|---|---|---|
| `flowStep` | Integer | 当前步编号，1-6，CANCELLED 时为 0 |
| `flowStepTotal` | Integer | 总步数，固定为 6 |
| `flowStepCode` | String | 当前步代码（如 `COMPLETE_INFO` / `RESOURCE_PREPARING`） |
| `flowStepName` | String | **（原 `flowDisplayText`，已改名）** 当前步中文名，见下表取值 |
| `flowStatus` | String | 细状态枚举值（如 `AWAITING_PAY`），未改名 |
| `flowStatusName` | String | 细状态中文名（如「待支付」），未改名 |

`flowStepName` 取值对照：

| flowStep | flowStepName 值 | 说明 |
|---|---|---|
| 1 | `补全信息` 或 `待补全信息` | 待支付时显示「待补全信息」，其余第 1 步显示「补全信息」 |
| 2 | `资源准备` | 第 2 步 |
| 3 | `确认` | 第 3 步 |
| 4 | `出行` | 第 4 步 |
| 5 | `核单` | 第 5 步 |
| 6 | `结算` | 第 6 步 |
| 0 | `已取消` | CANCELLED 状态 |

---

## 六、枚举 / 数据字典

无枚举变化。`flowStepCode` 枚举值未改变，参见已有 `flowStep` 字段说明。

---

## 七、错误码

本次改动无新增错误码。

---

## 八、示例

### 8.1 典型成功 — 订单详情（出行中第 4 步）

请求：
```
GET /v3/admin/order/1234567890
Authorization: Bearer <token>
```

响应（仅展示流程进度字段）：
```json
{
  "code": 200,
  "data": {
    "main": {
      "flowStep": 4,
      "flowStepTotal": 6,
      "flowStepCode": "ON_TRIP",
      "flowStepName": "出行",
      "flowStatus": "ON_TRIP",
      "flowStatusName": "出行中"
    }
  }
}
```

### 8.2 边界情况 — 待支付订单（flowStep=1，flowStepName 为「待补全信息」）

响应（仅展示流程进度字段）：
```json
{
  "code": 200,
  "data": {
    "main": {
      "flowStep": 1,
      "flowStepTotal": 6,
      "flowStepCode": "COMPLETE_INFO",
      "flowStepName": "待补全信息",
      "flowStatus": "AWAITING_PAY",
      "flowStatusName": "待支付"
    }
  }
}
```

### 8.3 业务失败 — 使用已删除的旧字段名

旧字段 `flowDisplayText` 已从响应中移除，前端若仍读取该字段将得到 `undefined`，**不会返回错误码**，但进度条将无法显示文案。

---

## 九、业务边界

- **适用**：所有订单状态均含 `flowStepName` 字段
- **不适用**：无例外
- **特殊边界**：`flowStepName` 与 `flowStatusName` 是两个不同字段
  - `flowStepName`：线性 6 步进度条「当前步」的中文名（粗粒度，本次改名的字段）
  - `flowStatusName`：细状态 `flowStatus` 的中文名（细粒度，**本次未改名，保持 `flowStatusName`**）
  - 两者不要混淆

---

## 十、修改前后对比

### 字段级对比

| VO | 旧字段名 | 新字段名 | 类型 | 语义变化 |
|---|---|---|---|---|
| `OrderCreateRespVO`（创单响应） | `flowDisplayText` | `flowStepName` | String | 无变化 |
| `OrderListItemRespVO`（列表项） | `flowDisplayText` | `flowStepName` | String | 无变化 |
| `OrderMainVO`（详情主信息） | `flowDisplayText` | `flowStepName` | String | 无变化 |

### 行为级对比

| 项目 | 变更前 | 变更后 |
|---|---|---|
| 当前步中文名字段 | `flowDisplayText` | `flowStepName` |
| 字段取值 | 与新字段完全相同 | 与旧字段完全相同 |
| `flowDisplayText` 是否存在 | 存在 | **已删除，响应中不再返回** |

---

## 十一、影响评估 / 回滚

### 破坏兼容性

是。旧字段名 `flowDisplayText` 已从响应中删除，前端若不更新引用，进度条文案将变空白。

### 前端需同步上线

**是**。前端必须在同期将所有 `flowDisplayText` 引用改为 `flowStepName`，否则进度步骤名称无法显示。

需要全局搜索替换（3 个接口的响应消费处）：
- 创建订单响应处理
- 订单列表渲染（步骤名称列/角标）
- 订单详情进度条渲染

### 回滚方案

如需回滚，后端 revert PR #3969，字段名恢复为 `flowDisplayText`，前端同步 revert。

---

## 十二、注意事项

1. **`flowStatusName` 未改名**：与 `flowStatus`（细状态）配套的 `flowStatusName` 字段名称不变，不要误替换。
2. **全局搜索替换**：前端需搜索代码库中所有 `flowDisplayText` 引用，三个接口的响应消费处均需替换。
3. **字段取值完全不变**：只是字段名变了，取值逻辑、枚举对照均不变，不需要改显示逻辑。

---

## 十三、关联 / 联系人

| 项目 | 链接 |
|---|---|
| Issue | https://git.1814.love:8443/wx/HL/issues/3967 |
| PR | https://git.1814.love:8443/wx/HL/pulls/3969 |
| 后端负责人 | 腰苏图（yaosutu） |