docs: clarify fleet frontend contracts

2026-07-06 10:40:45 +08:00
@@ -11,6 +11,7 @@

 - 车务保险菜单只展示司机险任务，不展示游客保险、订单保险、客户退款保险明细。
 - `insurance.type=perTrip` 的司机在派单确认进入 `assigned` 后，后端按 `driverId + serviceDate` 自动一日一保投保。
+- `insurance.type=annual` 的司机不会自动按单买险，但派单确认时后端会逐服务日校验年保覆盖；年保到期或覆盖不足会生成车务保险待办。
 - 同一司机同一服务日只能有一份司机险；前后订单相接同日不重复买。
 - 取消/提前完结后，只退该司机该服务日已无其它 active 派单占用的单日险。
 - 司机险只进入车队/司机成本，不进入客户退款、订单收款、游客保险或合同保险。
@@ -275,6 +276,9 @@ POST /admin/fleet/insurance/tasks/{taskId}/ignore
 | 场景 | 后端行为 | 前端关注 |
 |------|----------|----------|
 | 派单确认 `holding -> assigned` | perTrip 司机按服务日逐日投保 | 确认派单成功不代表保险一定成功，需看保险任务 |
+| 派单确认时司机配置年保且服务日全部被 `annualStart~annualEnd` 覆盖 | 不买按单险，不生成待办 | 保险成本按年保摊销进车队成本 |
+| 派单确认时司机配置年保但部分服务日不被覆盖 | 对未覆盖服务日生成 `PENDING` 投保待办，错误码 `540033` | 提示车务续保/修正年保起止，或改按行程险后重试 |
+| 司机年保为手工/线下来源且与线上保单不一致 | 生成 `PENDING` 核对待办，错误码 `540034` | 提示上传线下凭证或修正保单信息 |
 | 已有线上保单覆盖同司机同日 | 不重复购买，写 `SUCCESS` 幂等流水 | 不要提示重复投保 |
 | 已有手工/年保覆盖同司机同日 | 不买按单险，写 `PENDING` 提醒核对 | 展示 `suggestedAction` |
 | 派单取消 | 只退该司机该服务日无其它 active 派单占用的单日险 | 同日仍有其它订单时不会退 |
@@ -291,6 +295,7 @@ POST /admin/fleet/insurance/tasks/{taskId}/ignore
 - 不要在前端拼重试业务参数，重试只传 `taskId`。
 - 不要在车务保险菜单展示订单游客险。
 - 不要把 `SUCCESS` 自动流水当成待办提示；待办只看 `PENDING/PROCESSING`。
+- 不要只看司机保险类型是 `annual` 就认为无需处理；必须以后端任务状态为准。年保到期、行程增加一天、换司机后都会重新按服务日校验。

 ---

@@ -302,6 +307,8 @@ POST /admin/fleet/insurance/tasks/{taskId}/ignore
 | `100502` | 幂等保护，重复提交 | “正在处理，请勿重复提交” |
 | `540007` | 保险计划缺费率 | “请维护保险计划费率后重试” |
 | `540032` | 同司机服务日已有保单覆盖 | “已有保单覆盖，请核对后处理” |
+| `540033` | 司机配置年保但服务日不在年保起止内 | “司机年保未覆盖当前服务日，请续保/修正年保后重试，或改按行程险处理” |
+| `540034` | 手工年保/线下保单与线上覆盖信息不一致 | “请核对线下保单并上传凭证，确认后标记线下完成” |
 | `605601` | 保险服务不可用 | “保险服务暂不可用，请稍后重试或线下处理” |

 ---
@@ -313,6 +320,8 @@ POST /admin/fleet/insurance/tasks/{taskId}/ignore
 - 新建订单 -> 补出行人 -> 补大交通 -> 提用车需求 -> 车务派单确认 -> 保险任务生成。
 - 同一司机同一服务日多订单，不重复买保险。
 - 取消派单时，同司机同日还有其它 active 派单则不退保。
+- 年保司机在服务期内不买按单险；服务日超过年保到期日时生成 `540033` 待办。
+- 年保续保后重试 `540033` 任务，应变为 `SUCCESS`，且不能产生重复按单险。
 - 投保失败后重试成功。
 - 线下完成必须上传凭证。
 - 定制师角色不可见车务保险菜单。