---
schema: "hl-changelog/v2"
ticket: "5644"
title: "司机手机号支持车务管理员直接修改（放开 phone 可改）"
consumer: "admin"
author: "wx"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "mmg"
frontend_ref: "hl-admin@0e8340a1ca012de0c7e965906596ccc3c37d31cd"
target_release: ""
verified_at: "2026-08-07"
status_note: "后端完成：PR #5648 已合并 dev-v3（86e319ac1）并部署 TEST（hl-fleet-service 双实例）。手机号编辑放开：明文入参正常更新（格式 600212 / 重复 600203），脱敏回传保持原值；idCard 仍不可改。网关验证 12/12 通过：改 phone 生效、重复 600203、格式 600212、脱敏保持、idCard 不变、临时司机已清理。"
updated_at: "2026-08-07"
base: "dev-v3"
generated: "2026-08-07T14:50:00+08:00"
---

# 司机手机号支持车务管理员直接修改（放开 phone 可改）

> 后端完成：PR #5648 已合并 dev-v3 并部署 TEST。

## 关联 / 联系人

### 链接

- **Issue**: [#5644](https://git.1814.love:8443/wx/HL/issues/5644)
- **PR**: [#5648](https://git.1814.love:8443/wx/HL/pulls/5648)
- **Merge commit**: [86e319ac1](https://git.1814.love:8443/wx/HL/commit/86e319ac1)

### 联系人

- **后端负责人**: @wx

## 背景

司机手机号此前被锁死：后端编辑接口注释「idCard/phone 不可改：入参 phone 忽略不更新」，前端编辑页手机号禁用（「不可编辑，如需更换请联系管理员」）。wx 要求车务管理员可直接修改司机手机号（联系方式口径，不涉及司机登录账号体系）。

## 方案

**编辑司机档案接口放开 phone**（仅车务管理员权限，接口本身已由 `/admin/fleet/**` 角色门禁保护）：

1. `PUT /admin/fleet/drivers/{id}`：入参 `phone` 不再忽略——**非空明文（不含 `*`）时正常更新**，落库前校验：
   - **格式**：11 位数字，非法返 `code=600212 手机号格式错误（需 11 位数字）`（新增错误码；600211 已被 #5640 占用让位）
   - **唯一性**：`existsByPhone(phone, excludeSelf)` 排除自身，与其他司机重复返 `code=600203 手机号已存在`
2. **脱敏回写防护**：详情页回显的手机号是脱敏值（如 `135****5020`），前端原样回传（含 `*`）时**跳过更新保持原值**（与 license.no 同机制，防掩码串覆盖 AES 加密真值）；`phone` 不传（null）同样保持原值
3. **idCard 仍不可改**：入参忽略不更新（保持不变）
4. 手机号是唯一键（uk_phone），编辑更新走既有加密列等值比对（EncryptTypeHandler），服务层预校验 + DB 唯一键兜底

## 变更接口

| 方法 | 路径 | 服务 | 说明 |
|---|---|---|---|
| PUT | `/admin/fleet/drivers/{id}` | hl-fleet-service | **修改接口**：`phone` 入参放开可改（明文 11 位数字更新；含 `*` 脱敏回传 / null 保持原值；格式非法 600212；与其他司机重复 600203）；`idCard` 仍忽略不更新 |

**请求体变化**：`phone` 字段从「编辑忽略」变为「可编辑」（新增时本就必填，字段定义不变，仅编辑语义变化）。

## 行为变化

- **车务管理员**编辑司机档案时，手机号可直接修改（不再被忽略）；改后立即生效（档案联系方式口径，不联动登录账号）
- 修改为**其他司机已占用**的手机号 → `code=600203 手机号已存在`，整单拒绝
- 提交非 11 位数字 → `code=600212 手机号格式错误（需 11 位数字）`
- 不传 phone / 回传脱敏值 → 保持原手机号不变
- 身份证号（idCard）任何情况下不可修改（入参忽略）

## 前端/调用方动作

**必须**：司机编辑页手机号**去禁用**（去掉「不可编辑，如需更换请联系管理员」文案），改为可编辑输入框：
- 提交前可做 11 位数字格式校验（后端 600212 兜底）
- 若用户未修改手机号，编辑表单回显的是脱敏值（含 `*`），**原样回传即可**（后端保持原值）
- 修改时提交明文 11 位号码
- 后端返回 `600203`（重复）/ `600212`（格式）时按 Result 协议展示错误提示

## 验证证据

- **测试**：DriverServiceTest 151/151（新增 4 例：明文更新生效 / 脱敏回传保持原值 / 格式非法 600212 / 重复 600203 排除自身 / null 保持原值）、DriverControllerTest 30/30；fleet 全量 verify **3251 tests 0 失败 4 skipped** + spotless:check 通过（Release E 门禁参数）——见工单评论
- **部署**：hl-fleet-service 滚动部署 TEST 双实例 UP（dev-v3=86e319ac1）
- **网关验证**：待执行（改 phone 生效 / 脱敏保持 / 600203 重复拒绝）