wx/hl-api-changelog

派生 0

yaosutu 05fa996c27 新增 changelog：待支付订单流程状态归入补全信息步（管理后台，PR #3961，Issue #3960）

2026-06-18 10:58:37 +08:00

11 KiB

原始文件 Blame 文件历史

待支付订单流程状态归入「补全信息」步骤 — 修改接口 — 管理后台

变更类型：修改接口（出参字段值语义变化） 端类型：管理后台 生效日期：2026-06-18 影响接口数：3 个（创建订单 / 订单列表 / 订单详情）

一、接口背景

撤销 PR #3923「待支付不算流程状态」的处理。

原先（#3923 之后）：待支付订单的流程进度栏显示 0/6、文案为空、详情步骤条全灰。产品口径调整（#3960）：待支付订单属于流程第 1 步「补全信息」，因为客人还没补出行人信息，步骤条需高亮第一步，文案显示「待补全信息」。

二、变更清单

序号	端点	变更类型	影响字段
1	`POST /v3/admin/order`	出参字段值变化	`flowStep` / `flowDisplayText` / `flowStatusName`
2	`GET /v3/admin/order/list`	出参字段值变化	`flowStep` / `flowDisplayText` / `flowStatusName` / `flowStepCode`
3	`GET /v3/admin/order/{id}`	出参字段值变化	`flowStep` / `flowDisplayText` / `flowStatusName` / `flowStepCode` / `main.flowStepStatus` / `main.progressStepper[0]`

只有 orderStatus = "PENDING_PAY"（待支付）的订单受影响，其他状态完全不变。

三、接口详情

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（管理后台登录态）
幂等性	是（纯查询）
限流	无特殊限流

四、接口入参

4.1 创建订单（POST /v3/admin/order）

本次改动不涉及入参变化，入参契约与原有定义一致。

4.2 订单列表（GET /v3/admin/order/list）

本次改动不涉及入参变化，查询参数契约与原有定义一致。

4.3 订单详情（GET /v3/admin/order/{id}）

参数名	位置	类型	必填	说明
`id`	Path	Long（字符串传输）	是	订单 ID

五、出参字段

5.1 创建订单返回（OrderCreateRespVO）

下表仅列出本次值语义变化的流程字段；其余字段不变。

字段名	类型	说明	变化
`flowStep`	Integer	当前步号，取值 1-6，总共 6 步；不在流程中时为 `null`	待支付时由 `0` 改为 `1`
`flowStepTotal`	Integer	总步数，固定 `6`	不变
`flowDisplayText`	String	步骤展示文案（纯中文，直接用于前端展示）	待支付时由 `null` 改为 `"待补全信息"`
`flowStatusName`	String	细状态中文名	待支付时由 `null` 改为 `"待补全信息"`
`flowStatus`	String	流程状态英文枚举原始值	不变，仍为 `"AWAITING_PAY"`

5.2 订单列表项返回（PageResult<OrderListItemRespVO>）

下表仅列出本次值语义变化的流程字段；其余字段不变。

字段名	类型	说明	变化
`flowStep`	Integer	当前步号，1-6	待支付时由 `0` 改为 `1`
`flowStepTotal`	Integer	总步数，固定 `6`	不变
`flowDisplayText`	String	步骤展示文案（纯中文）	待支付时由 `null` 改为 `"待补全信息"`
`flowStatusName`	String	细状态中文名	待支付时由 `null` 改为 `"待补全信息"`
`flowStepCode`	String	当前步英文编码	待支付时由 `null` 改为 `"PROFILE"`
`flowStatus`	String	流程状态英文枚举原始值	不变，仍为 `"AWAITING_PAY"`
`orderStatus`	String	订单状态，独立维度	不变，仍为 `"PENDING_PAY"`
`orderStatusName`	String	订单状态中文名	不变，仍为 `"待支付"`

5.3 订单详情返回（OrderDetailRespVO — main 节点 OrderMainVO）

下表仅列出本次值语义变化的流程字段；其余字段不变。

