yaosutu 4620642b9f feat(order-v3): 推送订单列表3个接口变更changelog(#3923/#3930/#3938)

- 修改接口: 待支付订单flowStatusName/flowDisplayText返null(#3923)
- 新增接口: GET /v3/admin/order/status-options 订单状态下拉(#3930)
- 新增接口: GET /v3/admin/order/status-group-counts Tab分组计数(#3939)
- 修改接口: GET /v3/admin/order 新增入参statusGroup Tab过滤(#3939)

2026-06-17 18:10:44 +08:00

4.4 KiB

原始文件 Blame 文件历史

订单状态筛选下拉选项端点 — 新增接口 — 管理后台

变更类型：✨ 新增接口端类型：管理后台日期：2026-06-17 服务：hl-order-service-v3 PR：wx/HL#3934

1. 接口背景

功能页面：管理后台「订单列表」页的筛选栏 — "订单状态"下拉框。

用在哪：订单列表顶部筛选区域，用户点"订单状态"下拉时渲染选项列表（6 个状态），选中后把对应的 value 作为 orderStatus 参数传给列表接口过滤。

为什么新增：之前前端硬编码 6 个订单状态选项。订单状态是后端状态机枚举，未来若调整（改名/增减），前端需同步手动改。现改为后端派生，前端从此端点取选项，单一真相源在枚举，改状态前端自动跟随，无需手动维护。

2. 变更清单

变更类型	接口	说明
✨ 新增	`GET /v3/admin/order/status-options`	返回 6 个订单状态枚举选项（value + label），供订单列表状态筛选下拉使用

3. 接口详情

方法 + 路径：GET /v3/admin/order/status-options
接口名：订单状态枚举选项（下拉）
认证：需要 JWT（管理后台登录 token，Gateway 注入 X-Admin-Id）
幂等性：查询接口，天然幂等
限流：无独立限流规则
说明：路径为字面量，Spring 路由优先于 /{id} 动态路径，不会冲突

4. 接口入参

无入参（无 Query 参数、无请求体）。

5. 出参字段

返回类型：Result<List<OrderStatusOptionVO>>

字段	类型	说明	示例
`value`	String	订单状态枚举值，传给列表接口 `orderStatus` 参数	`"PENDING_PAY"`
`label`	String	订单状态中文名，用于下拉展示	`"待支付"`

返回固定 6 项，按生命周期顺序：

序号	value	label
1	`PENDING_PAY`	待支付
2	`CUSTOMIZING`	定制中
3	`PENDING_DEPARTURE`	待出行
4	`TRAVELLING`	出行中
5	`COMPLETED`	已完成
6	`CANCELLED`	已取消

6. 枚举 / 数据字典

本接口出参即为订单状态枚举的完整映射（见出参字段表），无额外枚举依赖。

7. 错误码

code	含义
`200`	成功（data 为 6 个选项数组）
`401`	未登录 / token 过期

8. 示例

8.1 典型成功

GET /v3/admin/order/status-options
Authorization: Bearer <token>

{
  "code": 200,
  "data": [
    { "value": "PENDING_PAY",        "label": "待支付" },
    { "value": "CUSTOMIZING",        "label": "定制中" },
    { "value": "PENDING_DEPARTURE",  "label": "待出行" },
    { "value": "TRAVELLING",         "label": "出行中" },
    { "value": "COMPLETED",          "label": "已完成" },
    { "value": "CANCELLED",          "label": "已取消" }
  ]
}

8.2 边界——未来状态机新增/改名后的自动适配

后端枚举新增状态后，本接口返回的数组会自动多出对应项，前端无需感知，下拉自动展示新选项。

8.3 业务失败——未登录

{
  "code": 401,
  "msg": "未登录或 token 已过期"
}

9. 业务边界

适用：

管理后台订单列表「订单状态」下拉框选项渲染。
选中某选项后，把 value 作为 GET /v3/admin/order 的 orderStatus 参数传入。

不适用：

不适用于小程序端（小程序无订单列表状态筛选下拉）。
不适用于流程状态（flowStatus）筛选，本接口仅覆盖粗状态（orderStatus）。

特殊边界：

本接口返回所有状态（含 CANCELLED 已取消），如需在下拉中排除已取消，前端自行过滤，后端不做删减。

12. 注意事项

前端调用此端点后，不再需要在代码里硬编码 6 个状态；选中 value 直接传给列表接口 orderStatus 参数即可。
本接口无分页，永远返回完整枚举列表，前端可在应用启动时预加载缓存。
value 与列表接口 orderStatus 参数完全对应，可直接作为传参值。

13. 关联 / 联系人

Issue：wx/HL#3930
PR：wx/HL#3934
Commit：ece0d86edb
后端负责人：腰苏图

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