diff --git a/changelogs-v2/2026-06/22_申诉退款执行迁移售后工单-删除接口-管理后台.md b/changelogs-v2/2026-06/22_申诉退款执行迁移售后工单-删除接口-管理后台.md new file mode 100644 index 0000000..fdec1c7 --- /dev/null +++ b/changelogs-v2/2026-06/22_申诉退款执行迁移售后工单-删除接口-管理后台.md @@ -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 +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`