字段名	类型	说明	变化
`flowStep`	Integer	当前步号，1-6	待支付时由 `0` 改为 `1`
`flowStepTotal`	Integer	总步数，固定 `6`	不变
`flowDisplayText`	String	步骤展示文案（纯中文）	待支付时由 `null` 改为 `"待补全信息"`
`flowStatusName`	String	细状态中文名	待支付时由 `null` 改为 `"待补全信息"`
`flowStepCode`	String	当前步英文编码	待支付时由 `null` 改为 `"PROFILE"`
`flowStepStatus`	String	当前步状态枚举	待支付时由 `null` 改为 `"PROCESSING"`
`flowStatus`	String	流程状态英文枚举原始值	不变，仍为 `"AWAITING_PAY"`
`main.progressStepper[0].status`	String	步骤条「补全信息」节点状态	待支付时由 `"WAITING"` 改为 `"PROCESSING"`
`main.progressStepper[0].isCurrent`	Boolean	是否为当前高亮步	待支付时由 `false` 改为 `true`
`orderStatus`	String	订单状态，独立维度	不变，仍为 `"PENDING_PAY"`
`orderStatusName`	String	订单状态中文名	不变，仍为 `"待支付"`

六、枚举 / 数据字典

6.1 流程 6 步固定编码（flowStepCode）

步号（flowStep）	英文编码（flowStepCode）	中文文案（flowDisplayText）
1	`PROFILE`	待补全信息
2	`RESOURCE`	资源准备
3	`CONFIRM`	确认
4	`DEPART`	出行
5	`REVIEW`	核单
6	`SETTLE`	结算
-	-	`null`（已取消等不在流程中的状态）

flowStepTotal 固定为 6，不随状态变化。

6.2 步骤节点状态（progressStepper[N].status）

值	说明
`WAITING`	未开始（灰色）
`PROCESSING`	进行中 / 当前高亮步
`DONE`	已完成

6.3 当前步状态（flowStepStatus）

值	说明
`PROCESSING`	当前步进行中
`DONE`	当前步已完成
`null`	不在流程中（如已取消）

七、错误码

本次改动不引入新错误码，原有错误码契约不变。

八、示例

8.1 典型成功 — 待支付订单列表项（orderStatus = PENDING_PAY）

请求：

GET /v3/admin/order/list?orderStatus=PENDING_PAY&pageNo=1&pageSize=10

响应（仅展示流程相关字段）：

{
  "code": 200,
  "data": {
    "total": 1,
    "list": [
      {
        "id": "1234567890123456789",
        "orderStatus": "PENDING_PAY",
        "orderStatusName": "待支付",
        "flowStatus": "AWAITING_PAY",
        "flowStatusName": "待补全信息",
        "flowStep": 1,
        "flowStepTotal": 6,
        "flowDisplayText": "待补全信息",
        "flowStepCode": "PROFILE"
      }
    ]
  }
}

前端展示建议：步骤进度条可渲染为 1/6 · 待补全信息。

8.2 边界情况 — 已取消订单（不受本次影响）

响应（流程相关字段）：

{
  "orderStatus": "CANCELLED",
  "orderStatusName": "已取消",
  "flowStatus": null,
  "flowStatusName": null,
  "flowStep": null,
  "flowStepTotal": 6,
  "flowDisplayText": "已取消",
  "flowStepCode": null
}

已取消订单 flowStep 为 null，步骤条无需高亮任何步骤。

8.3 对比参照 — 付款后定制中订单（不受本次影响）

响应（流程相关字段）：

{
  "orderStatus": "PAID",
  "orderStatusName": "已支付",
  "flowStatus": "CUSTOMIZING",
  "flowStatusName": "资源准备",
  "flowStep": 2,
  "flowStepTotal": 6,
  "flowDisplayText": "资源准备",
  "flowStepCode": "RESOURCE"
}

九、业务边界

适用：

orderStatus = "PENDING_PAY"（待支付）的订单，流程步号归入第 1 步「补全信息」。

不适用：

其他任何 orderStatus 值的订单，流程字段完全不受本次变更影响。

特殊边界：

