# 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) 评论区留言。