hl-api-changelog/changelogs-v2/2026-06/17_3923_订单待支付流程状态文案返空-修改接口-管理后台.md

待支付订单流程状态文案返空（与步骤条对齐）— 修改接口 — 管理后台

变更类型：🔧 接口行为变更（出参字段值规则调整） 端类型：管理后台 日期：2026-06-17 服务：hl-order-service-v3 PR：wx/HL#3926

---

1. 接口背景

功能页面：管理后台「订单列表」页 + 「订单详情」页。

用在哪：

• 订单列表：每一行订单卡片上显示「业务流程状态」的文字标签（如"资源准备""待出行"等）。
• 订单详情：详情 main 区域顶部的「当前步文案」（与步骤条联动显示，前端通常拼为"2/6 · 资源准备"格式）。

修复了什么问题：待支付订单（orderStatus=PENDING_PAY）的流程状态文案之前返回"待支付"，但详情步骤条（progressStepper）在待支付时 flowStep=0、6 个节点全为 WAITING（步骤条未点亮）。两者语义冲突——流程尚未开始，不应在流程状态位置显示文案。

修复后：待支付时 flowStatusName、flowDisplayText 均返 null，与步骤条未点亮保持一致。"待支付"由 orderStatus/orderStatusName 字段表达，语义不丢。

---

2. 变更清单

接口	字段	变更前	变更后	影响范围
GET /v3/admin/order（列表）	flowStatusName	"待支付"（当 PENDING_PAY 时）	null	订单列表行流程状态标签
GET /v3/admin/order（列表）	flowDisplayText	"待支付"（当 PENDING_PAY 时）	null	订单列表行当前步文案
GET /v3/admin/order/{id}（详情 main）	flowStatusName	"待支付"（当 PENDING_PAY 时）	null	详情页流程状态名
GET /v3/admin/order/{id}（详情 main）	flowDisplayText	"待支付"（当 PENDING_PAY 时）	null	详情页当前步文案

其他字段不变：flowStep 仍为 0，flowStatus 仍为 "AWAITING_PAY"，progressStepper 仍为 6 节点全 WAITING，orderStatusName 仍为 "待支付"。

---

3. 接口详情

3.1 订单列表

• 方法 + 路径：GET /v3/admin/order（别名 GET /v3/admin/order/list）
• 认证：需要 JWT（管理后台登录 token，Gateway 注入 X-Admin-Id）
• 幂等性：查询接口，天然幂等
• 限流：无独立限流规则

3.2 订单详情

• 方法 + 路径：GET /v3/admin/order/{id}
• 认证：需要 JWT（同上）
• 幂等性：查询接口，天然幂等
• 限流：无独立限流规则

---

4. 接口入参

4.1 订单列表 Query 参数（与本次变更无关，无入参改动）

参数	类型	必填	说明
orderStatus	String	否	粗状态过滤
keyword	String	否	关键字模糊搜索
departureDateFrom	LocalDate	否	出发日期起始
departureDateTo	LocalDate	否	出发日期结束
createSource	String	否	订单来源
consultantName	String	否	定制师姓名
page	Integer	否	页码，默认 1
pageSize	Integer	否	每页条数，默认 10

4.2 订单详情路径参数

参数	类型	必填	说明
id	Long	是	订单 ID（雪花 ID 字符串）

---

5. 出参字段（受本次影响的关键字段）

5.1 订单列表 OrderListItemRespVO（变更字段）

字段	类型	说明	本次变化
orderStatus	String	粗状态枚举值，如 PENDING_PAY	不变
orderStatusName	String	粗状态中文名，如 "待支付"	不变，仍返"待支付"
flowStatus	String	细状态枚举值，如 AWAITING_PAY	不变
flowStatusName	String	细状态中文名	⚠️ 变更：PENDING_PAY 时从"待支付"改为 null
flowStep	Integer	线性 6 步当前步序号（0=待支付未开始）	不变，仍为 0
flowStepTotal	Integer	总步数，固定 6	不变
flowDisplayText	String	当前步中文名	⚠️ 变更：PENDING_PAY 时从"待支付"改为 null

5.2 订单详情 OrderMainVO（变更字段）

字段	类型	说明	本次变化
orderStatus	String	粗状态枚举值	不变
orderStatusName	String	粗状态中文名	不变，仍返"待支付"
flowStatusName	String	细状态中文名	⚠️ 变更：PENDING_PAY 时从"待支付"改为 null
flowStep	Integer	当前步序号	不变，仍为 0
flowDisplayText	String	步骤展示文案	⚠️ 变更：PENDING_PAY 时从"待支付"改为 null
progressStepper	List	6 节点步骤条	不变，仍为 6 节点全 WAITING

---

6. 枚举 / 数据字典

订单粗状态 orderStatus

