From 31e2bc4fec36c161969ccc002fdff79e99d6ee87 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Mon, 6 Jul 2026 09:32:59 +0800
Subject: [PATCH] docs: add fleet insurance API handoff

---
 ...¦åŠ¡è�œå�•å…¨æŽ¥å�£éªŒæ”¶ä¸Žå‰�端契约收å�£-管ç�†å�Žå�°.md |   8 +-
 ...¸æœºé™©è‡ªåŠ¨æŠ•é€€ä¿�闭环与ä¿�险è�œå�•å¥‘约-管ç�†å�Žå�°.md | 318 ++++++++++++++++++
 2 files changed, 322 insertions(+), 4 deletions(-)
 create mode 100644 changelogs-v2/2026-07/26_4760_车务�机险自动投退�闭环与�险��契约-管���.md

diff --git a/changelogs-v2/2026-07/25_4756_车务��全接�验收与�端契约收�-管���.md b/changelogs-v2/2026-07/25_4756_车务��全接�验收与�端契约收�-管���.md
index a4fac82..6d936ce 100644
--- a/changelogs-v2/2026-07/25_4756_车务��全接�验收与�端契约收�-管���.md
+++ b/changelogs-v2/2026-07/25_4756_车务��全接�验收与�端契约收�-管���.md
@@ -22,7 +22,7 @@
 | 场景 | �端处� |
 |------|----------|
 | 当�角色 | 车务���能由 `VEHICLE_MANAGER` 或 `SUPER_ADMIN` 访问；`wx/CUSTOMIZER` 访问 `/admin/fleet/**` 返回 `403`，�示切�车务角色。 |
-| �机结算方� | �机新增/编辑/导入使用字典 `driver_settlement_mode`：`direct`=直接结算，`fleet_leader`=车队长结算。 |
+| �机结算方� | �机新增/编辑/导入使用字典 `driver_settlement_mode`：`direct`=直接结算，`captain`=车队长结算。 |
 | 待审核详情 ID | `GET /admin/fleet/drivers/pending/{pendingId}` �应主键字段是 `id`，�是 `pendingId`；路径���� `pendingId`。 |
 | 派���确认 | `POST /admin/fleet/assignments/{assignmentId}/confirm` ��许 `holding -> assigned`；� `holding` 返回 `605020`。 |
 | �消���作 | 终�派��次�消也返回 `605020`。 |
@@ -737,7 +737,7 @@ PUT /admin/fleet/drivers/{driverId}
   "preferredTypeKey": "suv",
   "preferredModel": "SUV",
   "vehicleSource": "company",
