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 目标

web-admin 登录以微信扫码为主：用户扫码 → 小程序授权手机号 → 匹配 sys_user.phone_no → 电脑端自动登录。
账号密码为辅入口（默认折叠，可展开），现有 RSA 登录逻辑保持可用。
不要求小程序事先已登录；授权成功后只登录电脑，手机不强制进入工作台。

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. 主流程

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. 会话状态机

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：

{
  "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：

{
  "sessionId": "...",
  "loginCode": "<wx.login code>",
  "phoneCode": "<getPhoneNumber code>"
}

处理顺序：

校验会话存在且为 pending/scanned、未过期。
code2session(loginCode) → openid（及可选 unionid）。
get_phone_number(phoneCode) → 手机号。
调用现有 resolve_wechat_login_user（与 POST /mini/auth/wechat-login 同源）。
issue_tokens_for_user → 写入会话 success + token 载荷。
失败 → 会话 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）。

布局：保留左右分栏；右侧主区为扫码，账号密码折叠为辅。

欢迎登录
微信扫一扫，授权手机号后自动登录

      [ 小程序码 ]
   状态文案（随轮询变化）
   [ 刷新二维码 ]

────── 或使用账号密码登录 ──────
（点击展开）
用户名 / 密码 / 登录（现有 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. 验收标准

登录页默认展示二维码；账号密码可展开且仍可登录。
微信扫码 → 授权手机号 → 电脑在数秒内进入系统；token 结构与密码登录一致。
匹配成功时按现逻辑绑定/校验 wx_openid。
无匹配、一号多人、停用、拒授权、过期：两端提示正确；可刷新或改用密码。
success 的 token 仅网页轮询成功取一次；重复请求不再返回完整票。
离开登录页停止轮询；刷新二维码使旧会话失效。
小程序未事先登录仍可完成授权。

8. 风险与缓解

风险	缓解
正式小程序未发布新页面	上线清单含发版；开发/体验用 `env_version`
`phone_no` 空或重复	主数据治理 + 明确失败文案
小程序码配额被刷	创建限流 + 短 TTL
scene 32 字符限制	短码 + 服务端映射完整 sessionId

9. 测试要点

单元/接口：会话状态迁移；success 一次性消费；过期；匹配失败各分支（可 mock 微信）。
手工：真机微信扫正式/体验码；电脑轮询成功进系统；密码辅入口回归；离页停轮询。

2026-09-18-web-admin-wx-qr-phone-login-design.md 10 KB Historia Raaka