4620642b9f
- 修改接口: 待支付订单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)
150 行
4.4 KiB
Markdown
150 行
4.4 KiB
Markdown
# 订单状态筛选下拉选项端点 — 新增接口 — 管理后台
|
||
|
||
> 变更类型：✨ 新增接口
|
||
> 端类型：管理后台
|
||
> 日期：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
|
||
- 后端负责人：腰苏图
|