orderStatus 和 flowStatus 是两个独立维度。本次只改变了 flowStatus = AWAITING_PAY 对应的步号与中文名，不影响 orderStatus = PENDING_PAY 本身的含义与文案。
前端如需同时展示「订单状态」和「流程步骤」两个维度，应分别取 orderStatusName（待支付）和 flowDisplayText（待补全信息），两者语义不同，不可混用。

十、修改前后对比

10.1 字段级对比（仅 orderStatus = PENDING_PAY 时）

字段	改前（#3923）	改后（#3960）	出现于
`flowStep`	`0`	`1`	列表 / 详情 / 创单
`flowDisplayText`	`null`	`"待补全信息"`	列表 / 详情 / 创单
`flowStatusName`	`null`	`"待补全信息"`	列表 / 详情 / 创单
`flowStepCode`	`null`	`"PROFILE"`	列表 / 详情
`main.flowStepStatus`	`null`	`"PROCESSING"`	仅详情
`main.progressStepper[0].status`	`"WAITING"`	`"PROCESSING"`	仅详情
`main.progressStepper[0].isCurrent`	`false`	`true`	仅详情

10.2 行为级对比

场景	改前	改后
订单列表流程进度栏（待支付订单）	显示 `0/6`，文案空白	显示 `1/6`，文案「待补全信息」
订单详情步骤条第一步（补全信息）（待支付）	灰色（WAITING），不高亮	高亮（PROCESSING），标记为当前步
其他状态订单	不变	不变

十一、影响评估 / 回滚

是否破坏兼容：

字段名未变，类型未变，仅字段值变化（0 → 1，null → 非 null 字符串）。
如前端代码中有 if (flowStep === 0) 或 if (flowDisplayText === null) 的特判逻辑，需检查并修正。

前端同步上线要求：

本次为出参值修正，后端已上线，前端无需改动即可展示正确数据（字段名保持不变）。
若前端此前已针对 flowStep = 0 做过特殊兜底处理，建议清理相关 workaround 逻辑。

回滚方案：

若需回滚，后端回退到 #3923 版本即可，前端无需操作。

十二、注意事项

前端绑定约定：流程状态显示的文字直接绑后端返回的 flowDisplayText / flowStatusName（这俩就是中文），逻辑判断 / 步骤高亮 / 样式 / 埋点用 flowStep / flowStepCode / flowStatus（英文枚举+步号）。禁止前端拿英文枚举自己硬编码中文（如 if flowStatus === 'AWAITING_PAY' return '待补全信息'）——文案以后端为唯一来源，避免管理后台 / 小程序两端文案漂移。

十三、关联 / 联系人

项目	链接 / 信息
Issue	wx/HL#3960
PR	wx/HL#3961
commit	https://git.1814.love:8443/wx/HL/commit/db976ed80
后端负责人	腰苏图（yaosutu）

11 KiB 原始文件 Blame 文件历史 Unescape Escape

待支付订单流程状态归入「补全信息」步骤 — 修改接口 — 管理后台

一、接口背景

二、变更清单

三、接口详情

3.1 创建订单

3.2 订单列表

3.3 订单详情

四、接口入参

4.1 创建订单（POST /v3/admin/order）

4.2 订单列表（GET /v3/admin/order/list）

4.3 订单详情（GET /v3/admin/order/{id}）

五、出参字段

5.1 创建订单返回（OrderCreateRespVO）

5.2 订单列表项返回（PageResult<OrderListItemRespVO>）

5.3 订单详情返回（OrderDetailRespVO — main 节点 OrderMainVO）

六、枚举 / 数据字典

6.1 流程 6 步固定编码（flowStepCode）

6.2 步骤节点状态（progressStepper[N].status）

6.3 当前步状态（flowStepStatus）

七、错误码

八、示例

8.1 典型成功 — 待支付订单列表项（orderStatus = PENDING_PAY）

8.2 边界情况 — 已取消订单（不受本次影响）

8.3 对比参照 — 付款后定制中订单（不受本次影响）

九、业务边界

十、修改前后对比

10.1 字段级对比（仅 orderStatus = PENDING_PAY 时）

10.2 行为级对比

十一、影响评估 / 回滚

十二、注意事项

十三、关联 / 联系人

11 KiB

原始文件 Blame 文件历史