值	中文名
PENDING_PAY	待支付
CUSTOMIZING	定制中
PENDING_DEPARTURE	待出行
TRAVELLING	出行中
COMPLETED	已完成
CANCELLED	已取消

订单细状态 flowStatus（PENDING_PAY 对应值）

值	中文名（本次改动前）	中文名（本次改动后）
AWAITING_PAY	待支付	null（不算流程状态）

---

7. 错误码

本次为出参字段值规则调整，无新增错误码。通用错误码：

code	含义
200	成功
401	未登录 / token 过期
404	订单不存在（详情接口）

---

8. 示例

8.1 典型成功——待支付订单列表项

GET /v3/admin/order?orderStatus=PENDING_PAY&page=1&pageSize=1

{
  "code": 200,
  "data": {
    "total": 33,
    "list": [
      {
        "id": "1234567890001",
        "orderNo": "HL20260617143025001",
        "orderStatus": "PENDING_PAY",
        "orderStatusName": "待支付",
        "flowStatus": "AWAITING_PAY",
        "flowStatusName": null,
        "flowStep": 0,
        "flowStepTotal": 6,
        "flowDisplayText": null,
        "currentSubFlows": null,
        "productName": "长白山天池3日深度游",
        "customerName": "张三",
        "departureDate": "2026-07-01"
      }
    ]
  }
}

8.2 边界——其他状态订单（flowStatusName 有值，不受影响）

GET /v3/admin/order?orderStatus=CUSTOMIZING&page=1&pageSize=1

{
  "code": 200,
  "data": {
    "list": [
      {
        "orderStatus": "CUSTOMIZING",
        "orderStatusName": "定制中",
        "flowStatus": "RESOURCE_PREPARING",
        "flowStatusName": "资源准备",
        "flowStep": 1,
        "flowDisplayText": "资源准备"
      }
    ]
  }
}

8.3 业务失败——订单不存在（详情接口）

GET /v3/admin/order/9999999999999

{
  "code": 404,
  "msg": "订单不存在"
}

---

9. 业务边界

适用：

• 仅影响 orderStatus=PENDING_PAY 的订单（即刚创单、尚未完成订金支付的订单）。

不适用：

• CUSTOMIZING、PENDING_DEPARTURE、TRAVELLING、COMPLETED 状态的订单，flowStatusName/flowDisplayText 仍正常有值，不受影响。
• CANCELLED 状态的订单，flowDisplayText 仍为 "已取消"，不受影响。

特殊边界：

• 前端若之前对 flowDisplayText=null 有防空处理，本次直接兼容，无需额外改动。
• 若前端之前硬判 flowDisplayText === "待支付" 来识别待支付状态，需改为读 orderStatus === "PENDING_PAY" 或 orderStatusName。

---

10. 修改前后对比

字段级对比（仅 PENDING_PAY 状态）

字段	修改前	修改后
flowStatusName（列表 + 详情）	"待支付"	null
flowDisplayText（列表 + 详情）	"待支付"	null
orderStatusName（列表 + 详情）	"待支付"	"待支付"（不变）
flowStep	0	0（不变）
progressStepper	6 节点全 WAITING	6 节点全 WAITING（不变）

行为级对比

场景	修改前	修改后
列表行「流程状态」标签	显示"待支付"（来自 flowStatusName）	为 null，前端显示为空或不展示该标签
详情当前步文案	"待支付"	null，前端步骤条未点亮，文案区域为空或不展示
"待支付"文字入口	同时出现在 orderStatusName 和 flowStatusName	仅由 orderStatusName 表达，语义唯一

---

11. 影响评估 / 回滚

破坏兼容性：⚠️ 是——flowStatusName/flowDisplayText 在 PENDING_PAY 时从字符串变为 null，前端需要做好 null 防空。

前端需同步操作：

1. 订单列表：渲染「流程状态标签」时判断 flowStatusName !== null 再显示；null 时不显示标签（或显示空）。
2. 订单详情：渲染「当前步文案」时判断 flowDisplayText !== null 再拼"X/6 · xxx"格式；null 时步骤条未点亮、文案区域留空。
3. 若有 flowDisplayText === "待支付" 的硬判逻辑，改为 orderStatus === "PENDING_PAY" 判断。

回滚方案：后端回退 PR #3926 即可恢复为旧行为（null 改回 "待支付"）。后端回滚后前端无需改动。

---

12. 注意事项

• flowStatus 字段本身仍为 "AWAITING_PAY"（原始枚举值保留），只是 flowStatusName（中文名映射）返 null。
• 步骤条 progressStepper 6 节点全 WAITING 行为不变，本次只影响文案字段。
• 已取消订单（CANCELLED）的 flowDisplayText 仍为 "已取消"，本次不涉及。

---

13. 关联 / 联系人

• Issue：wx/HL#3923
• PR：wx/HL#3926
• Commit：6f0648a28a
• 后端负责人：腰苏图