From 60be9447034d107246e19a9f884887452879a077 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Wed, 22 Jul 2026 14:36:57 +0800
Subject: [PATCH] docs(api): publish driver insurance candidate contract
 (#5141)

---
 ...¸æœºä¿�险ä¿�障状æ€�-修改接å�£-å‰�端待处ç�†-管ç�†å�Žå�°.md | 69 +++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 changelogs-v2/2026-07/81_5141_车务派��机�险�障状�-修改接�-�端待处�-管���.md

diff --git a/changelogs-v2/2026-07/81_5141_车务派��机�险�障状�-修改接�-�端待处�-管���.md b/changelogs-v2/2026-07/81_5141_车务派��机�险�障状�-修改接�-�端待处�-管���.md
new file mode 100644
index 0000000..b720e23
--- /dev/null
+++ b/changelogs-v2/2026-07/81_5141_车务派��机�险�障状�-修改接�-�端待处�-管���.md
@@ -0,0 +1,69 @@
+---
+schema: "hl-changelog/v1"
+ticket: "5141"
+title: "车务派��机�险类型与行程�障状�"
+consumer: "admin"
+backend: "verified"
+gateway: "verified"
+frontend: "pending"
+base: "dev-v3"
+generated: "2026-07-22T14:07:00+08:00"
+---
+
+# �修改接�·�端待处�·管���】车务派��机�险类型与行程�障状�
+
+## 目标�端
+
+- 端类型：管���（Web）
+- 目标仓库：`mmg/hl-ui`
+- 仓库地�：<https://git.1814.love:8443/mmg/hl-ui.git>
+- �调/验收环境：<http://192.168.100.160:9527>
+- �程�：无需处�
+
+## �更接�
+
+`POST /admin/fleet/assignments/candidates` 的 `data.drivers.records[]` 新增�机�险字段。数�直接�自�机档案，并按本次请求的 `startDate/endDate` 判断全年�险是�完整覆盖行程。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `insuranceType` | String | `annual` 全年�险�`perTrip` 按行程投��`none` 无�险 |
+| `insuranceTypeLabel` | String | `全年�险`�`按行程投�`�`无�险` |
+| `insuranceAnnualStart` | Date/null | 全年�险起始日；� `annual` 为空 |
+| `insuranceAnnualEnd` | Date/null | 全年�险到期日；� `annual` 为空 |
+| `insuranceCoverageStatus` | String | 本次行程�障状�，枚举�下表 |
+| `insuranceCoverageMessage` | String | �端生�的中文�示，�直接展示 |
+| `insuranceCovered` | Boolean | 仅全年�险完整覆盖本次�务日期时为 `true` |
+
+## �障状�
+
+| `insuranceCoverageStatus` | `insuranceCoverageMessage` | �义 |
+| --- | --- | --- |
+| `ANNUAL_COVERED` | 全年�险已覆盖 | 年�起止日完整覆盖本次行程 |
+| `ANNUAL_NOT_COVERED` | 全年�险�覆盖本行程 | 年�缺日期�未生效�已过期或仅覆盖部分行程 |
+| `PER_TRIP_REQUIRED` | 待按行程投� | �机�置为按行程投�，候选阶段尚�代表已�出� |
+| `UNINSURED` | 无�险 | �机档案明确为无�险 |
+| `UNKNOWN` | �险状�未知 | 存�异常值兜底，�能当作已�障 |
+
+## �端展示规则
+
+- 在�机�片姓�或驾龄附近展示�险徽标，文案优先使用 `insuranceCoverageMessage`。
+- `ANNUAL_COVERED` �用绿色；`PER_TRIP_REQUIRED` 用橙色；`ANNUAL_NOT_COVERED/UNINSURED/UNKNOWN` 用红色或醒目警示色。
+- 全年�险�在悬浮�示或次级文案展示 `insuranceAnnualStart ~ insuranceAnnualEnd`。
+- �险状��用于车务判断和�示，�影��机候选的 `available`，�得因为未投�或待按行程投��用�机。
+- ���根� `insuranceType=annual` 显示“已�障�，必须以 `insuranceCoverageStatus` 或 `insuranceCovered` 为准。
+
+## �端处�清�
+
+- [ ] �机候选�片展示�险�障徽标。
+- [ ] 区分全年已覆盖�全年未覆盖�待按行程投��无�险�未知状�。
+- [ ] 年��查看�障起止日，且�把过期或部分覆盖年�展示为已�障。
+- [ ] �险状��改��机�选性，候选�用���� `available === false`。
+
+## 验���
+
+- �端 PR [wx/HL#5143](https://git.1814.love:8443/wx/HL/pulls/5143) 已�并到 `dev-v3`。
+- 派�候选与�机域定�测试共 148 项通过。
+- fleet `spotless:check` 与 `mvn -pl hl-fleet-service -am verify` 通过。
+- 测试网关真实返回 21 ��机，覆盖全年已覆盖�全年未覆盖�待按行程投�和无�险四类结果；�应与测试库�机�险档案��一致，19 �警示状��机��选择。
+
+> 本文是�端接入通知，�代表已修改或�布 `mmg/hl-ui`。