From a9185984e7f77c87eb1a119bb7777ea258becf44 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Mon, 22 Jun 2026 14:25:21 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3(aftersale/mp):=20=E5=94=AE?= =?UTF-8?q?=E5=90=8E=E5=B7=A5=E5=8D=95=E6=8E=A5=E5=85=A5wx=E6=9C=BA?= =?UTF-8?q?=E5=AE=A1=E2=80=94=E2=80=94=E5=B0=8F=E7=A8=8B=E5=BA=8F=E7=AB=AF?= =?UTF-8?q?=E5=85=A5=E5=8F=82=E6=96=B0=E5=A2=9EmediaTraceIds=EF=BC=8C?= =?UTF-8?q?=E5=87=BA=E5=8F=82=E6=96=B0=E5=A2=9EauditStatus=20(#4196=20PR#4?= =?UTF-8?q?203)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../22_4196_售后工单机审-修改接口-小程序端.md | 341 ++++++++++++++++++ 1 file changed, 341 insertions(+) create mode 100644 changelogs-v2-mp/2026-06/22_4196_售后工单机审-修改接口-小程序端.md diff --git a/changelogs-v2-mp/2026-06/22_4196_售后工单机审-修改接口-小程序端.md b/changelogs-v2-mp/2026-06/22_4196_售后工单机审-修改接口-小程序端.md new file mode 100644 index 0000000..44b4330 --- /dev/null +++ b/changelogs-v2-mp/2026-06/22_4196_售后工单机审-修改接口-小程序端.md @@ -0,0 +1,341 @@ +# 售后工单接入 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. 接口背景 + +用户在小程序发起售后工单（投诉/申诉）时，若附带图片或视频，前端需先通过微信内容安全 `msgSecCheck` 接口对媒体文件做内容审核，得到微信返回的 `traceId` 后，连同创建工单请求一并透传给后端。后端不直接调用微信安全接口，只存储 traceId，等待微信异步回调后更新审核状态。无图/无视频的工单跳过机审，直接置为 `APPROVED`。 + +--- + +## 2. 变更清单 + +| 变更类型 | 接口 | 字段 | 说明 | +|---------|------|------|------| +| ⚠️ 入参新增 | `POST /v3/mp/aftersale/ticket` | `mediaTraceIds` | 新增可选字段，机审 traceId 数组，最多 12 个 | +| ✨ 出参新增 | `GET /v3/mp/aftersale/ticket/{id}` | `auditStatus` | 工单 wx 内容安全机审状态 | +| ✨ 出参新增 | `GET /v3/mp/aftersale/ticket/list` | `auditStatus` | 工单列表每条记录新增机审状态 | + +--- + +## 3. 接口详情 + +### 3.1 发起售后工单 + +| 属性 | 值 | +|-----|-----| +| 方法 + 路径 | `POST /v3/mp/aftersale/ticket` | +| 接口描述 | 用户发起售后工单（投诉/申诉），支持附件 + 机审 traceId 透传 | +| 认证 | 需要用户 JWT（小程序登录 token） | +| 幂等性 | 非幂等，每次调用创建一条新工单 | +| 限流 | 无独立限流（受网关全局限流） | + +### 3.2 工单详情 + +| 属性 | 值 | +|-----|-----| +| 方法 + 路径 | `GET /v3/mp/aftersale/ticket/{id}` | +| 接口描述 | 获取单条售后工单详情 | +| 认证 | 需要用户 JWT，仅可查自己的工单 | +| 限流 | 无独立限流 | + +### 3.3 工单列表 + +| 属性 | 值 | +|-----|-----| +| 方法 + 路径 | `GET /v3/mp/aftersale/ticket/list` | +| 接口描述 | 查询当前用户的售后工单列表（分页） | +| 认证 | 需要用户 JWT | +| 限流 | 无独立限流 | + +--- + +## 4. 接口入参 + +### 4.1 路径参数 / Query 参数 + +`GET /v3/mp/aftersale/ticket/{id}` + +| 参数名 | 类型 | 必填 | 说明 | +|-------|------|------|------| +| id | Long | 是 | 工单 ID | + +### 4.2 请求体字段（POST /v3/mp/aftersale/ticket） + +| 字段名 | 类型 | 必填 | 校验 | 说明 | +|-------|------|------|------|------| +| orderId | Long | 是 | 不能为空 | 关联订单 ID | +| category | String | 是 | 枚举：COMPLAINT / APPEAL | 工单分类：投诉 / 申诉 | +| type | String | 是 | 枚举，见 §6 | 具体类型（如 HOTEL / GUIDE / PRICE） | +| title | String | 是 | max=100 | 工单标题 | +| description | String | 是 | max=2000 | 问题描述 | +| attachments | List\ | 否 | max=10 | 附件 URL 列表（图片/视频） | +| **mediaTraceIds** | **List\** | **否** | **max=12** | **微信内容安全 traceId 数组（前端透传，后端只存）** | + +> `mediaTraceIds` 与 `attachments` 一一对应关系由前端维护。后端不校验对应关系，仅存储用于异步机审回流。无附件时可不传或传空数组。 + +--- + +## 5. 出参字段 + +### TicketMpRespVO（工单详情/列表单条） + +| 字段名 | 类型 | 说明 | +|-------|------|------| +| 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 | 工单状态中文名 | +| canWithdraw | Boolean | 是否可撤回 | +| **auditStatus** | **String** | **wx 内容安全机审状态，取值见 §6** | +| attachments | List\ | 附件 URL | +| createdAt | String | 创建时间（ISO 8601） | +| updatedAt | String | 更新时间（ISO 8601） | + +--- + +## 6. 枚举 / 数据字典 + +### auditStatus — wx 内容安全机审状态 + +| 值 | 含义 | 触发条件 | +|----|------|---------| +| `PENDING` | 机审中 | 创建工单时有 mediaTraceIds（异步等待微信回调） | +| `APPROVED` | 已通过 | 无 mediaTraceIds 的工单直接置此（免审）；微信回调结果合规也置此 | +| `MANUAL_REVIEW` | 人工复审 | 微信机审认为需人工介入 | +| `REJECTED` | 已驳回 | 微信机审判定内容违规 | + +> **重要**：`PENDING` 状态为异步，工单创建成功后微信回调可能在数秒到数分钟内到达。前端建议在工单详情页轮询或基于页面刷新展示最新状态，不要把 `PENDING` 当作错误。 + +### category — 工单分类 + +| 值 | 含义 | +|----|------| +| `COMPLAINT` | 投诉 | +| `APPEAL` | 申诉 | + +--- + +## 7. 错误码 + +| 错误码 | HTTP 状态 | 含义 | 触发场景 | +|-------|---------|------|---------| +| 581001 | 400 | 工单关联订单不存在 | orderId 无效 | +| 581002 | 400 | 工单已存在，不可重复提交 | 同一订单同分类已有活跃工单 | +| 581003 | 400 | 订单状态不允许发起售后 | 订单未处于可售后状态 | +| 200-001 | 401 | 未授权 | JWT 缺失或过期 | +| 200-002 | 403 | 无权操作 | 工单不属于当前用户 | + +--- + +## 8. 示例 + +### 8.1 典型成功——带图片机审 + +**请求** +```http +POST /v3/mp/aftersale/ticket +Authorization: Bearer +Content-Type: application/json + +{ + "orderId": 1234567890, + "category": "COMPLAINT", + "type": "HOTEL", + "title": "酒店降级安排", + "description": "预订了四星酒店，实际安排了三星，差价未退。", + "attachments": [ + "https://oss.example.com/media/hotel_photo_1.jpg", + "https://oss.example.com/media/hotel_photo_2.jpg" + ], + "mediaTraceIds": [ + "trace_abc123def456", + "trace_xyz789uvw012" + ] +} +``` + +**响应** +```json +{ + "code": 200, + "msg": "success", + "data": { + "id": 987654321, + "orderId": 1234567890, + "orderNo": "HL20260622001", + "category": "COMPLAINT", + "type": "HOTEL", + "title": "酒店降级安排", + "description": "预订了四星酒店，实际安排了三星，差价未退。", + "status": "SUBMITTED", + "statusName": "已提交", + "canWithdraw": true, + "auditStatus": "PENDING", + "attachments": [ + "https://oss.example.com/media/hotel_photo_1.jpg", + "https://oss.example.com/media/hotel_photo_2.jpg" + ], + "createdAt": "2026-06-22T10:30:00", + "updatedAt": "2026-06-22T10:30:00" + } +} +``` + +> `auditStatus` 初始为 `PENDING`，等待微信异步回调后更新为 `APPROVED` / `MANUAL_REVIEW` / `REJECTED`。 + +### 8.2 边界情况——无附件工单（直接 APPROVED） + +**请求** +```http +POST /v3/mp/aftersale/ticket +Authorization: Bearer +Content-Type: application/json + +{ + "orderId": 1234567890, + "category": "APPEAL", + "type": "PRICE", + "title": "价格异议", + "description": "行程中临时要求加收费用，合同未约定。", + "attachments": [], + "mediaTraceIds": [] +} +``` + +**响应** +```json +{ + "code": 200, + "msg": "success", + "data": { + "id": 987654322, + "orderId": 1234567890, + "orderNo": "HL20260622001", + "category": "APPEAL", + "type": "PRICE", + "title": "价格异议", + "description": "行程中临时要求加收费用，合同未约定。", + "status": "SUBMITTED", + "statusName": "已提交", + "canWithdraw": true, + "auditStatus": "APPROVED", + "attachments": [], + "createdAt": "2026-06-22T10:35:00", + "updatedAt": "2026-06-22T10:35:00" + } +} +``` + +> 无 mediaTraceIds 或传空数组时，`auditStatus` 直接为 `APPROVED`，无需等待回调。 + +### 8.3 业务失败——订单已有活跃工单 + +**请求**（同一订单同分类已存在未关闭工单） +```http +POST /v3/mp/aftersale/ticket +Authorization: Bearer +Content-Type: application/json + +{ + "orderId": 1234567890, + "category": "COMPLAINT", + "type": "GUIDE", + "title": "导游服务差", + "description": "导游态度恶劣。", + "mediaTraceIds": [] +} +``` + +**响应** +```json +{ + "code": 581002, + "msg": "工单已存在，不可重复提交", + "data": null +} +``` + +--- + +## 9. 业务边界 + +**适用场景**： +- 订单处于可售后状态（已出行、出行中、已完成等，具体由后端校验） +- 有图片/视频附件时前端必须先完成 `wx.msgSecCheck` 得到 traceId 再调此接口 +- 无附件或不需要机审时，`mediaTraceIds` 可省略或传空数组 + +**不适用场景**： +- 已取消订单不可发起售后 +- 同一订单同分类已有活跃（非 CLOSED/WITHDRAWN）工单时，不可重复发起 + +**特殊边界**： +- `mediaTraceIds` 最多 12 个，超出返回参数校验错误 +- `auditStatus` 为 `PENDING` 时工单照常流转（客服可正常处理），机审结果不阻塞工单流程 +- `auditStatus` 为 `REJECTED` 时，仅作展示标记，工单处理流程由客服决定是否关闭 + +--- + +## 10. 修改前后对比 + +### 字段级对比 + +**CreateTicketReqVO（入参）** + +| 字段 | 变更前 | 变更后 | +|------|-------|-------| +| mediaTraceIds | 不存在 | 新增，List\，可选，max=12 | + +**TicketMpRespVO（出参）** + +| 字段 | 变更前 | 变更后 | +|------|-------|-------| +| auditStatus | 不存在 | 新增，String，wx 机审状态 | + +### 行为级对比 + +| 场景 | 变更前 | 变更后 | +|------|-------|-------| +| 带图片发起工单 | 无机审，无审核状态 | 存 traceId，初始 auditStatus=PENDING，微信异步回调更新 | +| 无图片发起工单 | 无机审状态字段 | auditStatus 直接置 APPROVED | + +--- + +## 11. 影响评估 / 回滚 + +| 维度 | 结论 | +|------|------| +| 破坏兼容性 | 否（入参新增可选字段，旧版不传兼容；出参新增字段，旧版忽略） | +| 前端同步上线 | 建议同步：入参传 mediaTraceIds 发挥机审能力；出参展示 auditStatus | +| 回滚方案 | 后端回滚 PR #4203 即可，无 DDL 数据损失风险（DDL 只加列不删） | + +--- + +## 12. 注意事项 + +1. `mediaTraceIds` 由前端在调用微信 `wx.msgSecCheck` 后获得，后端不直接调微信安全接口，只做存储和转发。 +2. `auditStatus=PENDING` 是异步状态，不代表工单异常，客服后台可正常处理。 +3. 历史工单（此 PR 上线前创建的）`auditStatus` 字段为 `null`，前端展示时建议视 `null` 等同于 `APPROVED` 处理。 +4. 微信机审结果 `REJECTED` 不自动关闭工单，仅打标记，由客服决定后续处理。 + +--- + +## 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