From 79906d032090e2a564e4d8ddce612e39d0536140 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Thu, 6 Aug 2026 15:42:12 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#5593=20=E5=8F=96=E6=B6=88?= =?UTF-8?q?=E6=B4=BE=E5=8D=95=E9=80=80=E4=BF=9D=E5=B9=82=E7=AD=89=E2=80=94?= =?UTF-8?q?=E2=80=94REFUND=5FCHECK=E7=8B=AC=E7=AB=8B=E7=B1=BB=E5=9E=8B+?= =?UTF-8?q?=E9=87=8D=E8=AF=95=E4=B8=8D=E8=B0=83=E4=BF=9D=E5=8F=B8+?= =?UTF-8?q?=E9=94=81=E7=9F=AD=E9=87=8D=E8=AF=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...独立类型+重试不调保司+任务锁短重试-修改接口-管理后台.md | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 changelogs-v2/2026-08/06_5593_取消派单退保幂等：退保检查任务独立类型+重试不调保司+任务锁短重试-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/06_5593_取消派单退保幂等：退保检查任务独立类型+重试不调保司+任务锁短重试-修改接口-管理后台.md b/changelogs-v2/2026-08/06_5593_取消派单退保幂等：退保检查任务独立类型+重试不调保司+任务锁短重试-修改接口-管理后台.md new file mode 100644 index 0000000..7683e10 --- /dev/null +++ b/changelogs-v2/2026-08/06_5593_取消派单退保幂等：退保检查任务独立类型+重试不调保司+任务锁短重试-修改接口-管理后台.md @@ -0,0 +1,70 @@ +--- +schema: "hl-changelog/v2" +ticket: "5593" +title: "取消派单退保幂等：退保检查任务独立类型+重试不调保司+任务锁短重试" +consumer: "admin" +author: "wx" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "@wx" +frontend_ref: "管理后台车务保险任务列表/筛选需适配 REFUND_CHECK（退保检查）类型" +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-06" +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//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 类型；接口字段结构不变