wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

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)
这个提交包含在：
yaosutu 2026-06-17 18:10:37 +08:00
父节点 81f054d3a3
当前提交 4620642b9f
共有 3 个文件被更改，包括 633 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

269
changelogs-v2/2026-06/17_3923_订单待支付流程状态文案返空-修改接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,269 @@
# 待支付订单流程状态文案返空（与步骤条对齐）— 修改接口 — 管理后台
> 变更类型：🔧 接口行为变更（出参字段值规则调整）
> 端类型：管理后台
> 日期：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
- 后端负责人：腰苏图

149
changelogs-v2/2026-06/17_3930_订单状态筛选下拉选项端点-新增接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,149 @@
# 订单状态筛选下拉选项端点 — 新增接口 — 管理后台
> 变更类型：✨ 新增接口
> 端类型：管理后台
> 日期：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
- 后端负责人：腰苏图

215
changelogs-v2/2026-06/17_3938_订单列表Tab分组计数与分组过滤-新增接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,215 @@
# 订单列表 Tab 分组计数与分组过滤 — 新增接口 — 管理后台
> 变更类型：✨ 新增接口 + 修改接口（列表新增入参）
> 端类型：管理后台
> 日期：2026-06-17
> 服务：hl-order-service-v3
> PR：https://git.1814.love:8443/wx/HL/pulls/3939
---
## 1. 接口背景
**功能页面**：管理后台「订单列表」页的**顶部 Tab 栏**（出行前 / 出行中 / 核单 / 异常·取消 / 全部）。
**用在哪**：
1. **Tab 计数徽标**：页面加载 / 筛选条件变更时，调 `GET /v3/admin/order/status-group-counts` 取每个 Tab 上显示的订单数量角标（如"出行前 33"、"异常/取消 5"）。
2. **点击 Tab 过滤列表**：用户点某个 Tab，前端只需把该 Tab 的 `group` 值作为 `statusGroup` 参数传给列表接口（`GET /v3/admin/order`），后端内部把 group 展开为对应状态集合过滤，前端无需自己维护"哪个 Tab 对应哪些状态"的映射。
**设计意图**：把 6 个粗状态按出行阶段折叠成 4 组+全部，让定制师快速聚焦当前阶段的订单，Tab 计数单独一个端点供徽标独立刷新，点击 Tab 与列表接口通过 `statusGroup` 解耦。
---
## 2. 变更清单
| 变更类型 | 接口 | 说明 |
|---|---|---|
| ✨ 新增 | `GET /v3/admin/order/status-group-counts` | Tab 分组计数，返回 5 项（ALL + 4 组），每项含 group/label/orderCount |
| ⚠️ 修改 | `GET /v3/admin/order`（列表） | 新增可选入参 `statusGroup`，前端传 group key 触发 Tab 过滤 |
---
## 3. 接口详情
### 3.1 Tab 分组计数
- **方法 + 路径**：`GET /v3/admin/order/status-group-counts`
- **接口名**：订单列表 Tab 分组计数
- **认证**：需要 JWT（管理后台登录 token）
- **幂等性**：查询接口，天然幂等
- **限流**：无独立限流规则
- **语义**：计数值尊重其他筛选条件（keyword/出发日期/定制师名/来源/标签），但与当前选中 Tab 无关（faceted 计数，ALL 恒含已取消）
### 3.2 订单列表（新增 statusGroup 入参）
- **方法 + 路径**：`GET /v3/admin/order`（别名 `GET /v3/admin/order/list`）
- **接口名**：订单列表
- **认证**：需要 JWT
- **幂等性**：查询接口，天然幂等
- **限流**：无独立限流规则
---
## 4. 接口入参
### 4.1 Tab 分组计数 Query 参数（复用列表筛选条件，不传 orderStatus / statusGroup）
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `keyword` | String | 否 | 关键字模糊搜索（团号/客户姓名/产品名/订单号） |
| `departureDateFrom` | LocalDate | 否 | 出发日期起始（格式 `yyyy-MM-dd`） |
| `departureDateTo` | LocalDate | 否 | 出发日期结束（格式 `yyyy-MM-dd`） |
| `consultantName` | String | 否 | 定制师姓名 LIKE 匹配 |
| `createSource` | String | 否 | 订单来源（`CONSULTANT` / `CUSTOMER`） |
| `tagNames` | List\<String\> | 否 | 标签名列表过滤（AND） |
> 注：不传 `orderStatus`（按 group 内部统计）、不传 `statusGroup`（计数接口自己统计所有组）、不传 `page`/`pageSize`（计数接口无分页）。
### 4.2 订单列表新增入参
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `statusGroup` | String | 否 | Tab 分组 key，取值见下方枚举表；后端内部展开为 orderStatus 集合；与 `orderStatus` 下拉并存时取 AND；不传或传 `ALL` 时含已取消 |
---
## 5. 出参字段
### 5.1 Tab 分组计数 StatusGroupCountVO
返回类型：`Result<List<StatusGroupCountVO>>`，共 5 项，ALL 在首位，后跟 4 组，按固定顺序。
| 字段 | 类型 | 说明 | 示例 |
|---|---|---|---|
| `group` | String | 分组标识 key，对应 `statusGroup` 入参 | `"BEFORE_TRIP"` |
| `label` | String | 分组中文标签，用于 Tab 展示 | `"出行前"` |
| `orderCount` | Long | 该分组订单数（满足其他筛选条件的计数） | `33` |
### 5.2 订单列表（本次只新增入参，出参字段不变，无需修改）
订单列表 `OrderListItemRespVO` 出参字段无变化（参考现有接口文档）。
---
## 6. 枚举 / 数据字典
### Tab 分组 group 值（statusGroup 参数取值 + 分组计数返回 group 值）
| group 值 | 中文标签 | 含义（包含的 orderStatus） |
|---|---|---|
| `ALL` | 全部 | 全部状态（含已取消） |
| `BEFORE_TRIP` | 出行前 | `PENDING_PAY`（待支付）+ `CUSTOMIZING`（定制中）+ `PENDING_DEPARTURE`（待出行） |
| `ON_TRIP` | 出行中 | `TRAVELLING`（出行中） |
| `SETTLEMENT` | 核单 | `COMPLETED`（已完成，横跨核单+结算两子阶段） |
| `ABNORMAL` | 异常/取消 | `CANCELLED`（已取消） |
> 前端只需感知 group 值，状态枚举的内部映射由后端维护，前端不用硬编码。
---
## 7. 错误码
| code | 含义 |
|---|---|
| `200` | 成功 |
| `401` | 未登录 / token 过期 |
| `400` | `statusGroup` 传了非法值（后端宽松处理：未知 group 忽略，不抛 400；但建议传枚举定义值） |
---
## 8. 示例
### 8.1 典型成功——获取 Tab 分组计数
```http
GET /v3/admin/order/status-group-counts
Authorization: Bearer <token>
```
```json
{
"code": 200,
"data": [
{ "group": "ALL", "label": "全部", "orderCount": 38 },
{ "group": "BEFORE_TRIP","label": "出行前", "orderCount": 33 },
{ "group": "ON_TRIP", "label": "出行中", "orderCount": 0 },
{ "group": "SETTLEMENT", "label": "核单", "orderCount": 0 },
{ "group": "ABNORMAL", "label": "异常/取消", "orderCount": 5 }
]
}
```
### 8.2 边界——带筛选条件的计数（Faceted，计数随筛选条件变化）
```http
GET /v3/admin/order/status-group-counts?departureDateFrom=2026-07-01&departureDateTo=2026-07-31
```
返回值中每组 `orderCount` 仅统计出发日期在 7 月的订单，即使当前 Tab 已选 BEFORE_TRIP，ALL 和其他组也只统计 7 月内的。
```json
{
"code": 200,
"data": [
{ "group": "ALL", "label": "全部", "orderCount": 12 },
{ "group": "BEFORE_TRIP","label": "出行前", "orderCount": 10 },
{ "group": "ON_TRIP", "label": "出行中", "orderCount": 1 },
{ "group": "SETTLEMENT", "label": "核单", "orderCount": 0 },
{ "group": "ABNORMAL", "label": "异常/取消", "orderCount": 1 }
]
}
```
### 8.3 业务失败——点击 Tab 后列表 statusGroup 传了未知值
```http
GET /v3/admin/order?statusGroup=UNKNOWN_GROUP&page=1&pageSize=10
```
```json
{
"code": 200,
"data": {
"total": 38,
"list": [ ... ]
}
}
```
> 后端宽松处理：未知 group 忽略，等同于不传 statusGroup（返回默认不含已取消的全部订单）。前端避免传枚举定义之外的值。
---
## 9. 业务边界
**适用**：
- 管理后台订单列表顶部 Tab 计数徽标渲染。
- 用户点击 Tab 触发列表按分组过滤。
**不适用**：
- 分组计数不适用于精确状态统计（`SETTLEMENT` 组包含 `COMPLETED`，横跨核单和结算两个子阶段，不区分子状态）。
- 分组计数的 `ALL` 恒含已取消订单（不可排除）；其他接口参数 `cancelled=false` 对分组计数无效。
**特殊边界**：
- `statusGroup=ALL` 与不传 `statusGroup` 行为不同：传 `ALL` 时含已取消；不传时默认不含已取消（`cancelled` 默认 `false`）。
- `statusGroup` 与 `orderStatus` 下拉可同时传，取 AND 逻辑（例：`statusGroup=BEFORE_TRIP&orderStatus=CUSTOMIZING` 只返定制中的订单）。
- 分组计数与当前选中 Tab 的 `statusGroup` 无关（Faceted 设计），每次只要其他筛选条件变了就重新调计数接口。
---
## 12. 注意事项
- **计数接口与列表接口分开调**：Tab 徽标数字调 `status-group-counts`，Tab 点击过滤调 `GET /v3/admin/order?statusGroup=...`，两者分开请求。
- **`statusGroup=ALL` 传参覆盖默认排除取消**：前端若需要"全部"含取消，用 `statusGroup=ALL` 而不是 `cancelled=true`（两者效果等同，但 `statusGroup=ALL` 更语义明确）。
- **分组映射由后端维护**：前端不要在代码里硬编码"BEFORE_TRIP = [PENDING_PAY, CUSTOMIZING, PENDING_DEPARTURE]"这样的映射表——这是后端内部逻辑，后端调整分组时前端自动跟随。
- 已实测（2026-06-17，测试服 dev-v3）：`statusGroup=BEFORE_TRIP` 返 33 单、无越界；`ALL` 组计数 = 4 组之和。
---
## 13. 关联 / 联系人
- Issue：https://git.1814.love:8443/wx/HL/issues/3938
- PR：https://git.1814.love:8443/wx/HL/pulls/3939
- Commit（refactor review 后）：https://git.1814.love:8443/wx/HL/commit/5eca8d67b0432dfc19e2b6d2c67ef7e6eac6ec02
- 后端负责人：腰苏图