docs(v2/aftersale): v2 申诉退款 execute-appeal 接口废弃 → 迁移至 v3 售后工单 resolve
v2 PUT /order/refund/{id}/execute-appeal 在 v3 不存在（404）
新流程：POST /v3/admin/aftersale/ticket/{id}/resolve 处置时核定金额，OA 通过后自动退款
关联 Issue #4161
这个提交包含在：
yaosutu
父节点
56c5498167
当前提交
df6bee83b8
@ -0,0 +1,229 @@
|
||||
# 申诉退款执行接口废弃 → 迁移至售后工单流程
|
||||
|
||||
- **日期**：2026-06-22
|
||||
- **变更类型**：删除接口 ⚠️
|
||||
- **端类型**：管理后台
|
||||
- **后端负责人**：腰苏图
|
||||
|
||||
---
|
||||
|
||||
## 1. 接口背景
|
||||
|
||||
v2 退款申诉流程在 refund 域有一个独立的「手动执行退款」步骤：企微 OA 申诉审批通过后，管理员还需要手动调用 execute-appeal 接口并填写实退金额，才会真正触发微信退款。
|
||||
|
||||
v3 将「退款申诉」整体迁移至**售后工单中心**（com.hulalv.aftersale），并把「两步（OA 通过 + 手动执行）」改为「一步（处置时核定金额，OA 通过后系统自动退款）」。因此 v2 的 execute-appeal 接口在 v3 **不存在**。
|
||||
|
||||
---
|
||||
|
||||
## 2. 变更清单
|
||||
|
||||
| 变更类型 | 接口 | 说明 |
|
||||
|---|---|---|
|
||||
| ⚠️ 删除 | `PUT /order/refund/{applicationId}/execute-appeal` | v3 无此接口，调用返回 404 |
|
||||
| ✨ 替代 | `POST /v3/admin/aftersale/ticket/{id}/resolve` | 处置工单并核定金额，OA 通过后自动退款 |
|
||||
| ✨ 新增 | `POST /v3/admin/aftersale/ticket/{id}/process` | 受理申诉工单（SUBMITTED→PROCESSING） |
|
||||
| ✨ 查询 | `GET /v3/admin/aftersale/ticket/page` | 申诉工单分页列表 |
|
||||
| ✨ 查询 | `GET /v3/admin/aftersale/ticket/{id}` | 申诉工单详情 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 废弃接口明细
|
||||
|
||||
### PUT /order/refund/{applicationId}/execute-appeal（v2，已删除）
|
||||
|
||||
**⚠️ 此接口在 v3 不存在，调用将返回 404。**
|
||||
|
||||
- **v2 路径**：`PUT /order/refund/{applicationId}/execute-appeal`
|
||||
- **v2 查询参数**：
|
||||
- `actualAmount`（BigDecimal，必填）：管理员手填的实际退款金额
|
||||
- `remark`（String，选填）：备注
|
||||
- **v2 语义**：企微 OA 申诉审批通过后，状态置为 `APPEAL_APPROVED`（此时还没退钱），管理员再调此接口填写 actualAmount，才触发微信退款。这是 OA 通过后的独立手动执行步。
|
||||
|
||||
---
|
||||
|
||||
## 4. 为什么没有了
|
||||
|
||||
v3 申诉流程整体迁入售后工单中心，执行模型发生了根本性变化：
|
||||
|
||||
| 维度 | v2 | v3 |
|
||||
|---|---|---|
|
||||
| 金额确认时机 | OA 通过后手动填 actualAmount | 处置时就填 resolutionAmount（OA 提交前确定） |
|
||||
| 退款触发方式 | 管理员手动调 execute-appeal | OA 通过后系统自动触发 |
|
||||
| 申诉入口 | refund 域独立接口 | 售后工单中心（菜单：售后 → 申诉） |
|
||||
|
||||
因为退款触发已经自动化，所以不再需要独立的手动执行接口。
|
||||
|
||||
---
|
||||
|
||||
## 5. 迁移指引：v3 申诉退款完整链路
|
||||
|
||||
> 以下是管理后台视角的完整操作步骤，对应 v2 的整个申诉退款流程。
|
||||
|
||||
| 步骤 | v3 接口 | 方法 | 说明 |
|
||||
|---|---|---|---|
|
||||
| ① 发起申诉（用户侧） | `POST /v3/mp/aftersale/ticket` | POST | C 端用户发起，category=APPEAL，type=REFUND_REJECTED 或 REFUND_AMOUNT_DISPUTE，targetRefId=关联退款申请 ID |
|
||||
| ② 受理工单 | `POST /v3/admin/aftersale/ticket/{id}/process` | POST | 工单状态 SUBMITTED→PROCESSING，可设 assigneeId/remark |
|
||||
| ③ 处置工单（核定金额） | `POST /v3/admin/aftersale/ticket/{id}/resolve` | POST | **对应 v2 的 execute-appeal**，填 decision=APPROVE、resolutionType=REFUND、resolutionAmount=核定金额，系统自动提企微 OA |
|
||||
| ④ 退款自动执行 | 无需调接口 | — | 企微 OA 审批通过后，系统自动触发微信退款，无手动执行步 |
|
||||
|
||||
**核心对应关系**：
|
||||
|
||||
```
|
||||
v2：PUT /order/refund/{id}/execute-appeal?actualAmount=500.00&remark=同意退差价
|
||||
|
||||
v3：POST /v3/admin/aftersale/ticket/{id}/resolve
|
||||
{ "decision":"APPROVE", "resolutionType":"REFUND", "resolutionAmount":500.00, "remark":"同意退差价" }
|
||||
→ OA 通过后自动退款，无额外操作
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. resolve 接口入参字段表
|
||||
|
||||
**接口**：`POST /v3/admin/aftersale/ticket/{id}/resolve`
|
||||
**认证**：JWT（管理后台 Token）
|
||||
**路径参数**：`id`（Long，工单 ID）
|
||||
|
||||
**请求体（ResolveTicketReqVO）**：
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| decision | String | 必填 | 处置决定：`APPROVE`（同意）/ `REJECT`（驳回） |
|
||||
| resolutionType | String | APPROVE 时必填 | 处置方式：`REFUND`（退款）/ `RECTIFY`（整改）/ `REJECT`（维持原决定） |
|
||||
| resolutionAmount | BigDecimal | resolutionType=REFUND 时必填 | 后台核定退款金额，≥0，是退款的唯一金额依据（对应 v2 的 actualAmount） |
|
||||
| remark | String | 选填 | 处置说明，建议填写核定原因 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 错误码
|
||||
|
||||
| 错误码 | 含义 | 场景 |
|
||||
|---|---|---|
|
||||
| 旧接口 404 | v2 路径已下线 | 调用 `/order/refund/*/execute-appeal` |
|
||||
| 工单相关错误码 | 见售后工单 changelog（Issue #4161） | 工单状态非法、金额超可退余额等 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 示例
|
||||
|
||||
### 8.1 典型成功（同意退款 500 元）
|
||||
|
||||
**v3 新调用**：
|
||||
```http
|
||||
POST /v3/admin/aftersale/ticket/9001/resolve
|
||||
Authorization: Bearer <admin-token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"decision": "APPROVE",
|
||||
"resolutionType": "REFUND",
|
||||
"resolutionAmount": 500.00,
|
||||
"remark": "经核实酒店降级，同意退差价¥500"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": null,
|
||||
"msg": "success"
|
||||
}
|
||||
```
|
||||
|
||||
OA 通过后系统自动触发微信退款，无需再调任何接口。
|
||||
|
||||
### 8.2 边界情况（金额为 0，驳回申诉）
|
||||
|
||||
```http
|
||||
POST /v3/admin/aftersale/ticket/9002/resolve
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"decision": "REJECT",
|
||||
"remark": "经核实服务已按合同履行，驳回申诉"
|
||||
}
|
||||
```
|
||||
|
||||
decision=REJECT 时 resolutionType 和 resolutionAmount 可不填。
|
||||
|
||||
### 8.3 v2 旧接口调用（已失效，返回 404）
|
||||
|
||||
```http
|
||||
PUT /order/refund/8001/execute-appeal?actualAmount=500.00&remark=同意退差价
|
||||
```
|
||||
|
||||
```json
|
||||
404 Not Found
|
||||
（v3 此路径不存在，请迁移至 /v3/admin/aftersale/ticket/{id}/resolve）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 业务边界
|
||||
|
||||
**适用**：
|
||||
- 用户已通过 C 端（或客服代客）发起了申诉工单
|
||||
- 工单处于 PROCESSING 状态（已受理）
|
||||
- resolutionAmount ≤ 订单可退余额（由 resolve 接口前置校验）
|
||||
|
||||
**不适用**：
|
||||
- 工单尚未受理（SUBMITTED 状态），需先调 process 接口受理
|
||||
- 工单已处置（RESOLVED/CLOSED），不可重复 resolve
|
||||
- resolutionType=REFUND 但不传 resolutionAmount（接口拒绝）
|
||||
|
||||
**特殊边界**：
|
||||
- resolutionAmount 与用户诉求金额 claimAmount 是双金额模型，后台核定金额由管理员独立决定，不受用户填写的 claimAmount 约束（与 v2 actualAmount 语义一致）
|
||||
- 退款超额/累计校验在 refund 域兜底，resolve 时工单层也预检可退余额，两层校验
|
||||
|
||||
---
|
||||
|
||||
## 10. 修改前后对比
|
||||
|
||||
### 流程对比
|
||||
|
||||
| 阶段 | v2 流程 | v3 流程 |
|
||||
|---|---|---|
|
||||
| 用户发起申诉 | 调退款申诉接口（refund 域） | 创建售后工单（aftersale 域），category=APPEAL |
|
||||
| 管理员受理 | 无独立受理步骤 | `POST /v3/admin/aftersale/ticket/{id}/process` |
|
||||
| 核定金额 + 提 OA | 单独的 OA 提交步骤（金额 OA 通过后才填） | `POST /v3/admin/aftersale/ticket/{id}/resolve`（处置时即填金额，系统自动提 OA） |
|
||||
| 执行退款 | **管理员手动调 execute-appeal** | OA 通过后**系统自动退款** |
|
||||
|
||||
### 字段对比
|
||||
|
||||
| v2 字段 | v2 语义 | v3 字段 | v3 语义 |
|
||||
|---|---|---|---|
|
||||
| `actualAmount`（query param） | OA 通过后手填实退金额 | `resolutionAmount`（请求体） | 处置时预填核定金额，OA 通过后直接用 |
|
||||
| `remark`（query param） | 执行备注 | `remark`（请求体） | 处置说明 |
|
||||
| 无 | — | `decision` | APPROVE/REJECT，明确处置决定 |
|
||||
| 无 | — | `resolutionType` | REFUND/RECTIFY/REJECT，明确处置方式 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 影响评估 / 回滚
|
||||
|
||||
**破坏兼容**：是。v2 execute-appeal 路径在 v3 不存在，直接 404。
|
||||
|
||||
**前端同步事项**：
|
||||
1. 删除调用 `PUT /order/refund/{id}/execute-appeal` 的代码
|
||||
2. 在售后工单详情页接入 `POST /v3/admin/aftersale/ticket/{id}/resolve` 替代
|
||||
3. 售后工单列表/详情见 Issue #4161 的 changelog（changelogs-v2/2026-06/22_4161_售后申诉中心-新增接口-管理后台.md）
|
||||
|
||||
**回滚方案**：如需临时降级，可在前端继续调 v2 的 execute-appeal（v2 服务 hl-order-service-v2 端口 8094 仍在运行）；v3 no rollback，此接口不会补建。
|
||||
|
||||
---
|
||||
|
||||
## 12. 注意事项
|
||||
|
||||
- `resolutionAmount` 是退款的唯一金额依据，一旦 OA 通过无法修改，请管理员在处置时确认准确金额再提交。
|
||||
- resolve 之后工单进入「待 OA 审批」状态，此时工单不可取消、不可重新处置；如需修改金额，需先联系技术撤回 OA 流程（当前无前端入口）。
|
||||
- 售后工单中心同时承载「投诉」和「申诉」两种类型，查询时注意用 `category=APPEAL` 过滤，避免与投诉工单混淆。
|
||||
- v3 申诉工单的发起方是 C 端用户（`/v3/mp/aftersale/ticket`），管理后台只有受理和处置权限，不能代客创建 APPEAL 类型工单（仅 COMPLAINT 类型支持管理端代客）。
|
||||
|
||||
---
|
||||
|
||||
## 13. 关联 / 联系人
|
||||
|
||||
- **关联 Issue**：https://git.1814.love:8443/wx/HL/issues/4161（售后申诉中心上线）
|
||||
- **v2 原接口 PR**：历史遗留，无单独 PR 记录
|
||||
- **后端负责人**：腰苏图（@yaosutu）
|
||||
- **售后工单 changelog 参考**：`changelogs-v2/2026-06/22_4161_售后申诉中心-新增接口-管理后台.md`
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户