238 行
7.0 KiB
Markdown
238 行
7.0 KiB
Markdown
# 售后工单接入 wx 内容安全机审 — 修改接口（管理后台）
|
||
|
||
- **端类型**：管理后台
|
||
- **日期**：2026-06-22
|
||
- **Issue**：[#4196](https://git.1814.love:8443/wx/HL/issues/4196)
|
||
- **PR**：[#4203](https://git.1814.love:8443/wx/HL/pulls/4203)
|
||
- **Commit**：[8882eb156](https://git.1814.love:8443/wx/HL/commit/8882eb1568a7e5ab8f48a6db4b7e3d4d4b6f2c15)
|
||
- **后端负责人**：yaosutu
|
||
|
||
---
|
||
|
||
## 1. 接口背景
|
||
|
||
售后工单（投诉/申诉）接入微信内容安全机审后，管理后台在查看工单详情或列表时，可以看到每条工单的机审结果（`auditStatus`）。客服可据此判断用户提交内容是否经机审标记为违规，辅助处理决策。
|
||
|
||
---
|
||
|
||
## 2. 变更清单
|
||
|
||
| 变更类型 | 接口 | 字段 | 说明 |
|
||
|---------|------|------|------|
|
||
| ✨ 出参新增 | `GET /v3/admin/aftersale/ticket/{id}` | `auditStatus` | 工单 wx 内容安全机审状态 |
|
||
| ✨ 出参新增 | `GET /v3/admin/aftersale/ticket/page` | `auditStatus` | 工单列表每条记录新增机审状态 |
|
||
|
||
---
|
||
|
||
## 3. 接口详情
|
||
|
||
### 3.1 工单详情
|
||
|
||
| 属性 | 值 |
|
||
|-----|-----|
|
||
| 方法 + 路径 | `GET /v3/admin/aftersale/ticket/{id}` |
|
||
| 接口描述 | 管理后台查看单条售后工单详情 |
|
||
| 认证 | 需要管理员 JWT |
|
||
| 限流 | 无独立限流 |
|
||
|
||
### 3.2 工单分页列表
|
||
|
||
| 属性 | 值 |
|
||
|-----|-----|
|
||
| 方法 + 路径 | `GET /v3/admin/aftersale/ticket/page` |
|
||
| 接口描述 | 管理后台分页查询售后工单列表 |
|
||
| 认证 | 需要管理员 JWT |
|
||
| 限流 | 无独立限流 |
|
||
|
||
---
|
||
|
||
## 4. 接口入参
|
||
|
||
本次变更**仅涉及出参**，入参无变化。
|
||
|
||
---
|
||
|
||
## 5. 出参字段
|
||
|
||
### TicketAdminRespVO（工单详情/列表单条）
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|-------|------|------|
|
||
| id | Long | 工单 ID |
|
||
| orderId | Long | 关联订单 ID |
|
||
| orderNo | String | 订单编号 |
|
||
| category | String | 工单分类枚举：COMPLAINT / APPEAL |
|
||
| type | String | 工单类型 |
|
||
| title | String | 标题 |
|
||
| description | String | 描述 |
|
||
| status | String | 工单状态：SUBMITTED / PROCESSING / RESOLVED / CLOSED / WITHDRAWN |
|
||
| statusName | String | 工单状态中文名 |
|
||
| linkedRefundId | Long | 关联退款单 ID（申诉退款回填） |
|
||
| **auditStatus** | **String** | **wx 内容安全机审状态，取值见 §6** |
|
||
| attachments | List\<String\> | 附件 URL |
|
||
| createdAt | String | 创建时间（ISO 8601） |
|
||
| updatedAt | String | 更新时间（ISO 8601） |
|
||
|
||
---
|
||
|
||
## 6. 枚举 / 数据字典
|
||
|
||
### auditStatus — wx 内容安全机审状态
|
||
|
||
| 值 | 含义 | 触发条件 |
|
||
|----|------|---------|
|
||
| `PENDING` | 机审中 | 工单创建时携带了 mediaTraceIds（等待微信异步回调） |
|
||
| `APPROVED` | 已通过 | 无媒体附件的工单直接置此；微信回调合规也置此 |
|
||
| `MANUAL_REVIEW` | 需人工复审 | 微信机审认为需要人工介入 |
|
||
| `REJECTED` | 已驳回 | 微信机审判定内容违规 |
|
||
|
||
> **管理后台可操作建议**：`REJECTED` 的工单表示用户上传的媒体内容被微信判定违规，客服可将此作为处置参考，但工单本身流程不受影响，需客服手动决定是否关闭。
|
||
|
||
---
|
||
|
||
## 7. 错误码
|
||
|
||
| 错误码 | HTTP 状态 | 含义 | 触发场景 |
|
||
|-------|---------|------|---------|
|
||
| 200-001 | 401 | 未授权 | JWT 缺失或过期 |
|
||
| 200-002 | 403 | 无权操作 | 非管理员角色 |
|
||
| 581001 | 404 | 工单不存在 | 工单 ID 无效 |
|
||
|
||
---
|
||
|
||
## 8. 示例
|
||
|
||
### 8.1 典型成功——查询已通过机审的工单详情
|
||
|
||
**请求**
|
||
```http
|
||
GET /v3/admin/aftersale/ticket/987654321
|
||
Authorization: Bearer <admin-jwt>
|
||
```
|
||
|
||
**响应**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 987654321,
|
||
"orderId": 1234567890,
|
||
"orderNo": "HL20260622001",
|
||
"category": "COMPLAINT",
|
||
"type": "HOTEL",
|
||
"title": "酒店降级安排",
|
||
"description": "预订四星，实际三星，差价未退。",
|
||
"status": "SUBMITTED",
|
||
"statusName": "已提交",
|
||
"linkedRefundId": null,
|
||
"auditStatus": "APPROVED",
|
||
"attachments": [
|
||
"https://oss.example.com/media/hotel_photo_1.jpg"
|
||
],
|
||
"createdAt": "2026-06-22T10:30:00",
|
||
"updatedAt": "2026-06-22T10:32:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.2 边界情况——机审中（PENDING）的工单
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": 987654322,
|
||
"orderId": 1234567890,
|
||
"orderNo": "HL20260622001",
|
||
"category": "APPEAL",
|
||
"type": "PRICE",
|
||
"title": "价格异议",
|
||
"description": "临时收费未在合同内。",
|
||
"status": "SUBMITTED",
|
||
"statusName": "已提交",
|
||
"linkedRefundId": null,
|
||
"auditStatus": "PENDING",
|
||
"attachments": [
|
||
"https://oss.example.com/media/receipt.jpg"
|
||
],
|
||
"createdAt": "2026-06-22T10:35:00",
|
||
"updatedAt": "2026-06-22T10:35:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
> `auditStatus=PENDING` 表示微信回调尚未到达，属正常状态，客服可照常处理工单。
|
||
|
||
### 8.3 业务失败——工单不存在
|
||
|
||
```http
|
||
GET /v3/admin/aftersale/ticket/9999999999
|
||
Authorization: Bearer <admin-jwt>
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 581001,
|
||
"msg": "工单不存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 业务边界
|
||
|
||
**适用场景**：
|
||
- 客服查看任意用户提交的售后工单，可见机审状态
|
||
- 列表页可按 `auditStatus` 过滤（需前端实现过滤 UI，后端支持按此字段查询）
|
||
|
||
**特殊边界**：
|
||
- 历史工单（PR #4203 上线前创建）`auditStatus` 为 `null`，前端可展示为「-」或「已通过」
|
||
- `auditStatus=REJECTED` 仅为机审标记，不影响工单的正常流转，客服仍需手动处置
|
||
|
||
---
|
||
|
||
## 10. 修改前后对比
|
||
|
||
### 字段级对比（TicketAdminRespVO）
|
||
|
||
| 字段 | 变更前 | 变更后 |
|
||
|------|-------|-------|
|
||
| auditStatus | 不存在 | 新增，String，wx 内容安全机审状态 |
|
||
|
||
### 行为级对比
|
||
|
||
| 维度 | 变更前 | 变更后 |
|
||
|------|-------|-------|
|
||
| 机审可见性 | 无任何机审信息 | 管理后台可见用户提交内容的机审结论 |
|
||
|
||
---
|
||
|
||
## 11. 影响评估 / 回滚
|
||
|
||
| 维度 | 结论 |
|
||
|------|------|
|
||
| 破坏兼容性 | 否（出参新增字段，旧版忽略） |
|
||
| 前端同步上线 | 建议同步展示 auditStatus，辅助客服判断违规内容 |
|
||
| 回滚方案 | 后端回滚 PR #4203 即可，无数据损失风险 |
|
||
|
||
---
|
||
|
||
## 12. 注意事项
|
||
|
||
1. `auditStatus=REJECTED` 的工单，客服可参考机审结论处理，但系统不会自动关闭工单。
|
||
2. 历史工单 `auditStatus` 为 `null`，前端建议展示为「-」。
|
||
3. `MANUAL_REVIEW` 状态表示微信需要人工介入，平台客服可主动跟进或等待微信反馈。
|
||
|
||
---
|
||
|
||
## 13. 关联 / 联系人
|
||
|
||
- **Issue**：[https://git.1814.love:8443/wx/HL/issues/4196](https://git.1814.love:8443/wx/HL/issues/4196)
|
||
- **PR**：[https://git.1814.love:8443/wx/HL/pulls/4203](https://git.1814.love:8443/wx/HL/pulls/4203)
|
||
- **Commit**：[https://git.1814.love:8443/wx/HL/commit/8882eb1568a7e5ab8f48a6db4b7e3d4d4b6f2c15](https://git.1814.love:8443/wx/HL/commit/8882eb1568a7e5ab8f48a6db4b7e3d4d4b6f2c15)
|
||
- **关联 Issue**：[#4161 售后申诉中心](https://git.1814.love:8443/wx/HL/issues/4161)
|
||
- **后端负责人**：yaosutu
|