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

docs(order/admin): 订单列表售后 Tab 接口变更通知 (#4222/#4225)

浏览代码 
GET /v3/admin/order/status-group-counts 返回数组由 5 项增至 6 项，新增末项售后(AFTERSALE)。
GET /v3/admin/order statusGroup 参数新增枚举值 AFTERSALE。
售后为横切叠加语义，计数不纳入全部总数，与出行阶段 Tab 正交。
这个提交包含在：
yaosutu 2026-06-22 15:47:41 +08:00
父节点 38960ac9d3
当前提交 0df61a7b61
共有 1 个文件被更改，包括 289 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

289
changelogs-v2/2026-06/22_4222_订单列表售后Tab-修改接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,289 @@
# 订单列表售后 Tab — 修改接口（管理后台）
- **日期**：2026-06-22
- **端类型**：管理后台
- **Issue**：[#4222](https://git.1814.love:8443/wx/HL/issues/4222)
- **PR**：[#4225](https://git.1814.love:8443/wx/HL/pulls/4225)
- **Commit**：[82c669b2a](https://git.1814.love:8443/wx/HL/commit/82c669b2a)
- **后端负责人**：腰苏图
---
## 1. 接口背景
管理后台订单列表原有 5 个 Tab（全部 / 出行前 / 出行中 / 核单 / 异常取消），均以 `orderStatus`（订单状态）为过滤维度。
本次新增第 6 个「售后」Tab，以 `aftersale_status=IN_PROGRESS` 为过滤维度。售后是**横切（叠加）语义**，与出行阶段正交：一个订单可同时出现在某出行阶段 Tab 和售后 Tab，且售后计数**不计入**「全部」（全部仍 = 出行前 + 出行中 + 核单 + 异常取消四项之和）。
---
## 2. 变更清单
| # | 接口 | 变更类型 | 具体内容 |
|---|------|----------|----------|
| 1 | `GET /v3/admin/order/status-group-counts` | ⚠️ 出参新增 | 返回数组由 5 项变 6 项，末尾新增 `{ group: "AFTERSALE", label: "售后", orderCount: N }` |
| 2 | `GET /v3/admin/order` | ✨ 入参枚举新增 | `statusGroup` 新增可选值 `AFTERSALE` |
---
## 3. 接口详情
### 接口一：订单列表 Tab 分组计数
| 项 | 内容 |
|----|------|
| 方法 + 路径 | `GET /v3/admin/order/status-group-counts` |
| 功能描述 | 返回各 Tab 的订单计数，供顶部 Tab 展示角标数字 |
| 认证 | Bearer Token（管理员 JWT，必填） |
| 幂等性 | 只读，天然幂等 |
| 限流 | 无独立限流策略 |
### 接口二：订单列表
| 项 | 内容 |
|----|------|
| 方法 + 路径 | `GET /v3/admin/order` |
| 功能描述 | 管理后台订单列表，支持多维度过滤与分页 |
| 认证 | Bearer Token（管理员 JWT，必填） |
| 幂等性 | 只读，天然幂等 |
| 限流 | 无独立限流策略 |
---
## 4. 接口入参
### 4.1 接口一入参（Query 参数，与 GET /v3/admin/order 共用过滤字段）
> 计数接口忽略分页字段（page / pageSize），只消费过滤字段。
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| keyword | String | 否 | 关键词（订单号 / 客户姓名 / 手机号） |
| departureDateFrom | String | 否 | 出发日期起（yyyy-MM-dd） |
| departureDateTo | String | 否 | 出发日期止（yyyy-MM-dd） |
| consultantName | String | 否 | 定制师姓名 |
| createSource | String | 否 | 订单来源（字典值） |
| tagNames | Array\<String\> | 否 | 标签名列表，多值 AND |
### 4.2 接口二入参（Query 参数）
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | Integer | 否 | 页码，默认 1 |
| pageSize | Integer | 否 | 每页数量，默认 20 |
| keyword | String | 否 | 关键词 |
| departureDateFrom | String | 否 | 出发日期起（yyyy-MM-dd） |
| departureDateTo | String | 否 | 出发日期止（yyyy-MM-dd） |
| consultantName | String | 否 | 定制师姓名 |
| createSource | String | 否 | 订单来源字典值 |
| tagNames | Array\<String\> | 否 | 标签名列表 |
| orderStatus | String | 否 | 订单状态下拉（与 statusGroup 并存时为 AND） |
| statusGroup | String | 否 | Tab 分组标识，见枚举表，**本次新增 `AFTERSALE`** |
---
## 5. 出参字段
### 接口一出参
`Result<List<StatusGroupCountVO>>`，数组共 **6 项**（固定顺序）。
**StatusGroupCountVO 字段：**
| 字段名 | 类型 | 说明 |
|--------|------|------|
| group | String | 分组标识，见枚举表 |
| label | String | 分组中文标签（直接展示） |
| orderCount | long | 该分组订单数 |
**6 项固定顺序：**
| 顺序 | group | label | 语义 |
|------|-------|-------|------|
| 1 | ALL | 全部 | 全部订单（= 出行前+出行中+核单+异常取消之和，**不含**售后独立计数） |
| 2 | BEFORE_TRIP | 出行前 | orderStatus IN (PENDING_PAY, CUSTOMIZING, PENDING_DEPARTURE) |
| 3 | ON_TRIP | 出行中 | orderStatus = TRAVELLING |
| 4 | SETTLEMENT | 核单 | orderStatus = COMPLETED |
| 5 | ABNORMAL | 异常/取消 | orderStatus = CANCELLED |
| 6 | AFTERSALE | 售后 | aftersale_status = IN_PROGRESS（横切，不限出行阶段） |
### 接口二出参
`PageResult<OrderListItemVO>`，字段结构与本次无变化。
---
## 6. 枚举 / 数据字典
### statusGroup 枚举值（接口二入参 + 接口一出参 group 字段）
| 枚举值 | 含义 | 过滤维度 | 是否横切 |
|--------|------|----------|----------|
| ALL | 全部 | 不过滤（含取消） | 否 |
| BEFORE_TRIP | 出行前 | orderStatus IN (PENDING_PAY, CUSTOMIZING, PENDING_DEPARTURE) | 否 |
| ON_TRIP | 出行中 | orderStatus = TRAVELLING | 否 |
| SETTLEMENT | 核单 | orderStatus = COMPLETED | 否 |
| ABNORMAL | 异常/取消 | orderStatus = CANCELLED | 否 |
| **AFTERSALE** | **售后（新增）** | **aftersale_status = IN_PROGRESS** | **是** |
**横切说明**：`AFTERSALE` 不按 orderStatus 过滤，而是按 `aftersale_status=IN_PROGRESS` 过滤。一个出行中的订单如果同时有在途售后工单，该订单会出现在「出行中」Tab 和「售后」Tab 两处。
---
## 7. 错误码
| 错误码 | 含义 | 触发场景 |
|--------|------|----------|
| 401 | 未认证 | 未携带或 Token 失效 |
| 403 | 无权限 | 非管理员角色访问 |
| 422 | 参数校验失败 | statusGroup 传了无法识别的值（后端宽松处理：未知 group 忽略，不报 422；前端只传枚举表中的值即可） |
---
## 8. 示例
### 8.1 典型成功——获取各 Tab 计数（含售后）
**请求：**
```
GET /v3/admin/order/status-group-counts
Authorization: Bearer <admin_token>
```
**响应：**
```json
{
"code": 200,
"msg": "success",
"data": [
{ "group": "ALL", "label": "全部", "orderCount": 120 },
{ "group": "BEFORE_TRIP","label": "出行前", "orderCount": 50 },
{ "group": "ON_TRIP", "label": "出行中", "orderCount": 30 },
{ "group": "SETTLEMENT", "label": "核单", "orderCount": 35 },
{ "group": "ABNORMAL", "label": "异常/取消","orderCount": 5 },
{ "group": "AFTERSALE", "label": "售后", "orderCount": 8 }
]
}
```
> 注意：ALL.orderCount(120) = 50+30+35+5 = 120，不含 AFTERSALE 的 8。
### 8.2 边界情况——无任何在途售后工单
**请求：**
```
GET /v3/admin/order/status-group-counts
Authorization: Bearer <admin_token>
```
**响应（售后 orderCount = 0）：**
```json
{
"code": 200,
"data": [
{ "group": "ALL", "label": "全部", "orderCount": 30 },
{ "group": "BEFORE_TRIP","label": "出行前", "orderCount": 20 },
{ "group": "ON_TRIP", "label": "出行中", "orderCount": 8 },
{ "group": "SETTLEMENT","label": "核单", "orderCount": 2 },
{ "group": "ABNORMAL", "label": "异常/取消","orderCount": 0 },
{ "group": "AFTERSALE", "label": "售后", "orderCount": 0 }
]
}
```
### 8.3 业务失败——筛售后 Tab + 订单状态 AND 组合
**请求（出行中且在售后的单）：**
```
GET /v3/admin/order?statusGroup=AFTERSALE&orderStatus=TRAVELLING&page=1&pageSize=20
Authorization: Bearer <admin_token>
```
**响应（无出行中的在售后单时返回空列表）：**
```json
{
"code": 200,
"data": {
"total": 0,
"records": []
}
}
```
---
## 9. 业务边界
**适用：**
- `GET /v3/admin/order/status-group-counts` 在任意过滤条件下均会返回 6 项（含 AFTERSALE）
- `GET /v3/admin/order` 传 `statusGroup=AFTERSALE` 返回所有 `aftersale_status=IN_PROGRESS` 的订单，不限出行阶段（含已取消订单，只要售后工单仍在途）
**不适用：**
- 售后 Tab 不会从其他 Tab 移走订单：用户在「出行中」Tab 看到的订单不会因为开了售后工单而消失
- 售后计数不纳入「全部」总数，前端角标与「全部」Tab 数字不加 AFTERSALE.orderCount
**特殊边界：**
- `statusGroup=AFTERSALE` 与 `orderStatus=XXX` 同时传为 AND 关系（先按 aftersale_status=IN_PROGRESS 过滤，再按 orderStatus 收窄）
- `statusGroup=ALL` 时包含取消的单，即 `cancelled=true`，行为不变
---
## 10. 修改前后对比
### 出参对比（接口一 status-group-counts）
**字段级：**
| 字段/项 | 修改前 | 修改后 |
|---------|--------|--------|
| 返回数组长度 | 5 项（ALL + 4 阶段） | **6 项**（ALL + 4 阶段 + 售后） |
| 第 6 项 group | 无 | `AFTERSALE` |
| 第 6 项 label | 无 | `售后` |
| 第 6 项 orderCount | 无 | long，`aftersale_status=IN_PROGRESS` 的订单数 |
| ALL.orderCount 口径 | 四阶段之和 | **不变**，仍 = 四阶段之和，不含 AFTERSALE |
**行为级：**
| 行为 | 修改前 | 修改后 |
|------|--------|--------|
| 下拉菜单 statusGroup 可选值 | ALL / BEFORE_TRIP / ON_TRIP / SETTLEMENT / ABNORMAL | 同上 + **AFTERSALE** |
| 传 AFTERSALE 的过滤逻辑 | 传入忽略（未知 group） | 按 `aftersale_status=IN_PROGRESS` 过滤 |
---
## 11. 影响评估 / 回滚
**前端同步上线：**
- 若前端对 status-group-counts 返回长度做了硬编码（如 `data.length === 5`）或索引访问，需更新为动态渲染
- 需在 Tab 列表末尾渲染新的「售后」Tab，点击时传 `statusGroup=AFTERSALE`
- ALL.orderCount 口径不变，前端逻辑无需调整
**兼容性：**
- 不传 statusGroup 或传旧值的请求行为不变，向下兼容
- status-group-counts 固定多返回 1 项，前端旧版不会报错（JSON 数组多一项无副作用），但售后 Tab 不会渲染，属预期降级
**回滚方案：**
- 后端回滚：恢复 `OrderStatusGroup` 枚举（删除 AFTERSALE），countByStatusGroup 重新返回 5 项
- 前端回滚：无感知（旧前端代码仍正常，只是不展示售后 Tab）
---
## 12. 注意事项
1. **横切语义，计数不累加到 ALL**：前端不要把 AFTERSALE.orderCount 加到 ALL 的角标里，否则显示总数虚高。
2. **AND 过滤**：`statusGroup=AFTERSALE` 与 `orderStatus` 下拉同时传是合法且有意义的用法（筛"出行中且在售后"），前端过滤 UI 无需屏蔽两者同时选择。
3. **硬编码 5 个 Tab 需更新**：若之前按固定 5 项渲染 Tab，须改为遍历 API 返回数组动态渲染，否则「售后」Tab 不出现。
4. **售后 Tab 包含已取消订单**：`aftersale_status=IN_PROGRESS` 的订单不论 orderStatus 是什么（含 CANCELLED）都会出现在售后 Tab。
---
## 13. 关联 / 联系人
- **Issue**：[#4222 管理后台订单列表加「售后」Tab](https://git.1814.love:8443/wx/HL/issues/4222)
- **PR**：[#4225 feat(order-v3): 管理后台订单列表加「售后」Tab](https://git.1814.love:8443/wx/HL/pulls/4225)
- **Commit**：[399288d4d](https://git.1814.love:8443/wx/HL/commit/399288d4d97b26238d292b7c7768b69b67f46300)
- **关联 PR**：[#4197 订单售后中展示 aftersale_status（售后状态激活）](https://git.1814.love:8443/wx/HL/pulls/4197)
- **后端负责人**：腰苏图（yaosutu）