feat(order-v3): 出参字段 flowDisplayText 重命名为 flowStepName（#3967/PR#3969）

三个接口（创单/列表/详情）破坏性改名，前端需全局替换引用。
2026-06-18 12:52:14 +08:00 · 2026-06-18 12:52:14 +08:00 · 49cd72a481
--- a/changelogs-v2/2026-06/18_3967_flowDisplayText改名flowStepName-修改接口-管理后台.md
+++ b/changelogs-v2/2026-06/18_3967_flowDisplayText改名flowStepName-修改接口-管理后台.md
@ -0,0 +1,227 @@
+# 出参字段 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） |
+