docs: add web-admin WeChat QR phone login design.

Record the shanxia-shell + zkxw-tab dual-mode login approach (mini program code, session poll, phone_no match) with an interactive HTML demo for review. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 18:08:11 +08:00
1 parent 1ba1f38321
commit ef8b59d23c
@@ -0,0 +1,303 @@
+# web-admin 微信扫码登录（手机号匹配）设计
+
+> 日期：2026-09-18  
+> 适用范围：`web-admin` 登录页 + `backend` 扫码会话 + `miniprogram` 网页登录授权页  
+> 参考实现：中科兴皖 `zkxw`（`docs/superpowers/specs/2026-09-18-web-admin-wx-qr-phone-login-design.md`）  
+> 决策：完整对齐 zkxw 方案 1（小程序码 + 网页轮询 + 手机号匹配）；UI 采用「山峡壳 + 中科兴皖式 Tab」
+
+---
+
+## 1. 目标与已确认决策
+
+### 1.1 目标
+
+1. web-admin 登录以**微信扫码**为主：用户扫码 → 小程序授权手机号 → 匹配 `sys_user.phone_no` → 电脑端自动登录。
+2. **账号密码**为辅入口（Tab 切换），现有 RSA 登录逻辑保持可用。
+3. 不要求小程序事先已登录；授权成功后**只登录电脑**，手机不强制进入工作台。
+
+### 1.2 决策摘要
+
+| 项 | 约定 |
+|----|------|
+| UI 布局 | 保留山峡全屏背景 + 右侧毛玻璃登录卡；卡内 `el-tabs`：默认「微信扫码」、可切「账号密码」 |
+| 身份策略 | 授权手机号匹配 `phone_no`（复用小程序微信登录逻辑）；账号均已维护手机号 |
+| 扫码载体 | 微信小程序码（非开放平台网站应用经典扫码） |
+| 电脑取票 | 网页轮询会话状态，success 时下发与密码登录同结构的 JWT |
+| 未匹配 / 失败 | 明确提示，引导电脑端账号密码登录；**不自动注册** |
+| 手机会话 | 授权成功后小程序不强制写 JWT、不跳转工作台 |
+| 会话存储 | Redis（TTL 默认 180s）；无 Redis 时仅开发环境内存兜底 |
+| 实现策略 | 从 zkxw 按模块移植，对接山峡已有 `resolve_wechat_login_user` / `issue_web_login_tokens` / `WECHAT_MP_*` |
+
+### 1.3 非目标
+
+- 微信开放平台「网站应用」嵌入式二维码登录（无手机号）
+- 扫码自动开户 / 注册
+- 改动密码登录签发结构（须与现有 `token` / `refreshToken` / `userInfo` 对齐）
+- 替换 `miniprogram` 日常登录主流程（仅新增网页授权落地页）
+- 改成中科兴皖「左侧品牌绿 + 右侧白底」整页布局
+
+### 1.4 为何不走经典网页扫码
+
+PC 网页微信扫码（开放平台网站应用）一般只返回 openid/unionid，**不能授权手机号**。产品要求按手机号自动匹配，故必须经小程序 `getPhoneNumber`，再由网页轮询取票。
+
+---
+
+## 2. 主流程
+
+```text
+web-admin                         backend                         miniprogram
+   |                                 |                                |
+   |-- 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 --(PC 轮询消费)--> consumed
+   |                       |
+   |                       +--授权/匹配失败-->  failed（带 reason）
+   |
+   +--超时 / 刷新换新码-->  expired（旧 session 作废）
+```
+
+| 状态 | 含义 | 网页表现 |
+|------|------|----------|
+| `pending` | 已生成码，等待扫 | 「请使用微信扫一扫」 |
+| `scanned` | 已打开小程序页，待授权 | 「已扫码，请在手机上确认授权」 |
+| `success` | 已匹配并发票 | 取 token，进入系统 |
+| `failed` | 匹配或授权失败 | 展示 `message`，可刷新二维码 |
+| `expired` | 超时或已作废 | 自动或手动刷新 |
+
+规则：
+
+- TTL 默认 **180 秒**。
+- `success` 后 token 载荷**一次性消费**：网页轮询取走即从会话删除，防重放。
+- 刷新二维码 = 创建新会话，旧 `sessionId` 标记 `expired`。
+- `sessionId` 使用不可猜测值（UUID）；因小程序码 `scene` 最长 32 字符，对外 scene 可用短码，服务端映射到完整 sessionId。
+- Redis key 建议：`wxqr:sess:{id}`、`wxqr:short:{short}`（与 zkxw 对齐便于移植）。
+
+---
+
+## 4. 后端 API
+
+路径加入 `API_ENCRYPT_EXCLUDE_PATHS`（与现有 login / wechat-login 一致）。未登录可调。
+
+### 4.1 `POST /api/web/auth/wx-qr/create`
+
+生成扫码会话并返回小程序码图片。
+
+**响应 `data`：**
+
+```json
+{
+  "sessionId": "<完整会话 id，供轮询>",
+  "expiresIn": 180,
+  "qrImageBase64": "data:image/png;base64,..."
+}
+```
+
+实现要点：
+
+- 写入 Redis：`status=pending`、过期时间。
+- 调用微信获取不限制小程序码（`getwxacodeunlimit`），`page` 为小程序网页登录页路径，`scene` 为短码。
+- 同 IP / 同客户端创建频率限流，避免耗尽小程序码配额（与 zkxw 同级防护即可）。
+
+### 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": "..." }`（也可传短码，服务端 `resolve_session_id`）。  
+将 `pending` → `scanned`，改善网页文案。非法/过期会话返回错误。
+
+### 4.4 `POST /api/mini/auth/web-qr-confirm`
+
+Body：
+
+```json
+{
+  "sessionId": "...",
+  "loginCode": "<wx.login code>",
+  "phoneCode": "<getPhoneNumber code>"
+}
+```
+
+处理顺序：
+
+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_web_login_tokens` → 写入会话 `success` + token 载荷。
+6. 失败 → 会话 `failed` + `message`；响应错误文案与小程序展示一致。
+
+成功时小程序响应仅需业务成功提示（**可不向手机返回完整 web JWT**），电脑端通过轮询取票。
+
+### 4.5 复用与签发（山峡现状）
+
+| 能力 | 山峡落点 |
+|------|----------|
+| 匹配 / 绑定 | `backend/app/services/wechat_login_service.py` → `resolve_wechat_login_user` |
+| 发票 | `backend/app/services/web_login_tokens.py` → `issue_web_login_tokens` |
+| code2session / 手机号 | `backend/app/services/wechat_mini_auth.py`（已有） |
+| 小程序码 | **新增** `get_unlimited_wxacode`（从 zkxw 移植） |
+| 会话 | **新增** `backend/app/services/wx_qr_session.py`（从 zkxw 移植） |
+| 微信凭证 | `WECHAT_MP_APPID` / `WECHAT_MP_SECRET`（已有；**不用** zkxw 的 `WXPAY_*`） |
+
+路由挂载：`public.py`（web 公开端）+ `mini_auth.py`（小程序端）；注册方式遵循现有 `app/api/__init__.py` 与 `main.py` 约定。
+
+---
+
+## 5. 前端
+
+### 5.1 web-admin 登录页
+
+文件：`web-admin/src/views/auth/login/index.vue`、`web-admin/src/api/auth.ts`。
+
+布局：保留山峡壳；右侧卡内 Tab（对齐 Demo：`docs/demos/web-admin-login-wx-qr-demo.html`）。
+
+```text
+[ logo / 山峡一体化门户 ]
+副标题随 Tab 切换
+
+[ 微信扫码 | 账号密码 ]   ← 默认 wechat
+
+  微信扫码 Tab：
+    [ 小程序码 200×200 ]
+    状态文案
+    [ 刷新二维码 ]
+
+  账号密码 Tab：
+    用户名 / 密码 / 登录（现有 RSA）
+```
+
+交互：
+
+| 时机 | 行为 |
+|------|------|
+| 进入页 / 点刷新 | `create` → 展示码 → 开始轮询 |
+| pending | 「请使用微信扫一扫」 |
+| scanned | 「已扫码，请在手机上确认授权」 |
+| success | 停轮询 → `setToken` / `setUserInfo` → 通知 → 安全跳转（同现逻辑） |
+| failed | 展示 `message`，可刷新 |
+| expired | 提示过期，自动或手动刷新 |
+| 切到密码 Tab | 停止轮询 |
+| 切回微信 Tab | 失败/过期/无 session 则重新 `create`；否则恢复轮询 |
+| 离开页面 | 停止轮询 |
+
+API：`fetchWxQrCreate` / `fetchWxQrStatus`；请求头与加密白名单对齐（`X-Api-Crypto: off` 或走 exclude paths）。
+
+视觉：Fresh Mint（主色 `#10b981` 链）；二维码区简洁。
+
+### 5.2 miniprogram 网页登录授权页
+
+路径：`pages/login/web-qr/index`（写入 `pages.json`；小程序码 `page` / `WX_QR_PAGE` 与此一致）。
+
+- 入参：从 `scene` / query 解析短码或 `sessionId`。
+- Header 标题：网页登录授权。
+- 说明：正在登录电脑端管理后台，请授权手机号完成验证。
+- 主按钮：`open-type="getPhoneNumber"`（须用户点击；协议同意可复用现 `pages/login/login` 模式）。
+- 成功：提示「电脑端即将登录，可关闭本页」；不强制写本地 JWT、不跳转工作台。
+- 失败 / 缺 session：页内明确原因 + 引导电脑账号密码登录。
+- `onLoad` 可选调用 `web-qr-scanned`。
+- 视觉：三墙 Token（`#0a9f6d` 等），与日常登录页风格一致，**勿混用** web-admin Fresh Mint 主色。
+
+### 5.3 统一失败文案
+
+| 场景 | 文案方向 |
+|------|----------|
+| 未匹配手机号 | 未找到与该手机号匹配的员工账号，请使用电脑账号密码登录或联系管理员 |
+| 一号多人 | 手机号对应多个账号，请使用账号密码登录 |
+| 账号停用 | 账号已停用 |
+| 会话过期 | 二维码已过期，请在电脑上刷新后重扫 |
+| 拒绝授权 | 需要授权手机号才能完成扫码登录 |
+
+---
+
+## 6. 配置与改动清单
+
+### 6.1 配置
+
+| 项 | 说明 |
+|----|------|
+| `WECHAT_MP_APPID` / `WECHAT_MP_SECRET` | 已有；小程序码、换票、手机号 |
+| `REDIS_*` | 扫码会话；未配置时仅开发内存兜底；生产多实例必需 |
+| `API_ENCRYPT_EXCLUDE_PATHS` | 加入 `/api/web/auth/wx-qr/create`、`/api/web/auth/wx-qr/status`、`/api/mini/auth/web-qr-scanned`、`/api/mini/auth/web-qr-confirm` |
+| `WX_QR_SESSION_TTL_SEC` | 默认 180 |
+| `WX_QR_ENV_VERSION` | `release` / `trial` / `develop`，生成码环境 |
+| `WX_QR_PAGE` | 默认 `pages/login/web-qr/index` |
+| 小程序发版 | 必须包含 `pages/login/web-qr/index` |
+| 微信后台 | request 合法域名含 API |
+
+前端 `VITE_API_ENCRYPT_*` exclude 路径同步上述 web 端点（若生产加密开启）。
+
+无新业务表。
+
+### 6.2 代码改动面
+
+| 区域 | 内容 |
+|------|------|
+| backend | `wx_qr_session.py`；`get_unlimited_wxacode`；`/web/auth/wx-qr/*`；`/mini/auth/web-qr-*`；config + encrypt exclude；单测 |
+| web-admin | 登录页 Tab + 轮询；`auth.ts` 新增 create/status |
+| miniprogram | `pages/login/web-qr/index` + `pages.json` + API 封装；加密/请求 exclude |
+| docs | 本设计；实现计划另开；可选保留 Demo HTML |
+
+---
+
+## 7. 验收标准
+
+1. 登录页默认展示二维码 Tab；账号密码 Tab 仍可登录。
+2. 微信扫码 → 授权手机号 → 电脑在数秒内进入系统；token 结构与密码登录一致。
+3. 匹配成功时按现逻辑绑定/校验 `wx_openid`。
+4. 无匹配、一号多人、停用、拒授权、过期：两端提示正确；可刷新或改用密码。
+5. success 的 token 仅网页轮询成功取一次；重复请求不再返回完整票。
+6. 离开登录页停止轮询；刷新二维码使旧会话失效。
+7. 小程序未事先登录仍可完成授权。
+
+---
+
+## 8. 风险与缓解
+
+| 风险 | 缓解 |
+|------|------|
+| 正式小程序未发布新页面 | 上线清单含发版；开发/体验用 `WX_QR_ENV_VERSION` |
+| `phone_no` 空或重复 | 产品已确认账号均有手机号；仍保留失败文案兜底 |
+| 小程序码配额被刷 | 创建限流 + 短 TTL |
+| scene 32 字符限制 | 短码 + 服务端映射完整 sessionId |
+| 多实例无 Redis | 生产必须配置 Redis；文档标明内存仅开发兜底 |
+
+---
+
+## 9. 测试要点
+
+- 单元/接口：会话状态迁移；success 一次性消费；过期；匹配失败各分支（可 mock 微信）；可移植 zkxw `test_wx_qr_*` / `test_wxacode`。
+- 手工：真机微信扫正式/体验码；电脑轮询成功进系统；密码辅入口回归；离页停轮询；切 Tab 停/启轮询。
+
+---
+
+## 10. 参考
+
+- 中科兴皖设计：`/Users/zlwu/work/00code/zkxw/docs/superpowers/specs/2026-09-18-web-admin-wx-qr-phone-login-design.md`
+- 山峡 UI Demo：`docs/demos/web-admin-login-wx-qr-demo.html`
+- 山峡 UI 规范：`docs/web-admin-ui-spec-fresh-mint.md`、`docs/miniprogram-ui-spec-sanqiang.md`