# web-admin 微信扫码登录（手机号匹配）设计 > 日期：2026-09-18 > 适用范围：`web-admin` 登录页 + `backend` 扫码会话 + `mobile-h5` 网页登录授权页 > 关联：`docs/superpowers/specs/2026-08-10-mobile-h5-wechat-login-design.md` > 决策：方案 B（按手机号匹配）+ 实现方案 1（小程序码 + 网页轮询） --- ## 1. 目标与已确认决策 ### 1.1 目标 1. web-admin 登录以**微信扫码**为主：用户扫码 → 小程序授权手机号 → 匹配 `sys_user.phone_no` → 电脑端自动登录。 2. **账号密码**为辅入口（默认折叠，可展开），现有 RSA 登录逻辑保持可用。 3. 不要求小程序事先已登录；授权成功后**只登录电脑**，手机不强制进入工作台。 ### 1.2 决策摘要 | 项 | 约定 | |----|------| | 身份策略 | 授权手机号匹配 `phone_no`（复用小程序微信登录逻辑） | | 扫码载体 | 微信小程序码（非开放平台网站应用经典扫码） | | 电脑取票 | 网页轮询会话状态，success 时下发与密码登录同结构的 JWT | | 未匹配 / 失败 | 明确提示，引导电脑端账号密码登录；**不自动注册** | | 手机会话 | 授权成功后小程序不强制写 JWT、不跳转工作台 | | 会话存储 | Redis（TTL 默认 180s）；无 Redis 时仅开发环境内存兜底 | ### 1.3 非目标 - 微信开放平台「网站应用」嵌入式二维码登录（无手机号） - 扫码自动开户 / 注册 - 改动密码登录签发结构（须与现有 `token` / `refreshToken` / `userInfo` 对齐） - 替换 `mobile-h5` 日常登录主流程（仅新增网页授权落地页） ### 1.4 为何不走经典网页扫码 PC 网页微信扫码（开放平台网站应用）一般只返回 openid/unionid，**不能授权手机号**。产品要求按手机号自动匹配，故必须经小程序 `getPhoneNumber`，再由网页轮询取票。 --- ## 2. 主流程 ```text web-admin backend mobile-h5 | | | |-- POST /web/auth/wx-qr/create ->| | |<- sessionId + 小程序码 ---------| | | 展示二维码，开始轮询 | | | | 用户微信扫一扫 | | |------------------------------->| | | 打开 web-qr 页 | | |<- (可选) web-qr-scanned --------| |<- status=scanned ---------------| | | |<- web-qr-confirm (phone) -------| | | 匹配 phone_no，issue tokens | |<- status=success + JWT ---------| | | 写入 store，进入系统 | 提示成功，可关闭 | ``` --- ## 3. 会话状态机 ```text pending --扫码打开页--> scanned --授权成功--> success | | | +--授权/匹配失败--> failed（带 reason） | +--超时 / 刷新换新码--> expired（旧 session 作废） ``` | 状态 | 含义 | 网页表现 | |------|------|----------| | `pending` | 已生成码，等待扫 | 「请使用微信扫一扫」 | | `scanned` | 已打开小程序页，待授权 | 「已扫码，请在手机上确认授权」 | | `success` | 已匹配并发票 | 取 token，进入系统 | | `failed` | 匹配或授权失败 | 展示 `message`，可刷新二维码 | | `expired` | 超时或已作废 | 自动或手动刷新 | 规则： - TTL 默认 **180 秒**。 - `success` 后 token 载荷**一次性消费**：网页轮询取走即从会话删除，防重放。 - 刷新二维码 = 创建新会话，旧 `sessionId` 标记 `expired`。 - `sessionId` 使用不可猜测值（UUID）；因小程序码 `scene` 最长 32 字符，对外 scene 可用短码，服务端映射到完整 sessionId。 --- ## 4. 后端 API 路径加入 `API_ENCRYPT_EXCLUDE_PATHS`（与现有 login 一致）。未登录可调。 ### 4.1 `POST /api/web/auth/wx-qr/create` 生成扫码会话并返回小程序码图片。 **响应 `data`：** ```json { "sessionId": "<完整会话 id，供轮询>", "expiresIn": 180, "qrImageBase64": "data:image/png;base64,..." } ``` 实现要点： - 写入 Redis：`status=pending`、过期时间。 - 调用微信获取不限制小程序码（或等价 API），`page` 为小程序网页登录页路径，`scene` 为短码。 - 同 IP / 同客户端创建频率限流，避免耗尽小程序码配额。 ### 4.2 `GET /api/web/auth/wx-qr/status?sessionId=` 网页轮询（建议间隔约 1.5s）。 | status | 额外字段 | |--------|----------| | pending / scanned / expired | — | | failed | `message` | | success（首次消费） | `token`、`refreshToken`、`expiresIn`、`userInfo`（与 `/web/auth/login` 一致） | | success（已消费） | 视为过期或返回明确错误，不再下发票 | ### 4.3 `POST /api/mini/auth/web-qr-scanned`（可选） Body：`{ "sessionId": "..." }` 将 `pending` → `scanned`，改善网页文案。非法/过期会话返回错误。 ### 4.4 `POST /api/mini/auth/web-qr-confirm` Body： ```json { "sessionId": "...", "loginCode": "", "phoneCode": "" } ``` 处理顺序： 1. 校验会话存在且为 `pending`/`scanned`、未过期。 2. `code2session(loginCode)` → openid（及可选 unionid）。 3. `get_phone_number(phoneCode)` → 手机号。 4. 调用现有 `resolve_wechat_login_user`（与 `POST /mini/auth/wechat-login` 同源）。 5. `issue_tokens_for_user` → 写入会话 `success` + token 载荷。 6. 失败 → 会话 `failed` + `message`；响应错误文案与小程序展示一致。 成功时小程序响应仅需业务成功提示（**可不向手机返回完整 web JWT**），电脑端通过轮询取票。 ### 4.5 复用与签发 - 匹配 / 绑定：`app/services/wechat_login_service.py` 的 `resolve_wechat_login_user`。 - 发票：`issue_tokens_for_user`（与密码登录、小程序微信登录一致）。 - 微信凭证：复用 `WXPAY_MINI_APPID`、`WXPAY_SECRET`；新增服务端 `access_token` + 小程序码生成封装（仓库内尚无现成 getwxacode 实现）。 --- ## 5. 前端 ### 5.1 web-admin 登录页 文件：`web-admin/src/views/auth/login/index.vue`（及 `src/api/auth.ts`）。 布局：保留左右分栏；右侧主区为扫码，账号密码折叠为辅。 ```text 欢迎登录 微信扫一扫，授权手机号后自动登录 [ 小程序码 ] 状态文案（随轮询变化） [ 刷新二维码 ] ────── 或使用账号密码登录 ────── （点击展开） 用户名 / 密码 / 登录（现有 RSA 逻辑） ``` 交互： | 时机 | 行为 | |------|------| | 进入页 / 点刷新 | `create` → 展示码 → 开始轮询 | | pending | 「请使用微信扫一扫」 | | scanned | 「已扫码，请在手机上确认授权」 | | success | 停轮询 → `setToken` / `setUserInfo` → 通知 → 安全跳转（同现逻辑） | | failed | 展示 `message`，可刷新 | | expired | 提示过期，自动或手动刷新 | | 离开页面 | 停止轮询 | 视觉：Fresh Mint（主色 `#10b981` 链）；二维码区简洁。 ### 5.2 mobile-h5 网页登录授权页 路径建议：`pages/login/web-qr/index`（写入 `pages.json`；小程序码 `page` 与此一致）。 - 入参：从 `scene` / query 解析短码或 `sessionId`。 - Header 标题：网页登录授权。 - 说明：正在登录电脑端管理后台，请授权手机号完成验证。 - 主按钮：`open-type="getPhoneNumber"`（须用户点击；协议同意可复用现登录页模式）。 - 成功：提示「电脑端即将登录，可关闭本页」；不强制写本地 JWT、不跳转工作台。 - 失败 / 缺 session：页内明确原因 + 引导电脑账号密码登录。 - `onLoad` 可选调用 `web-qr-scanned`。 ### 5.3 统一失败文案 | 场景 | 文案方向 | |------|----------| | 未匹配手机号 | 未找到与该手机号匹配的员工账号，请使用电脑账号密码登录或联系管理员 | | 一号多人 | 手机号对应多个账号，请使用账号密码登录 | | 账号停用 | 账号已停用 | | 会话过期 | 二维码已过期，请在电脑上刷新后重扫 | | 拒绝授权 | 需要授权手机号才能完成扫码登录 | --- ## 6. 配置与改动清单 ### 6.1 配置 | 项 | 说明 | |----|------| | `WXPAY_MINI_APPID` / `WXPAY_SECRET` | 已有；小程序码、换票、手机号 | | `REDIS_*` | 扫码会话；未配置时仅开发内存兜底 | | `API_ENCRYPT_EXCLUDE_PATHS` | 加入 wx-qr / web-qr 相关路径 | | 可选 `WX_QR_SESSION_TTL_SEC` | 默认 180 | | 可选 `WX_QR_ENV_VERSION` | `release` / `trial` / `develop`，生成码环境 | | 小程序发版 | 必须包含 `pages/login/web-qr/index` | | 微信后台 | request 合法域名含 API | 无新业务表。 ### 6.2 代码改动面 | 区域 | 内容 | |------|------| | backend | 会话服务；小程序码生成；`/web/auth/wx-qr/*`；`/mini/auth/web-qr-*` | | web-admin | 登录页改版；auth API；轮询 | | mobile-h5 | web-qr 页 + `pages.json` | | docs | 本设计；实现计划另开 | --- ## 7. 验收标准 1. 登录页默认展示二维码；账号密码可展开且仍可登录。 2. 微信扫码 → 授权手机号 → 电脑在数秒内进入系统；token 结构与密码登录一致。 3. 匹配成功时按现逻辑绑定/校验 `wx_openid`。 4. 无匹配、一号多人、停用、拒授权、过期：两端提示正确；可刷新或改用密码。 5. success 的 token 仅网页轮询成功取一次；重复请求不再返回完整票。 6. 离开登录页停止轮询；刷新二维码使旧会话失效。 7. 小程序未事先登录仍可完成授权。 --- ## 8. 风险与缓解 | 风险 | 缓解 | |------|------| | 正式小程序未发布新页面 | 上线清单含发版；开发/体验用 `env_version` | | `phone_no` 空或重复 | 主数据治理 + 明确失败文案 | | 小程序码配额被刷 | 创建限流 + 短 TTL | | scene 32 字符限制 | 短码 + 服务端映射完整 sessionId | --- ## 9. 测试要点 - 单元/接口：会话状态迁移；success 一次性消费；过期；匹配失败各分支（可 mock 微信）。 - 手工：真机微信扫正式/体验码；电脑轮询成功进系统；密码辅入口回归；离页停轮询。