wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-06/22_4197_订单售后中展示-修改接口-管理后台.md

244 行
8.3 KiB
Markdown
原始文件 Blame 文件历史

此文件含有模棱两可的 Unicode 字符

此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的，可以安全地忽略该警告。 使用 Escape 按钮显示他们。

# 订单「售后中」展示激活（aftersale_status） — 修改接口（管理后台）
- **端类型**：管理后台
- **日期**：2026-06-22
- **Issue**：[#4197](https://git.1814.love:8443/wx/HL/issues/4197)
- **PR**：[#4208](https://git.1814.love:8443/wx/HL/pulls/4208)
- **Commit**：[334272517](https://git.1814.love:8443/wx/HL/commit/3342725174cd706175a2bea0a162eea2c1333206)
- **后端负责人**：yaosutu
---
## 1. 接口背景
v3 订单主表 `order_main` 有预留字段 `aftersale_status`，此前零写入、无枚举、VO 不输出（字段恒为 null）。本次激活该字段：用户发起任意售后工单（投诉/申诉）时，后端自动将订单置为「售后中」（`IN_PROGRESS`）；当该订单所有售后工单全部终结（CLOSED 或 WITHDRAWN）后，自动回切为「售后完成」（`RESOLVED`）。管理后台订单列表和订单详情均新增此字段，可据此实现「售后中」Tab 或标记。
---
## 2. 变更清单
| 变更类型 | 接口 | 字段 | 说明 |
|---------|------|------|------|
| ✨ 出参新增 | `GET /v3/admin/order/list`（订单列表） | `aftersaleStatus` | 订单售后汇总状态枚举 |
| ✨ 出参新增 | `GET /v3/admin/order/list`（订单列表） | `aftersaleStatusName` | 售后状态中文名 |
| ✨ 出参新增 | `GET /v3/admin/order/{id}`（订单详情） | `aftersaleStatus` | 订单售后汇总状态枚举 |
| ✨ 出参新增 | `GET /v3/admin/order/{id}`（订单详情） | `aftersaleStatusName` | 售后状态中文名 |
---
## 3. 接口详情
### 3.1 订单列表
| 属性 | 值 |
|-----|-----|
| 方法 + 路径 | `GET /v3/admin/order/list` |
| 接口描述 | 管理后台订单列表（分页），新增售后汇总状态字段 |
| 认证 | 需要管理员 JWT |
| 限流 | 无独立限流 |
### 3.2 订单详情
| 属性 | 值 |
|-----|-----|
| 方法 + 路径 | `GET /v3/admin/order/{id}` |
| 接口描述 | 管理后台订单详情，新增售后汇总状态字段 |
| 认证 | 需要管理员 JWT |
| 限流 | 无独立限流 |
---
## 4. 接口入参
本次变更**仅涉及出参**，入参无变化。
---
## 5. 出参字段
### OrderListItemRespVO（订单列表单条）— 新增字段
| 字段名 | 类型 | 说明 |
|-------|------|------|
| **aftersaleStatus** | **String** | **订单售后汇总状态枚举，取值见 §6** |
| **aftersaleStatusName** | **String** | **售后状态中文名（如「售后中」）** |
（其余字段不变，以下仅列新增部分）
### OrderMainVO（订单详情）— 新增字段
| 字段名 | 类型 | 说明 |
|-------|------|------|
| **aftersaleStatus** | **String** | **订单售后汇总状态枚举，取值见 §6** |
| **aftersaleStatusName** | **String** | **售后状态中文名（如「售后中」）** |
---
## 6. 枚举 / 数据字典
### aftersaleStatus — 订单售后汇总状态
> 此枚举为状态机字段（非业务分类字段），`aftersaleStatusName` 来自枚举自身的 label，**不走数据字典**。
| 值 | 中文名（aftersaleStatusName） | 含义 | 触发条件 |
|----|------------------------------|------|---------|
| `NONE` | 无售后 | 订单无售后工单，或全部已终结且从未有活跃工单 | 初始默认态；DB `null` 也兜底为此 |
| `IN_PROGRESS` | 售后中 | 订单存在至少 1 条活跃售后工单（状态非 CLOSED/WITHDRAWN） | 用户发起投诉或申诉时自动置入 |
| `RESOLVED` | 售后完成 | 订单所有售后工单均已终结（均为 CLOSED 或 WITHDRAWN） | 最后一条活跃工单关闭/撤回时自动回切 |
**注意**：`aftersaleStatus` 是订单维度的**汇总状态**，与单条工单的 `status`（SUBMITTED / PROCESSING / RESOLVED / CLOSED / WITHDRAWN）是**两个独立维度**，不要混淆。
---
## 7. 错误码
| 错误码 | HTTP 状态 | 含义 | 触发场景 |
|-------|---------|------|---------|
| 200-001 | 401 | 未授权 | JWT 缺失或过期 |
| 200-002 | 403 | 无权操作 | 非管理员角色 |
| 580001 | 404 | 订单不存在 | 订单 ID 无效 |
---
## 8. 示例
### 8.1 典型成功——订单列表含售后中状态
**请求**
```http
GET /v3/admin/order/list?page=1&size=10
Authorization: Bearer <admin-jwt>
```
**响应（节选单条）**
```json
{
"code": 200,
"msg": "success",
"data": {
"total": 100,
"list": [
{
"id": "1234567890",
"orderNo": "HL20260622001",
"status": "PAID",
"statusName": "已支付",
"aftersaleStatus": "IN_PROGRESS",
"aftersaleStatusName": "售后中",
"totalAmount": 9800.00,
"createdAt": "2026-06-20T08:00:00"
}
]
}
}
```
### 8.2 边界情况——订单无售后工单（默认 NONE）
**响应（订单详情节选）**
```json
{
"code": 200,
"msg": "success",
"data": {
"id": "1234567891",
"orderNo": "HL20260622002",
"status": "CONFIRMED",
"statusName": "已确认",
"aftersaleStatus": "NONE",
"aftersaleStatusName": "无售后"
}
}
```
> 历史订单（字段激活前创建）DB 中 `aftersale_status` 为 `null`，后端自动兜底为 `NONE`，前端无需特殊处理。
### 8.3 业务失败——订单不存在
```http
GET /v3/admin/order/9999999999
Authorization: Bearer <admin-jwt>
```
```json
{
"code": 580001,
"msg": "订单不存在",
"data": null
}
```
---
## 9. 业务边界
**适用场景**：
- 前端订单列表希望展示「售后中」Tab，筛选 `aftersaleStatus=IN_PROGRESS` 的订单
- 订单详情页顶部展示售后状态标记
- 客服看板中识别需跟进的售后订单
**不适用场景**：
- `aftersaleStatus` 不反映具体工单的处理进度，需查工单列表接口获取详情
**特殊边界**：
- `IN_PROGRESS` 的触发是用户发起任意工单（投诉 or 申诉），只要存在一条非终结工单即为此态
- 多条工单的情况：必须全部终结（全部 CLOSED 或 WITHDRAWN）才回切 `RESOLVED`
- `RESOLVED` 态表示所有工单已关闭，但不代表用户诉求已满足（仅流程终态）
- 后端激活写入逻辑：工单 CLOSED 到终态（5 个路径均已覆盖：管理员驳回/整改完成/用户撤回/OA 驳回/退款成功）
---
## 10. 修改前后对比
### 字段级对比
**OrderListItemRespVO（订单列表）**
| 字段 | 变更前 | 变更后 |
|------|-------|-------|
| aftersaleStatus | 不存在 | 新增，String，订单售后汇总状态枚举 |
| aftersaleStatusName | 不存在 | 新增，String，中文名如「售后中」 |
**OrderMainVO（订单详情）**
| 字段 | 变更前 | 变更后 |
|------|-------|-------|
| aftersaleStatus | 不存在（字段预留但零输出） | 新增，String，订单售后汇总状态枚举 |
| aftersaleStatusName | 不存在 | 新增，String，中文名 |
### 行为级对比
| 维度 | 变更前 | 变更后 |
|------|-------|-------|
| 用户发起售后工单后，订单 aftersaleStatus | 恒为 null（字段无写入） | 自动置为 IN_PROGRESS |
| 所有工单终结后，aftersaleStatus | 恒为 null | 自动回切为 RESOLVED |
| 订单列表/详情 aftersaleStatus | 不返回此字段 | 返回枚举值 + 中文名 |
---
## 11. 影响评估 / 回滚
| 维度 | 结论 |
|------|------|
| 破坏兼容性 | 否（出参新增字段，旧版忽略） |
| 前端同步上线 | 建议同步展示：订单列表加「售后中」Tab；订单详情头部加状态标记 |
| 回滚方案 | 后端回滚 PR #4208 即可；零 DDL（`aftersale_status` 列早已存在），无数据损失风险 |
---
## 12. 注意事项
1. 历史订单 `aftersale_status` 为 `null`，后端兜底输出 `NONE`，前端不需要判空。
2. `aftersaleStatus` 与单条工单的 `status` 字段是两个维度，不要用工单 status 推断订单 aftersaleStatus。
3. v3 C 端订单接口（`/v3/mp/orders`）尚未建立，该接口就绪后后端将同步补充此字段，届时会另推 changelog（follow-up）。
---
## 13. 关联 / 联系人
- **Issue**：[https://git.1814.love:8443/wx/HL/issues/4197](https://git.1814.love:8443/wx/HL/issues/4197)
- **PR**：[https://git.1814.love:8443/wx/HL/pulls/4208](https://git.1814.love:8443/wx/HL/pulls/4208)
- **Commit**：[https://git.1814.love:8443/wx/HL/commit/3342725174cd706175a2bea0a162eea2c1333206](https://git.1814.love:8443/wx/HL/commit/3342725174cd706175a2bea0a162eea2c1333206)
- **关联 Issue**：[#4161 售后申诉中心](https://git.1814.love:8443/wx/HL/issues/4161)
- **后端负责人**：yaosutu
在新工单中引用 查看 Git Blame 复制永久链接