# 二期 v3 FLEET 车务：H5 入职接口可达 + 司机 PII 加密 + 车辆/司机契约补齐

> **服务**: hl-fleet-service + hl-gateway
> **PR**: #3102 / #3104 / #3106
> **Issue**: #3101 / #3103 / #3105
> **日期**: 2026-05-27
> **影响**: 🟡 H5 司机自助入职接口现可通过网关访问 + 车辆/司机列表新增字段 + 批量导入响应结构变更 + submit 入参字段名澄清(司机 PII 加密对前端透明)

---

## ⚠️ 关键变化(前端 mmg 必读)

### 1. 【重要】H5 司机自助入职接口现可通过网关访问(原 404)

之前网关缺 `/app/h5/**` 路由，下列 4 个 H5 端点过网关一律 404，现已补齐可正常调用：

- `GET  /app/h5/driver-onboard/init`
- `POST /app/h5/driver-onboard/ocr/{step}`(multipart 上传)
- `POST /app/h5/driver-onboard/submit/new`
- `POST /app/h5/driver-onboard/submit/renew`

鉴权：H5 端走**自带 onboard token**(query/form 参数，由后端 H5OnboardService 自校验)，**不需要 admin JWT**。坏 token 返 `data.tokenValid=false`(不报错)。

### 2. 车辆列表新增字段

`GET /admin/fleet/vehicles/page` 的 `records[]` 现包含：
- `typeKey` / `typeName`：车型大类(LEFT JOIN 车型库带出)
- `regDate`：注册日期

### 3. 司机列表新增字段

`GET /admin/fleet/drivers/page` 的 `records[]` 现包含：
- `licenseType` / `licenseExpire`：驾照类型 / 到期日
- `totalOrders` / `avgRating` / `lastOrderAt`：接单数 / 评分 / 最近接单(业务流水模块上线前为默认 `0`/`0.00`/`null`)

### 4. 批量导入响应结构变更 + 去重行为

**车辆导入** `POST /admin/fleet/vehicles/import` 出参：
```jsonc
// 之前: { total, success, failed, errorRows[] }
// 之后:
{ "totalRows": 10, "insertedCount": 7, "updatedCount": 2, "errorCount": 1,
  "errors": [ { "row": 5, "plate": "蒙A12345", "msg": "..." } ] }
```
**司机导入** `POST /admin/fleet/drivers/import` 出参：
```jsonc
{ "totalRows": 10, "insertedCount": 7, "renewedCount": 2, "errorCount": 1,
  "errors": [ { "row": 5, "name": "张三", "msg": "..." } ] }
```
**去重行为**：车牌(车辆)/身份证(司机)**已存在的行现执行 UPDATE**(原为报错计入失败)，不存在则 INSERT。

### 5. H5 新司机提交入参字段名澄清(文档笔误修正)

`POST /app/h5/driver-onboard/submit/new` 入参用：
- `idCard`(**不是** `idCardNo`)
- `preferredCategory`(**不是** `preferredTypeKey`)

代码一直是这两个名，是文档示例写错；文档已更正。前端按 `idCard` / `preferredCategory` 传参。

### 6. 司机敏感字段加密(后端透明，前端无需改动)

身份证 / 手机 / 驾照号 / 紧急联系电话改为**加密存储**。接口响应仍按原样**脱敏返回**(如 `idCard: "110***********2468"`)，与之前一致，**前端无感知**。

---

## 📌 备注

- **已部署测试服(dev-v3)并经真 admin token + 真实数据 API 验证全绿**：车辆列表 typeName/typeKey/regDate 正确填充(真实 MySQL JOIN)、身份证密文存储 + 加密后按身份证去重命中 + 读路径脱敏正常、司机列表 5 个新字段齐全、`/app/h5` 路由连通。
- 司机 PII 仅接通加密通道；测试库 #3104 前的存量明文司机均为软删数据，不影响。