# 【功能落地·车辆/司机】常驻司机 1:1 车侧权威 — primaryDriverId 真实可用 + 详情回显

> **变更类型**：🟢 功能落地（原文档已描述、后端补实现；出入参字段不变）
> **端类型**：管理后台
> **服务**：hl-fleet-service
> **PR**：https://git.1814.love:8443/wx/HL/pulls/3602
> **日期**：2026-06-08

---

## ⚠️ 关键说明

「常驻司机」`primaryDriverId` 之前文档已写、但后端是占位（详情 `primaryDriverName` 一直返 null）。本次**真实落地**：

- **常驻严格 1:1·车侧权威**：一车一常驻司机、一司机一常驻车，权威落 `fleet_vehicle.primary_driver_id`。
- 与「派单 N:N」正交——常驻只是派单候选加权，实际派谁开哪台车仍可任意。

---

## 1. 前端能用什么了

| 场景 | 说明 |
|---|---|
| 车辆**编辑**（`PUT /admin/fleet/vehicles/{id}`）设常驻 | 入参 `primaryDriverId` 传司机 ID = 设为常驻；传 `null`/不传 = **解绑**常驻 |
| 设常驻**冲突** | 选的司机已是别车常驻 → 返 **`605022`**「该司机已是其它车辆的常驻司机，请先解绑后再指定」（不自动转移，需先去那台车解绑） |
| 车辆**详情**（`GET /admin/fleet/vehicles/{id}`）回显 | `primaryDriverId` / `primaryDriverName` / `primaryDriverPhone`（脱敏）现在**真实返回**（无常驻则三者全 null），不再恒 null |

---

## 2. 出参示例（详情，有常驻司机）

```json
{
  "code": 0,
  "data": {
    "id": "<vehicleId>",
    "plate": "蒙A-88888",
    "primaryDriverId": "1234567890",
    "primaryDriverName": "王师傅",
    "primaryDriverPhone": "138****1234"
  },
  "msg": "成功"
}
```

无常驻时：`primaryDriverId` / `primaryDriverName` / `primaryDriverPhone` 均为 `null`。

---

## 3. 新增错误码

| code | msg | 触发场景 |
|---|---|---|
| 605022 | 该司机已是其它车辆的常驻司机，请先解绑后再指定 | 设常驻时所选司机已是别车常驻 |

---

## 4. 尚未包含（下一步）

「司机**自带车**审核通过 → 自动建车 + 自动设常驻本人 + 自动归个人所有」**未包含**——它依赖「自带车→自动建车」路径，该路径目前后端未实现（自带车审核当前只在司机档案记车牌字符串、未建车辆记录）。该路径落地后会自动完成上述联动，届时另发 changelog。当前车管可手动建车 + 手动设常驻。

---

## 5. 验证

- `hl-fleet-service` 211 单测全绿。
- 已部署测试服（双实例 8087 + 8187 均 UP，Flyway 加列成功）；运行态 OpenAPI 契约详情含 `primaryDriverId`/`primaryDriverName`/`primaryDriverPhone`、编辑入参含 `primaryDriverId`。

---

## 6. 关联文档

| 文档 | 版本 |
|---|---|
| API-SPEC-FLEET | v1.5.18（§2.2 / §2.4 / §14.3 错误码 605022） |
| DATABASE-SCHEMA-FLEET | v1.5.15（fleet_vehicle.primary_driver_id + uk_primary_driver） |
| SRS-FLEET | v1.5（§9.15.4 常驻 1:1 车侧权威） |