From 49cd72a4817857210f092e9b4e3c444487dc56af Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Thu, 18 Jun 2026 12:52:14 +0800 Subject: [PATCH] =?UTF-8?q?feat(order-v3):=20=E5=87=BA=E5=8F=82=E5=AD=97?= =?UTF-8?q?=E6=AE=B5=20flowDisplayText=20=E9=87=8D=E5=91=BD=E5=90=8D?= =?UTF-8?q?=E4=B8=BA=20flowStepName=EF=BC=88#3967/PR#3969=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 三个接口（创单/列表/详情）破坏性改名，前端需全局替换引用。 --- ...yText改名flowStepName-修改接口-管理后台.md | 227 ++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 changelogs-v2/2026-06/18_3967_flowDisplayText改名flowStepName-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/18_3967_flowDisplayText改名flowStepName-修改接口-管理后台.md b/changelogs-v2/2026-06/18_3967_flowDisplayText改名flowStepName-修改接口-管理后台.md new file mode 100644 index 0000000..8ba9ab1 --- /dev/null +++ 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 +``` + +响应（仅展示流程进度字段）： +```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） | +