hl-api-changelog/changelogs/2026-05/22_feat_admin_user_add_mobile.md

feat(user): admin_user 加 mobile 字段（必填+全局唯一）

仓库: HL (后端 hl-user-service) 关联 PR/Issue: PR #2897 (→ dev), PR #2898 (dev → dev-v3), Closes #2886 日期: 2026-05-22 影响范围: 管理后台「管理员管理」新增/编辑/列表 接收方: mmg (前端) 前端: 需要改动 — 表单加手机号字段 + 列表展示

---

🚨 关键变化

• 后端 admin_user 新增 mobile VARCHAR(20) NULL + uk_admin_user_mobile 唯一索引
• 新增管理员必填手机号(11 位中国大陆),编辑时允许补录但格式校验
• 后续场景: 定制师用手机号绑定个人微信、客人下单按手机号关联

---

一、API 影响

新增字段(出现在所有 admin 接口的 request / response)

字段	类型	必填(创建)	必填(编辑)	校验
mobile	String	✅ @NotBlank	❌(三态语义见下)	^1[3-9]\d{9}$ 11 位正则

POST /admin/user 创建管理员

请求体加 mobile(必填):

{
  "username": "zhangsan",
  "mobile": "13800138000",
  "roleIds": [2]
}

响应:

场景	code	message
成功	200	成功
漏 mobile	400	手机号不能为空
格式错(非 11 位 / 不是 1[3-9] 开头)	400	手机号格式不正确
重复 mobile	200310	手机号已被其他管理员使用,mobile={传入值}

PUT /admin/user/{adminId} 编辑管理员

请求体加 mobile(选填,但有三态规则):

当前 admin mobile	传入 mobile	行为
有值	null / 空串	保持原值不变
有值	非空 + 同值	不查重,正常更新其他字段
有值	非空 + 不同值 + 已被其他 admin 占	200310 手机号已被其他管理员使用
有值	非空 + 不同值 + 未被占	正常更新 mobile
空 (历史 admin)	null / 空串	200311 历史管理员编辑时必须补填手机号,adminId=xxx
空 (历史 admin)	非空	正常补录(走查重)

GET /admin/user 列表

响应每个 admin 记录新增 mobile 字段:

{
  "adminId": "...",
  "username": "cz",
  "mobile": "13800138000",
  "isDefaultConsultant": false,
  ...
}

错误码

code	含义
200310	手机号已被其他管理员使用
200311	历史管理员(mobile 为空)编辑时必须补填手机号

---

🚨 前端需要做的事

1. 新增管理员表单

文件: hl-ui/src/views/system/admin/... (新增/编辑弹窗)

• 加「手机号」必填输入框
• 前端做 11 位格式预校验(/^1[3-9]\d{9}$/)
• 提交后端响应 code=200310 → 提示「该手机号已被其他管理员使用,请更换」

2. 编辑管理员表单

• 加「手机号」输入框
• 历史 admin (mobile 为空) 编辑保存时,前端要把 mobile 字段标红强制要求填(后端会返 200311)
• 已有 mobile 的 admin,编辑时允许不传 mobile(保持原值)

3. 列表展示

• 表头加「手机号」列,展示 mobile 字段(null 时显示「未补录」或 -)
• 可选: 列表筛选条件加「手机号」关键字搜索

4. 自查

grep -rE "admin.*mobile|管理员.*手机" hl-ui/src

---

二、DB 改动

hl-user-service Flyway:

• V20260523_001__add_mobile_to_admin_user.sql
  • ALTER TABLE admin_user ADD COLUMN mobile VARCHAR(20) NULL COMMENT '手机号(11位中国大陆,允许 NULL 便于历史过渡)'
  • CREATE UNIQUE INDEX uk_admin_user_mobile ON admin_user (mobile)
• 允许 NULL: MySQL InnoDB 唯一索引允许多 NULL,历史 admin 平滑过渡
• 企微 mobile 接口权限已收回,不做自动回填,历史 admin 由运营手动逐个补录

---

三、唯一性策略

• DB 层: uk_admin_user_mobile 兜底
• Service 层: ensureMobileNotDuplicated 先查重报友好错码,排除 STATUS_DELETED admin(离职软删后释放手机号给新员工复用)

---

四、测试服验证记录

部署到测试服 (https://web.test.1814.love:9443) 后 round-trip 验证 (2026-05-22 15:50):

#	场景	预期	实测
T1	POST /admin/user 带 mobile	200 + 字段回显	✅ adminId 返回,mobile=13911119001
T2	POST /admin/user 漏 mobile	400 @NotBlank	✅ 手机号不能为空
T3	POST /admin/user 重复 mobile	200310	✅ 手机号已被其他管理员使用,mobile=13911119001
T4	POST /admin/user 格式错 mobile=123	400 @Pattern	✅ 手机号格式不正确
T5	PUT 编辑改成重复 mobile	200310	✅
T6	PUT 编辑改成新 mobile	200 + 回显	✅
T7	PUT 编辑同值 mobile	200 不查重	✅

测试服 dev-v3 已部署生效,可直接联调。

---

五、不在本次范围

• ❌ 「忘记密码走短信重置」(已规划 #2889 单独工单)
• ❌ 管理端手机号验证码登录(已规划 #2889 单独工单,免企微 2FA)
• ❌ 客人自主下单兜底绑定定制师(dev-v3 #2542 已实现,使用 is_default_consultant 字段)

---

六、联系人

后端: wx(呼籁旅行) 前端: mmg

如有疑问可在 #2886 评论区留言。