---
schema: "hl-changelog/v2"
ticket: "5593"
title: "取消派单退保幂等：退保检查任务独立类型+重试不调保司+任务锁短重试"
consumer: "admin"
author: "wx"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "mmg"
frontend_ref: "hl-admin@2b2dedfe65aea63746b62de5188f82630461cc80"
target_release: ""
verified_at: "2026-08-06"
status_note: "后端完成：PR #5605 合并 dev-v3（ef5199207）并部署 TEST；网关实测取消派单退保幂等——每保单仅 1 条 REFUND 明细（同保单不重复退保）、REFUND_CHECK 独立类型（退保检查）逐服务日收敛、taskType=REFUND 筛选不再混入检查任务。前端需在任务列表/筛选/详情展示 REFUND_CHECK（退保检查）类型标签。"
updated_at: "2026-08-07"
base: "dev-v3"
generated: "2026-08-06T15:40:15+08:00"
---

# 取消派单退保幂等：退保检查任务独立类型+重试不调保司+任务锁短重试

> 服务端已部署 TEST 并网关验证；前端展示适配项见"前端/调用方动作"。

## 关联 / 联系人

### 链接

- **Issue**: [#5593](https://git.1814.love:8443/wx/HL/issues/5593)
- **PR**: [#5605](https://git.1814.love:8443/wx/HL/pulls/5605)
- **Merge commit**: [ef5199207](https://git.1814.love:8443/wx/HL/commit/ef5199207)

### 联系人

- **后端负责人**: @wx

## 变更接口

| 方法 | 路径 | 来源 | 变更 |
|---|---|---|---|
| `GET` | `/admin/fleet/insurance/tasks` | `FleetInsuranceTaskController`（fleet） | 查询参数 `taskType` 新增取值 `REFUND_CHECK`（退保检查）；`taskType=REFUND` 只返回真实调保司退保的明细任务，不再混入 REFUND_CHECK 汇总任务 |
| `POST` | `/admin/fleet/insurance/tasks/<taskId>/retry` | `FleetInsuranceTaskController`（fleet） | 语义变更：`REFUND_CHECK` 类型任务重试只收敛服务日退保检查结论，**绝不调用保司退保**（修复前 REFUND_CHECK 任务复用 REFUND 类型，重试会走退保逻辑） |

## 契约影响文件

- `hl-fleet-service/src/main/java/com/hulalv/fleet/insurance/enums/FleetInsuranceTaskTypeEnum.java`（新增 `REFUND_CHECK("REFUND_CHECK","退保检查")`）
- `hl-fleet-service/src/main/java/com/hulalv/fleet/insurance/vo/FleetInsuranceTaskPageReqVO.java`（taskType 枚举校验 + REFUND_CHECK）
- `hl-fleet-service/src/main/java/com/hulalv/fleet/insurance/FleetInsuranceTaskService.java`（REFUND_CHECK 构造按 bizKey 前缀自动解析类型；retryRefundCheck 不调保司；tryLockTask 瞬时锁竞争短重试 500ms×1）

## 根因与修复说明

- 取消派单同保单出现"2 条 REFUND 都 SUCCESS"：其中 1 条是 **REFUND_CHECK 逐服务日退保检查汇总**（纯本地收敛、不调保司），因任务类型枚举只有 PURCHASE/REFUND，检查任务 taskType 复用 REFUND，管理端按 taskType=REFUND 查询同保单出现 2 条 → 重复退保观感；**保游侧实际只退 1 次**（cancel 仅在 REFUND 明细执行）
- 潜在真重复源：REFUND_CHECK 任务被人工重试时旧代码走 `retryRefund` 会调保司退保——已修复（检查任务重试只收敛不调保司）
- 附带：司机险任务锁瞬时竞争导致的"任务锁暂不可用"PENDING 积压——`tryLockTask` 获取失败后短等待 500ms 重试一次

## 前端/调用方动作

1. **任务列表类型展示**：`taskTypeLabel` 新增"退保检查"（REFUND_CHECK），任务列表/详情可区分"退保"（REFUND 明细）与"退保检查"（REFUND_CHECK 汇总），避免同保单重复退保观感
2. **类型筛选**：任务筛选器 taskType 可选值增加 `REFUND_CHECK`；`REFUND` 筛选现在只返回真实退保明细（历史 REFUND_CHECK 任务仍为 REFUND 老值，属存量数据不迁移）
3. **重试按钮**：REFUND_CHECK 任务可重试（只收敛检查结论，不会触发退保）；提示文案建议区分"重试退保"与"重试退保检查"

## 验证证据

- 定向测试：FleetInsuranceTaskServiceTest 139/139（+3：REFUND_CHECK 重试收敛不调保司 / 明细缺失保持待处理 / 服务日有效派单拒绝重试）、FleetInsuranceTaskControllerTest 13/13、AssignmentInsuranceOutboxProcessorTest 44/44；fleet 全量 verify BUILD SUCCESS（含 spotless，10:54 min）
- 网关验证（TEST，海日汗 perTrip 2085268464900960257 取消）：
  - 取消后每保单仅 **1 条 REFUND 明细**（08-20 保单 2085268465328758786、08-23 保单 2085268539798626306 各 1 条，均 SUCCESS 且保单 CANCELLED）——同保单不重复退保
  - **REFUND_CHECK（退保检查）独立类型**逐服务日 4 条（08-20~23）全部 SUCCESS（有保单日"全部退保明细已成功"、无保单日"无需退保"）
  - `taskType=REFUND` 筛选只返回 2 条明细（不再混入检查任务）；`taskType=REFUND_CHECK` 筛选返回 4 条检查任务
  - 已取消派单重复取消被状态机拒绝（605020）
- 兼容性结论：历史 REFUND_CHECK 任务（taskType 存量 REFUND）不迁移，仅在列表中显示原"退保"标签；新产生任务使用 REFUND_CHECK 类型；接口字段结构不变