-  "settlementMode": "fleet_leader",
+  "settlementMode": "captain",
   "license": {
     "no": "L6966520260705",
     "type": "C1",
@@ -762,7 +762,7 @@ PUT /admin/fleet/drivers/{driverId}
     "phone": "199****9999",
     "driverStatus": "idle",
     "season": "active",
-    "settlementMode": "fleet_leader",
+    "settlementMode": "captain",
     "license": { "no": "L6966520260705", "type": "C1", "expire": "2035-12-31" },
     "insurance": { "type": "none" },
     "tags": ["API_TEST_FLEET_FULL"]
@@ -775,7 +775,7 @@ PUT /admin/fleet/drivers/{driverId}
 | 值 | 展示 |
 |----|------|
 | `direct` | 直接结算 |
-| `fleet_leader` | 车队长结算 |
+| `captain` | 车队长结算 |
 
 �法值�应：
 
diff --git a/changelogs-v2/2026-07/26_4760_车务�机险自动投退�闭环与�险��契约-管���.md b/changelogs-v2/2026-07/26_4760_车务�机险自动投退�闭环与�险��契约-管���.md
new file mode 100644
index 0000000..a100400
--- /dev/null
+++ b/changelogs-v2/2026-07/26_4760_车务�机险自动投退�闭环与�险��契约-管���.md
@@ -0,0 +1,318 @@
+# ��端对接·管���】车务�机险自动投退�闭环与�险��契约
+
+> **Issue**: [wx/HL#4760](https://git.1814.love:8443/wx/HL/issues/4760)
+> **�务**: hl-fleet-service + hl-order-service-v3 insurance Feign
+> **日期**: 2026-07-06
+> **影�范围**: 车务管� / �险�� / 派�确认 / �消 / ��完结 / 车队对账
+
+---
+
+## 1. 结论
+
+- 车务�险���展示�机险任务，�展示游客�险�订��险�客户退款�险明细。
+- `insurance.type=perTrip` 的�机在派�确认进入 `assigned` �，�端按 `driverId + serviceDate` 自动一日一�投�。
+- �一�机�一�务日�能有一份�机险；��订�相接�日���买。
+- �消/��完结�，�退该�机该�务日已无其它 active 派��用的�日险。
+- �机险�进入车队/�机�本，�进入客户退款�订�收款�游客�险或���险。
+- 自动投退�失败�阻断派�主�程，但必须进入车务�险任务待处�。
+
+---
+
+## 2. 角色与��
+
+| 角色 | 行为 |
+|------|------|
+| `admin` / 车务角色 | �访问 `/admin/fleet/insurance/**`，�查看任务��试�标记线下完��忽略 |
+| `wx` / 定制师 | �应展示车务�险��；若访问 `/admin/fleet/**` 按角色守�返回 `403` |
+
+�端���用订��险页�的数��。车务�险���调本文件接�。
+
+---
+
+## 3. 接�一：�机险任务/�水分页
+
+```http
+GET /admin/fleet/insurance/tasks
+```
+
+### 3.1 Query �数
+
+| �数 | 类型 | 必填 | 示例 | 说明 |
+|------|------|------|------|------|
+| `page` | number | � | `1` | 页� |
+| `pageSize` | number | � | `20` | �页�数 |
+| `pendingOnly` | boolean | � | `true` | `true` �查 `PENDING/PROCESSING`；�传查全部 |
+| `taskType` | string | � | `PURCHASE` | `PURCHASE` 投� / `REFUND` 退� |
+| `taskStatus` | string | � | `PENDING` | `PENDING/PROCESSING/SUCCESS/RESOLVED/IGNORED` |
+| `driverId` | string | � | `188800000000000001` | �机 ID |
+| `assignmentId` | string | � | `194000000000000001` | 派� ID |
+| `orderId` | string | � | `193900000000000001` | 订� ID |
+| `serviceDateFrom` | string | � | `2026-07-01` | �务日起，`yyyy-MM-dd` |
+| `serviceDateTo` | string | � | `2026-07-31` | �务日止，�能早于起始日 |
+
+### 3.2 请求例�
+
+```http
+GET /admin/fleet/insurance/tasks?pendingOnly=true&taskType=PURCHASE&serviceDateFrom=2026-07-01&serviceDateTo=2026-07-31&page=1&pageSize=20
+Authorization: Bearer <admin-token>
+```
+
+### 3.3 �应例�
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "page": 1,
+    "pageSize": 20,
+    "total": 2,
+    "records": [
+      {
+        "taskId": "194100000000000001",
+        "bizKey": "PURCHASE:188800000000000001:2026-07-06",
+        "taskType": "PURCHASE",
+        "taskTypeLabel": "投�",
+        "taskStatus": "PENDING",
+        "taskStatusLabel": "待处�",
+        "driverId": "188800000000000001",
+        "driverName": "王师傅",
+        "assignmentId": "194000000000000001",
+        "orderId": "193900000000000001",
+        "orderNo": "HL20260705001",
+        "insuranceOrderId": null,
+        "policyNo": "",
+        "serviceDate": "2026-07-06",
+        "coverageStartDate": "2026-07-06",
+        "coverageEndDate": "2026-07-06",
+        "premiumAmount": "0.00",
+        "source": "BAOYOU",
+        "sourceLabel": "�游网",
+        "errorCode": "540007",
+        "errorMessage": "�险计划没有匹�该�障天数的费率",
+        "suggestedAction": "�险计划没有匹�该�障天数的费率，请维护费率��试",
+        "retryCount": 1,
+        "proofUrls": [],
+        "handledBy": null,
+        "handledAt": null,
+        "handleRemark": "",
+        "createTime": "2026-07-06T09:10:00",
+        "updateTime": "2026-07-06T09:12:00"
+      },
+      {
+        "taskId": "194100000000000002",
+        "bizKey": "PURCHASE:188800000000000001:2026-07-07",
+        "taskType": "PURCHASE",
+        "taskTypeLabel": "投�",
+        "taskStatus": "SUCCESS",
+        "taskStatusLabel": "已�功",
+        "driverId": "188800000000000001",
+        "driverName": "王师傅",
+        "assignmentId": "194000000000000002",
+        "orderId": "193900000000000002",
+        "orderNo": "HL20260705002",
+        "insuranceOrderId": "194200000000000001",
+        "policyNo": "BY-20260707001",
+        "serviceDate": "2026-07-07",
+        "coverageStartDate": "2026-07-07",
+        "coverageEndDate": "2026-07-07",
+        "premiumAmount": "18.00",
+        "source": "BAOYOU",
+        "sourceLabel": "�游网",
+        "errorCode": "",
+        "errorMessage": "",
+        "suggestedAction": "",
+        "retryCount": 0,
+        "proofUrls": [],
+        "handledBy": "0",
+        "handledAt": "2026-07-06T09:10:05",
+        "handleRemark": "",
+        "createTime": "2026-07-06T09:10:05",
+        "updateTime": "2026-07-06T09:10:05"
+      }
+    ]
+  }
+}
+```
+
+### 3.4 字段说明
+
+| 字段 | 说明 |
+|------|------|
+| `bizKey` | �端幂等键，�端�展示/排查，��拼业务逻辑 |
+| `taskType` | `PURCHASE` 投�，`REFUND` 退� |
+| `taskStatus` | `PENDING` 待处�，`PROCESSING` 处�中，`SUCCESS` 线上�功，`RESOLVED` 线下解决，`IGNORED` 已忽略 |
+| `premiumAmount` | 真实�费/退回金�，字符串；�端��转 number �精度�算 |
+| `source` | `BAOYOU` �游网，`OFFLINE` 线下处� |
+| `proofUrls` | 线下处�凭� URL；线上�功通常为空数组 |
+| `handledBy=0` | �端自动�功�水，�是人工账� |
+
+---
+
+## 4. 接�二：�试任务
+
+```http
+POST /admin/fleet/insurance/tasks/{taskId}/retry
+```
+
+### 4.1 请求例�
+
+```http
+POST /admin/fleet/insurance/tasks/194100000000000001/retry
+Authorization: Bearer <admin-token>
+```
+
+无 body。
+
+### 4.2 �应例�
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "taskId": "194100000000000001",
+    "taskStatus": "SUCCESS",
+    "taskStatusLabel": "已�功"
+  }
+}
+```
+
+### 4.3 �端处�
+
+- 点击�按钮加 loading，接�有幂等�护，��连续�交。
+- �功�刷新分页列表。
+- 如果�返回 `PENDING`，说明�试失败但已更新错误信�和 `retryCount`，�端展示最新 `errorMessage/suggestedAction`。
+
+---
+
+## 5. 接�三：标记线下完�
+
+```http
+POST /admin/fleet/insurance/tasks/{taskId}/offline-done
+```
+
+### 5.1 请求�数
+
+| 字段 | 类型 | 必填 | 示例 | 说明 |
+|------|------|------|------|------|
+| `policyNo` | string | 是 | `OFFLINE-20260701001` | 真实��� / 退�凭�� |
+| `premiumAmount` | decimal string | 是 | `"18.00"` | 真实�费金�；退�填实际退回/冲�金� |
+| `proofUrls` | string[] | 是 | `["https://...jpg"]` | 至少 1 个凭� URL |
+| `remark` | string | � | `����线下补投` | 处�备注 |
+
+### 5.2 请求例�
+
+```json
+{
+  "policyNo": "OFFLINE-20260701001",
+  "premiumAmount": "18.00",
+  "proofUrls": [
+    "https://oss.test.1814.love/fleet/insurance/OFFLINE-20260701001.jpg"
+  ],
+  "remark": "����线下补投，截图已上传"
+}
+```
+
+### 5.3 �应例�
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "taskId": "194100000000000001",
+    "taskStatus": "RESOLVED",
+    "taskStatusLabel": "已解决"
+  }
+}
+```
+
+### 5.4 校验
+
+- `policyNo` 为空：�数校验失败。
+- `premiumAmount` 为空或负数：�数校验失败。
+- `proofUrls` 为空数组或�传：返回 `100001` / �数校验失败。
+
+---
+
+## 6. 接�四：忽略任务
+
+```http
+POST /admin/fleet/insurance/tasks/{taskId}/ignore
+```
+
+### 6.1 请求例�
+
+```json
+{
+  "remark": "��人工记录，��已由�一任务处�"
+}
+```
+
+### 6.2 �应例�
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "taskId": "194100000000000001",
+    "taskStatus": "IGNORED",
+    "taskStatusLabel": "已忽略"
+  }
+}
+```
+
+---
+
+## 7. 自动触�场景
+
+| 场景 | �端行为 | �端关注 |
+|------|----------|----------|
+| 派�确认 `holding -> assigned` | perTrip �机按�务日�日投� | 确认派��功�代表�险一定�功，需看�险任务 |
+| 已有线上��覆盖��机�日 | ���购买，写 `SUCCESS` 幂等�水 | ���示��投� |
+| 已有手工/年�覆盖��机�日 | �买按�险，写 `PENDING` �醒核对 | 展示 `suggestedAction` |
+| 派��消 | �退该�机该�务日无其它 active 派��用的�日险 | �日�有其它订�时�会退 |
+| ��完结 | 退新 `endDate` 之���使用的�日险 | 定时完结通常无动作 |
+| 撤销�消��为 assigned | 如果之�已退险，���补买 | �端刷新任务列表 |
+
+---
+
+## 8. �端���的事
+
+- ��用大交通日期推导�机险�障日期；�机险�障日期以派��务日为准。
+- ��把�机险退�结果�与客户退款计算。
+- ��把 `premiumAmount` 转� JS number �计算。
+- ��在�端拼�试业务�数，�试�传 `taskId`。
+- ��在车务�险��展示订�游客险。
+- ��把 `SUCCESS` 自动�水当�待办�示；待办�看 `PENDING/PROCESSING`。
+
+---
+
+## 9. 错误��示
+
+| code | 场景 | �端文案建议 |
+|------|------|--------------|
+| `100001` | �数�法�任务缺上下文��务日区间�了 | 展示�端 message |
+| `100502` | 幂等�护，���交 | “正在处�，请勿���交� |
+| `540007` | �险计划缺费率 | “请维护�险计划费率��试� |
+| `540032` | ��机�务日已有��覆盖 | “已有��覆盖，请核对�处�� |
+| `605601` | �险�务��用 | “�险�务暂��用，请���试或线下处�� |
+
+---
+
+## 10. 测试�求
+
+�端�调���测接� 200。至少覆盖：
+
+- 新建订� -> 补出行人 -> 补大交通 -> �用车需求 -> 车务派�确认 -> �险任务生�。
+- �一�机�一�务日多订�，���买�险。
+- �消派�时，��机�日还有其它 active 派�则�退�。
+- 投�失败��试�功。
+- 线下完�必须上传凭�。
+- 定制师角色���车务�险��。