# 【🔴前端必改·管理后台】司机自助录入「生成专属链接」需加「手机号(必填)+姓名(选填)」输入框 —— 后端已合并部署测试服并四路实测通过（PR #3815 / 工单 #3814）

> 端：hl-ui（车务管理 → 司机自助录入；保险订单/司机档案投保区同源生成入口）| 服务：hl-fleet-service `H5TokenAdminController` §4.1 | PR #3815 已合并 dev-v3 + 部署测试服 | 实测 2026-06-15
> ⚠️ **破坏性改动**：新招生成 token **手机号已变必填**。前端当前若仍不带手机号调生成接口 → 返 **100001**，新招生成会用不了，**请尽快加输入框**。

## ⚠️ 关键说明

司机自助录入「已发放链接」列表姓名/手机长期为「-」、「发短信」无号可发。后端已补：生成 token 时落库联系人，列表显示、「发短信」可直达。**前端需在生成入口加录入框并带参**。设计（wx 2026-06-15 拍）：**手动发短信 / 手机号必填、姓名选填 / 新招录入、续签自动取档案**。

## 1. 前端要做（两个 tab）

**新招(new)**：生成区加输入框
- 「手机号」**必填**（11 位，建议前端先做 `^1\d{10}$` 校验）
- 「姓名」选填
- 点「生成专属链接」时把 `phone` + `name` 一起传（见下端点）。

**续签(renew)**：**不要让车管重录**
- 选中司机后，姓名/手机由后端从所绑档案自动取，前端**无需传 phone/name**（传了也被后端忽略）。
- 如要展示，可只读/置灰显示该司机档案的姓名+脱敏手机（来源：司机列表项已有 name/phone）。

## 2. 端点契约（已部署实测）

`POST /admin/fleet/h5/token`（生成 token，base `/admin/fleet/h5`，网关 `/admin/fleet/**` 已覆盖）

| 字段 | 说明 |
|---|---|
| `mode` | `new`/`renew`（必填）|
| `phone` | 🆕 司机手机号。**新招必填(11位)**；续签可不传(取所绑档案) |
| `name` | 🆕 司机姓名。选填(新招录入)；续签忽略(取所绑档案) |
| `targetDriverId` | 续签必填(老档案 id，字符串透传防精度丢失) |
| `expireDays` | 选填(new=7/renew=14) |

错误码：**100001** 新招缺手机号「新招生成必须录入手机号」 / **400** 手机号格式不正确 / 600205 续签司机不存在。

返回不变：`pendingId/token/url/shortUrl/expireAt/qrCodeUrl`。

## 3. 配套（已就绪，前端零额外改动）

- 「已发放链接」列表（`GET /admin/fleet/h5/tokens`）的 `name`/`phone`(脱敏) 现在会有值，直接显示即可。
- 「发短信」（`POST /admin/fleet/h5/tokens/{pendingId}/resend`）端点未变；因生成时已落手机号，现在能直接发到该号、短信问候语带姓名。

## 实测（测试服网关 9443）

```
新招 {"mode":"new","phone":"13812340001","name":"测试新招ABC"} → 200；列表 name=测试新招ABC phone=138****0001
新招 {"mode":"new"}（缺手机号） → 100001「新招生成必须录入手机号」
新招 {"mode":"new","phone":"123"}（格式错） → 400「手机号格式不正确」
续签 {"mode":"renew","targetDriverId":"<司机id>"} → 200；列表显示该司机档案 name/phone（巴特尔 135****5020）
```

## 验收

新招：填手机号(必填)+姓名(选填) → 生成 → 「已发放链接」显示姓名/手机 → 点「发短信」发到该号。续签：选司机 → 生成 → 自动显示档案姓名/手机，无需重录。