diff --git a/changelogs/2026-05/22_feat_customizer_share_and_remaining_attempts.md b/changelogs/2026-05/22_feat_customizer_share_and_remaining_attempts.md new file mode 100644 index 0000000..08b8e6b --- /dev/null +++ b/changelogs/2026-05/22_feat_customizer_share_and_remaining_attempts.md @@ -0,0 +1,213 @@ +# feat(user/order): 定制师小程序分享 + 登录锁定剩余次数 + AdminLoginResponse 加 mobile + +> **仓库**: HL (后端 hl-user-service + hl-mp-service + hl-order-service-v2 + hl-common-*) +> **关联 PR/Issue**: PR #2913, Closes #2907 +> **日期**: 2026-05-22 +> **影响范围**: 管理后台登录页错误提示、admin 自身信息接口、小程序定制师身份识别、客人下单链路 +> **接收方**: mmg (前端) +> **前端**: **需要 3 处改动 — 登录失败响应解析 + admin info 显示 mobile + 小程序分享按钮** + +--- + +## 🚨 三大变化 + +### 1. AdminLoginResponse 加 `mobile` 字段 + +`/admin/auth/info` / `/admin/auth/login` / `/admin/auth/sms/login` / `/admin/auth/wechat/verify-2fa` / `/admin/auth/refresh` 等所有 admin 鉴权出口共 **9 处 builder 全部填充** admin.mobile。 + +前端可以直接 `data.mobile` 拿到当前登录管理员的手机号。 + +### 2. 5 次错误锁定 + 剩余次数 / 锁定分钟数 + +引入 `LoginFailException` (BusinessException 子类) + `GlobalExceptionHandler.handleLoginFail` 拦截器 + `Result.error(code, msg, data)` 三参重载,**统一在 `Result.data` 携带结构化字段**: + +```json +{ + "code": 200203, + "message": "密码错误,剩余 3 次尝试", + "data": { + "remainingAttempts": 3, + "lockedMinutes": null + } +} +``` + +**前端直接读 `data.remainingAttempts` / `data.lockedMinutes`,不用解析 message 中文**。 + +### 3. 定制师小程序分享 + 客人下单 openid 反查 + +完整链路: + +``` +1. 定制师后台补 mobile (#2886 已上线) +2. 定制师 SMS 登录小程序,user 表存 phone + openid +3. 小程序前端调 GET /mp/customizer/me 识别身份 → 显示「分享给客人」按钮 +4. 客人通过分享链接下单,提交 sharerOpenid +5. 后端 sharerOpenid → user.phone → admin_user.mobile → adminId → order.customizer_id +``` + +--- + +## 一、错误响应 data 字段规范 + +### 密码登录失败 `POST /admin/auth/login` + +| 场景 | code | message | data | +|---|---|---|---| +| 错 1-4 次 | 200203 | `密码错误,剩余 N 次尝试` | `{remainingAttempts: N}` | +| **错 5 次直接锁定** | **200212** | `账号已锁定,请 30 分钟后重试` | `{lockedMinutes: 30}` | +| 已锁定中重新登录 | 200212 | 同上 | `{lockedMinutes: <剩余分钟>}` | + +⚠️ 改密码路径(`PUT /admin/auth/password`)旧密码错使用 **200213** `ADMIN_CHANGE_PASSWORD_OLD_WRONG`(避免 200203 模板冲突) + +### 短信验证码登录失败 `POST /admin/auth/sms/login` + +| 场景 | code | message | data | +|---|---|---|---| +| 码错 1-4 次 | 200102 | `验证码错误,剩余 N 次尝试` | `{remainingAttempts: N}` | +| **码错 5 次直接锁定** | **200104** | `短信登录失败次数过多,请 15 分钟后重试` | `{lockedMinutes: 15}` | +| 验证码过期 / 未发送 | 200103 | `验证码已过期,请重新获取` | `{}` (**不增 fail count**,防攻击者锁住真用户) | + +--- + +## 🚨 前端需要做的事 + +### 1. 登录失败响应解析(账密 + 短信) + +文件:`hl-ui/src/views/login/...`、`hl-ui/src/api/admin.js` + +```js +// 拦截器或登录页 onError +if (resp.code === 200203 || resp.code === 200102) { + // 密码 / 验证码错 + const remaining = resp.data?.remainingAttempts + showError(`${resp.message}` + (remaining != null ? `(还剩 ${remaining} 次)` : '')) +} +if (resp.code === 200212 || resp.code === 200104) { + // 账号 / 短信登录已锁定 + const minutes = resp.data?.lockedMinutes + showError(`${resp.message}` + (minutes != null ? `(剩余 ${minutes} 分钟)` : '')) + lockLoginButton(minutes * 60 * 1000) +} +``` + +### 2. /admin/auth/info 显示当前管理员手机号 + +文件:`hl-ui/src/views/profile/...` 或顶部用户信息组件 + +```js +const me = await getAdminInfo() // GET /admin/auth/info +this.mobile = me.data.mobile // 直接读 (null 时显示「未补录」) +``` + +### 3. 小程序定制师身份识别 + 分享按钮(mp 前端) + +文件:`mp-cli/src/pages/...`、`mp-cli/src/api/customizer.js` + +```js +// 登录后调一次 +const me = await getCustomizerMe() // GET /mp/customizer/me +if (me.data.isCustomizer) { + this.showShareButton = true + this.customizerInfo = me.data // adminId, customizerName, customizerAvatar +} +``` + +**分享链接 URL 必须带 `?sharerOpenid={当前用户 openid}`**(从当前小程序登录态拿)。 + +客人点开分享链接下单时,把 `sharerOpenid` 透传到下单请求 body (字段名沿用现有 `MpCreateOrderRequest.sharerOpenid`,已具备)。 + +### 4. 自查 + +```bash +grep -rE "remainingAttempts|lockedMinutes|/mp/customizer/me|sharerOpenid|admin.*mobile" hl-ui/src mp-cli/src +``` + +--- + +## 二、新增接口清单 + +### `GET /mp/customizer/me` — 当前用户的定制师身份 + +JWT 鉴权,无 token → 401。 + +响应: + +```json +{ + "code": 200, + "data": { + "isCustomizer": true, + "adminId": 9999999998, + "customizerName": "张三", + "customizerAvatar": "https://..." + } +} +``` + +`isCustomizer: false` 时其他字段为 null。 + +### 内部 Feign(后端服务间用,前端不调) + +- `GET /internal/user/admin/by-phone?phone=` 返 admin 信息或 null +- `GET /internal/mp/user/by-openid?openid=` 返 user.phone 或 null + +--- + +## 三、客人下单链路改造(对前端透明) + +`POST /mp/order/create` 流程改造,**前端无 API 字段变化**: + +``` +优先级: +1. request.customizerId 显式传 (现有 ?adminId=xxx URL 透传路径) +2. customizerId 为空 + sharerOpenid 非空 → 后端 openid → phone → adminId 反查 +3. 都没命中 → 沿用现有 assignRandomCustomizer 兜底 +``` + +反查失败降级不抛异常,客人下单不被后台问题阻塞。 + +--- + +## 四、新错误码(本期新增 4 个) + +| code | 含义 | data | +|---|---|---| +| 200212 | 账号已锁定(密码登录) | `{lockedMinutes: 30}` | +| 200213 | 旧密码错(改密码场景,与登录密码错码分离) | `{}` | +| 200102 message 更新 | 验证码错误,剩余 N 次尝试 | `{remainingAttempts: N}` | +| 200203 message 更新 | 密码错误,剩余 N 次尝试 | `{remainingAttempts: N}` | + +--- + +## 五、测试服验证记录 + +部署到测试服 (`api.test.1814.love:9443`) 后 round-trip 验证 (2026-05-22 18:07): + +| # | 场景 | 实测 | +|---|------|------| +| T1 | admin 登录 + /admin/auth/info 返回 mobile | ✅ mobile=13800138000 | +| T2 | 密码错 1-3 次 remainingAttempts 累加 | ✅ 4/3/2 | +| T3 | 密码错 5 次直接锁定 | ✅ 200212 + lockedMinutes=30 | +| T4 | SMS 错码 remainingAttempts 累加 | ✅ 4/3/2 | +| T5 | /mp/customizer/me 端点路由 | ✅ (401 鉴权要求, 路由正常) | + +⚠️ test_admin_lock 测试用户因没绑企微 login 时 token=null(`requireWechatBind=true`),改用内置 admin(已绑企微)测 info 端点通过。 + +--- + +## 六、不在本期范围 + +- ❌ dev-v3 二期同步 (另起工单) +- ❌ 客人维度长期绑定定制师 (另起工单) +- ❌ admin_user 表 schema 改动 (字段都已具备) +- ❌ 跨 appId openid 隔离 (当前单小程序) + +--- + +## 七、联系人 + +后端: wx(呼籁旅行) +前端: mmg + +如有疑问可在 [#2907](https://git.1814.love:8443/wx/HL/issues/2907) 评论区留言。