81 行
4.6 KiB
Markdown
81 行
4.6 KiB
Markdown
---
|
||
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 重复拒绝）
|