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

三个接口（创单/列表/详情）破坏性改名，前端需全局替换引用。

2026-06-18 12:52:14 +08:00

6.6 KiB

原始文件 永久链接 Blame 文件历史

出参字段 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>

响应（仅展示流程进度字段）：

{
  "code": 200,
  "data": {
    "main": {
      "flowStep": 4,
      "flowStepTotal": 6,
      "flowStepCode": "ON_TRIP",
      "flowStepName": "出行",
      "flowStatus": "ON_TRIP",
      "flowStatusName": "出行中"
    }
  }
}

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

响应（仅展示流程进度字段）：

{
  "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。

十二、注意事项

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

十三、关联 / 联系人

项目	链接
Issue	wx/HL#3967
PR	wx/HL#3969
后端负责人	腰苏图（yaosutu）

6.6 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape