feat(user): admin_user 加 mobile 字段 (#2886 / PR #2897 / merge #2898)

changelogs/2026-05/22_feat_admin_user_add_mobile.md

@@ -0,0 +1,164 @@
+# 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`(必填):
+
+```json
+{
+  "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` 字段:
+
+```json
+{
+  "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. 自查
+
+```bash
+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](https://git.1814.love:8443/wx/HL/issues/2886) 评论区留言。