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)
270 行
9.7 KiB
Markdown
270 行
9.7 KiB
Markdown
# 待支付订单流程状态文案返空（与步骤条对齐）— 修改接口 — 管理后台
|
||
|
||
> 变更类型：🔧 接口行为变更（出参字段值规则调整）
|
||
> 端类型：管理后台
|
||
> 日期：2026-06-17
|
||
> 服务：hl-order-service-v3
|
||
> PR：https://git.1814.love:8443/wx/HL/pulls/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 典型成功——待支付订单列表项
|
||
|
||
```json
|
||
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 有值，不受影响）
|
||
|
||
```json
|
||
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 业务失败——订单不存在（详情接口）
|
||
|
||
```json
|
||
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：https://git.1814.love:8443/wx/HL/issues/3923
|
||
- PR：https://git.1814.love:8443/wx/HL/pulls/3926
|
||
- Commit：https://git.1814.love:8443/wx/HL/commit/6f0648a28a17daafc4e6ebafdd36fb8c7a3b8e6b
|
||
- 后端负责人：腰苏图
|