gaoluyang
2026-11-05 d39e4f7d839167c16425086dfa2f8747bccfdff9
docs/aftersales_frontend_integration.md
@@ -6,28 +6,28 @@
|------|---------|------|
| 售后工单列表 | `/aftersales/ticket` | 工单列表、搜索、状态筛选 |
| 售后工单详情/编辑 | `/aftersales/ticket/detail?id=:id` | 新建/编辑工单、查看详情 |
| 退货申请列表 | `/aftersales/return` | 退货申请列表、搜索 |
| 退货申请详情 | `/aftersales/return/detail?id=:id` | 退货详情、审核操作 |
> 退货申请页面已下线,退货统一由仓储物流模块发起;售后工单只保留退货状态联动。
## 业务流程与数据带入
### 流程一:一般问题工单
```
创建工单 → 分配处理人 → 问题判定(一般问题)→ 处理 → 完结 → 关闭
创建工单(必选处理人,直接进入处理中)→ 问题判定(一般问题)→ 处理 → 完结 → 关闭
```
### 流程二:退货问题工单
```
创建工单 → 分配处理人 → 问题判定(退货问题)
  → 创建退货申请 → 销售审核 → [MES退货流程自动执行] → 退款/换货完成 → 完结 → 关闭
创建工单(必选处理人,直接进入处理中)→ 问题判定(退货问题)
  → 仓储物流发起销售退货 → 销售审核 → [MES退货流程自动执行] → 退款/换货完成 → 完结 → 关闭
```
### 流程三:维修问题工单
```
创建工单 → 分配处理人 → 问题判定(维修问题)
创建工单(必选处理人,直接进入处理中)→ 问题判定(维修问题)
  → 创建维修记录 → 维修完成 → 完结 → 关闭
```
@@ -53,11 +53,10 @@
| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/aftersales/ticket/create` | `aftersales:ticket:create` | 创建工单 |
| PUT | `/aftersales/ticket/update` | `aftersales:ticket:update` | 更新工单(仅草稿状态可更新) |
| PUT | `/aftersales/ticket/update` | `aftersales:ticket:update` | 更新工单(草稿/处理中状态可更新) |
| DELETE | `/aftersales/ticket/delete` | `aftersales:ticket:delete` | 删除工单(仅草稿/已取消状态可删除) |
| GET | `/aftersales/ticket/get` | `aftersales:ticket:query` | 获取工单详情 |
| GET | `/aftersales/ticket/page` | `aftersales:ticket:query` | 分页查询工单 |
| POST | `/aftersales/ticket/assign` | `aftersales:ticket:update` | 分配处理人 |
| POST | `/aftersales/ticket/classify` | `aftersales:ticket:update` | 问题判定 |
| PUT | `/aftersales/ticket/resolve` | `aftersales:ticket:update` | 完结工单 |
| PUT | `/aftersales/ticket/close` | `aftersales:ticket:update` | 关闭工单 |
@@ -128,7 +127,7 @@
#### 1.2 更新工单 `PUT /aftersales/ticket/update`
请求参数与创建相同,额外需要 `id` 字段。仅草稿状态可更新。
请求参数与创建相同,额外需要 `id` 字段。仅草稿或处理中状态可更新。
#### 1.3 删除工单 `DELETE /aftersales/ticket/delete`
@@ -251,16 +250,7 @@
**注意:** 分页列表响应中的每条记录结构与详情接口一致(含 `items` 和关联名称字段),但列表场景下 `items` 可为空。
#### 1.6 分配处理人 `POST /aftersales/ticket/assign`
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 工单编号(Query 参数) |
| handlerUserId | Long | 是 | 处理人用户编号(Query 参数) |
**业务规则:** 仅草稿、处理中状态可分配。分配后状态自动变为"处理中"。
#### 1.7 问题判定 `POST /aftersales/ticket/classify`
#### 1.6 问题判定 `POST /aftersales/ticket/classify`
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
@@ -269,7 +259,7 @@
| issueCategory | String | 否 | 问题分类(如"外观缺陷"、"功能故障"等) |
| severityLevel | Integer | 否 | 严重程度:0-轻微 1-一般 2-严重 3-致命 |
**业务规则:** 仅处理中状态可判定。判定为退货问题后,应引导用户创建退货申请。
**业务规则:** 仅处理中状态可判定。判定为退货问题后,由仓储物流模块发起销售退货。
#### 1.8 完结工单 `PUT /aftersales/ticket/resolve`
@@ -432,7 +422,7 @@
| 值 | 名称 | 说明 |
|----|------|------|
| 0 | 草稿 | 可编辑、可删除、可取消 |
| 10 | 处理中 | 可分配、可判定、可取消 |
| 10 | 处理中 | 可编辑、可判定、可完结、可取消 |
| 30 | 待退货 | 退货流程进行中 |
| 40 | 待退款/换货 | 等待退款或换货完成 |
| 50 | 已完结 | 可关闭 |
@@ -525,7 +515,7 @@
| issueDescription | 基本信息 | 问题描述 |
| severityLevel | 基本信息 | 严重程度(判定后显示) |
| ownerUserId / ownerUserName | 基本信息 | 负责人(创建时自动设为当前用户) |
| handlerUserId / handlerUserName | 基本信息 | 处理人(分配后显示) |
| handlerUserId / handlerUserName | 基本信息 | 处理人(新增时必选,创建后显示) |
| returnId | 基本信息 | 关联退货申请(可点击跳转) |
| repairId | 基本信息 | 关联维修记录(可点击跳转) |
| resolvedTime | 基本信息 | 解决时间(完结后显示) |
@@ -580,21 +570,12 @@
| 操作 | 草稿(0) | 处理中(10) | 待退货(30) | 待退款(40) | 已完结(50) | 已关闭(60) | 已取消(99) |
|------|---------|------------|------------|------------|------------|------------|------------|
| 编辑 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 编辑 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 删除 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| 分配处理人 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 问题判定 | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 创建退货申请 | ❌ | ✅(判定为退货后) | ❌ | ❌ | ❌ | ❌ | ❌ |
| 完结 | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| 关闭 | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| 取消 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
### 退货申请操作按钮显隐规则
| 操作 | 草稿(0) | 审核中(10) | 已同步MES(20) | 检验中(30) | 检验完成(40) | 已入库(50) | 退款完成(60) |
|------|---------|------------|---------------|------------|--------------|------------|--------------|
| 审核通过 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 查看详情 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
### 分页查询数据权限说明
@@ -628,7 +609,7 @@
1. **明细行更新策略**:更新工单时,明细行采用"先删后增"策略,前端必须传入完整的明细行列表(包括未修改的行),否则会导致明细行丢失。
2. **单号生成**:工单单号(AS前缀)和退货单号(RT前缀)由后端自动生成,前端不需要传入。
3. **状态流转**:所有状态变更操作(分配、判定、完结、关闭、取消、审核)后端都会校验当前状态是否允许,前端应根据按钮显隐规则控制操作入口。
3. **状态流转**:所有状态变更操作(判定、完结、关闭、取消、审核)后端都会校验当前状态是否允许,前端应根据按钮显隐规则控制操作入口。
4. **退货审核后自动同步 MES**:审核通过退货申请后,后端自动调用 MES 创建销售退货单,后续 MES 流程(质检→入库→退款)由回调自动推进状态,前端只需轮询刷新查看最新状态。
5. **数据带入**:创建退货申请时,必须从工单详情页跳转并带入 `ticketId`、`customerId`、`saleOrderId` 以及工单明细行中标记为"需要退货"的行。
6. **权限控制**:所有接口都有 `@PreAuthorize` 权限校验,前端菜单和按钮需要对应配置权限标识。