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` +- 仓库地址： +- 联调/验收环境： +- 小程序：无需处理 + +## 变更接口 + +`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`。