From 4b1d24c7e121c0efa8aba24be64a8eaf12458c22 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 22 May 2026 15:51:01 +0800 Subject: [PATCH] =?UTF-8?q?feat(user):=20admin=5Fuser=20=E5=8A=A0=20mobile?= =?UTF-8?q?=20=E5=AD=97=E6=AE=B5=20(#2886=20/=20PR=20#2897=20/=20merge=20#?= =?UTF-8?q?2898)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-05/22_feat_admin_user_add_mobile.md | 164 ++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 changelogs/2026-05/22_feat_admin_user_add_mobile.md diff --git a/changelogs/2026-05/22_feat_admin_user_add_mobile.md b/changelogs/2026-05/22_feat_admin_user_add_mobile.md new file mode 100644 index 0000000..d6ad946 --- /dev/null +++ b/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) 评论区留言。