hl-api-changelog/changelogs-v2/2026-06/02_3283-3285_订单列表状态进度字段前端选用说明.md

二期 v3：订单列表 状态 / 进度字段 —— 前端选用说明

服务: hl-order-service-v3 端: 管理后台 接口: GET /v3/admin/order（订单列表） 类型: 📘 字段使用说明（非接口改动，字段早已在出参里，本文只讲"前端该用哪个"） 日期: 2026-06-02 关联: Issue #3283（状态中文名）+ Issue #3285（8 步步骤条）

---

一句话结论

订单列表里和"状态 / 进度"有关的字段，前端只用下面 5 个即可：

orderStatus / orderStatusName   —— 订单大状态（6 态）
flowStatus  / flowStatusName    —— 流程细状态（16 态）
flowStep / flowStepTotal / flowDisplayText  —— 8 步进度步骤条

progress（"3/10"）和 flowItems 这两个字段列表不用，前端忽略（出参里可能还在，是历史字段，不要再消费）。

---

字段选用对照表（看这张就够）

你要展示什么	用哪个字段	说明
订单大状态（列表标签 / Tab 筛选）	展示用 orderStatusName，逻辑判断用 orderStatus	6 个粗状态
订单流程细状态（当前所处环节文字）	展示用 flowStatusName，逻辑判断用 flowStatus	16 个细状态
进度步骤条（第几步 / 共几步）	flowStep + flowStepTotal	如 5 / 8 → "5/8"
步骤条当前步文案（即"流程进度名称"）	flowDisplayText	如 "待出行"；前端自拼 "5/8 · 待出行"
节点完成度 "3/10"	progress	❌ 列表不用，忽略
并行未完成项列表	flowItems	❌ 列表不用，忽略

---

字段详解

1. 订单大状态 orderStatus / orderStatusName（6 态）

orderStatus	orderStatusName
PENDING_PAY	待支付
CUSTOMIZING	定制中
PENDING_DEPARTURE	待出行
TRAVELLING	出行中
COMPLETED	已完成
CANCELLED	已取消

2. 流程细状态 flowStatus / flowStatusName（16 态）

flowStatus	flowStatusName
AWAITING_PAY	待支付
AWAITING_PROFILE	待补全信息
AWAITING_HOTEL_SUBMIT	待提交配房需求
AWAITING_HOTEL_CLAIM	待抢房
HOTEL_IN_PROGRESS	房控处理中
HOTEL_NEED_ADJUST	房控需调整
AWAITING_VEHICLE_SUBMIT	待配车需求
VEHICLE_IN_PROGRESS	车控处理中
VEHICLE_NEED_ADJUST	车控需调整
PENDING_CONFIRM	待确认
PENDING_DEPARTURE	待出行
TRAVELLING	出行中
PENDING_REVIEW	待核单
REVIEWING	核单中
SETTLED	已结算
COMPLETED	已完成
CANCELLED	已取消

3. 8 步进度步骤条 flowStep / flowStepTotal / flowDisplayText

• flowStepTotal：固定 8。

• flowStep：当前第几步，由 (orderStatus, flowStatus) 后端算好：

  flowStep 值	含义	对应 flowStatus
  0	待支付（步骤条尚未开始）	AWAITING_PAY
  1	补全信息	AWAITING_PROFILE
  2	配房	AWAITING_HOTEL_SUBMIT / AWAITING_HOTEL_CLAIM / HOTEL_IN_PROGRESS / HOTEL_NEED_ADJUST
  3	配车	AWAITING_VEHICLE_SUBMIT / VEHICLE_IN_PROGRESS / VEHICLE_NEED_ADJUST
  4	确认	PENDING_CONFIRM
  5	待出行	PENDING_DEPARTURE
  6	出行	TRAVELLING
  7	核单	PENDING_REVIEW
  8	结算	REVIEWING / SETTLED
  null	终态或未知（已完成 / 已取消 / 脏数据）	COMPLETED / CANCELLED 等

  ⚠️ flowStep 可能为 null（终态/脏数据），前端步骤条渲染需对 null 兜底（如直接显示 flowDisplayText，不画进度条）。

• flowDisplayText：步骤条当前步的中文文案（即你说的"流程进度名称"）。规则：

  • 终态优先：orderStatus=已取消 → "已取消"；已完成 → "已完成"
  • 非终态：等于当前 flowStatus 的中文名
  • 只给中文，不带 "X/8 · " 前缀，需要的话前端自拼。

---

flowDisplayText 与 flowStatusName 的区别（容易混）

• 非终态：两者完全相同（都是 flowStatus 的中文名）。
• 终态：
  • flowDisplayText 走粗状态：固定 "已取消" / "已完成"。
  • flowStatusName 走细状态：是 flowStatus 字段本身的 label。
• 建议：步骤条文案用 flowDisplayText（终态展示更干净）；纯流程状态文字用 flowStatusName。

---

响应示例（列表单条，只列状态/进度相关字段）

{
  "orderStatus": "PENDING_DEPARTURE",
  "orderStatusName": "待出行",
  "flowStatus": "PENDING_DEPARTURE",
  "flowStatusName": "待出行",
  "flowStep": 5,
  "flowStepTotal": 8,
  "flowDisplayText": "待出行"
  // progress / flowItems 即使返回也请忽略
}

终态示例（已取消）：

{
  "orderStatus": "CANCELLED",
  "orderStatusName": "已取消",
  "flowStatus": "CANCELLED",
  "flowStatusName": "已取消",
  "flowStep": null,            // 终态无步骤，前端兜底
  "flowStepTotal": 8,
  "flowDisplayText": "已取消"
}

---

业务边界 / 注意事项

1. 文案权威源是后端枚举（OrderStatus / OrderFlowStatus），运营改文案后端改枚举即可，前端不要硬编码英文→中文映射。
2. flowStep 可能为 null（终态/脏数据），步骤条渲染必须兜底。
3. progress（"3/10"）/ flowItems 是历史字段，列表场景不要消费；后续可能下线，提前别依赖。
4. 本文不改任何接口契约，纯字段选用约定，后端无需重启。

---

关联

• 状态中文名: Issue #3283 / PR #3284
• 8 步步骤条: Issue #3285 / PR #3286
• 接口: GET /v3/admin/order