文档(aftersale+order/admin): 管理后台——售后工单机审auditStatus(#4196 PR#4203)+订单售后中展示aftersaleStatus(#4197 PR#4208)

2026-06-22 14:25:34 +08:00 · 2026-06-22 14:25:34 +08:00 · cbad66ecc7
--- a/changelogs-v2/2026-06/22_4196_售后工单机审-修改接口-管理后台.md
+++ b/changelogs-v2/2026-06/22_4196_售后工单机审-修改接口-管理后台.md
@ -0,0 +1,237 @@
+# 售后工单接入 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
--- a/changelogs-v2/2026-06/22_4197_订单售后中展示-修改接口-管理后台.md
+++ b/changelogs-v2/2026-06/22_4197_订单售后中展示-修改接口-管理后台.md
@ -0,0 +1,243 @@
+# 订单「售后中」展示激活（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