hl-api-changelog/changelogs-v2/2026-08/07_5644_司机手机号支持车务管理员直接修改（放开phone可改）-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base, generated

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

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

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

关联 / 联系人

链接

• Issue: #5644
• PR: #5648
• Merge 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 重复拒绝）