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

> 变更类型：✨ 新增接口
> 端类型：管理后台
> 日期：2026-06-17
> 服务：hl-order-service-v3
> PR：https://git.1814.love:8443/wx/HL/pulls/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 典型成功

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

```json
{
  "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 业务失败——未登录

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

---

## 9. 业务边界

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

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

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

---

## 12. 注意事项

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

---

## 13. 关联 / 联系人

- Issue：https://git.1814.love:8443/wx/HL/issues/3930
- PR：https://git.1814.love:8443/wx/HL/pulls/3934
- Commit：https://git.1814.love:8443/wx/HL/commit/ece0d86edb94053fc077b04272c4193b9f0755fd
- 后端负责人：腰苏图