hl-api-changelog/changelogs-v2/2026-06/22_4196_售后工单机审-修改接口-管理后台.md

售后工单接入 wx 内容安全机审 — 修改接口（管理后台）

• 端类型：管理后台
• 日期：2026-06-22
• Issue：#4196
• PR：#4203
• Commit：8882eb156
• 后端负责人：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 典型成功——查询已通过机审的工单详情

请求

GET /v3/admin/aftersale/ticket/987654321
Authorization: Bearer <admin-jwt>

响应

{
  "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）的工单

{
  "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 业务失败——工单不存在

GET /v3/admin/aftersale/ticket/9999999999
Authorization: Bearer <admin-jwt>

{
  "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
• PR：https://git.1814.love:8443/wx/HL/pulls/4203
• Commit：https://git.1814.love:8443/wx/HL/commit/8882eb1568a7e5ab8f48a6db4b7e3d4d4b6f2c15
• 关联 Issue：#4161 售后申诉中心
• 后端负责人：yaosutu