From ef8b59d23cbdef1e0050a01cbc5815ec11f2b735 Mon Sep 17 00:00:00 2001 From: wuzilong <704541015@qq.com> Date: Fri, 18 Sep 2026 18:08:11 +0800 Subject: [PATCH] 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 --- docs/demos/web-admin-login-wx-qr-demo.html | 479 ++++++++++++++++++ ...9-18-web-admin-wx-qr-phone-login-design.md | 303 +++++++++++ 2 files changed, 782 insertions(+) create mode 100644 docs/demos/web-admin-login-wx-qr-demo.html create mode 100644 docs/superpowers/specs/2026-09-18-web-admin-wx-qr-phone-login-design.md diff --git a/docs/demos/web-admin-login-wx-qr-demo.html b/docs/demos/web-admin-login-wx-qr-demo.html new file mode 100644 index 000000000..a9f38aacb --- /dev/null +++ b/docs/demos/web-admin-login-wx-qr-demo.html @@ -0,0 +1,479 @@ + + + + + + 山峡一体化门户 · 登录页 Demo（扫码 + 账号密码） + + + + + +
+ +
+ +
+ Copyright © 2025–2026 山峡化工有限公司 All Rights Reserved. +
+ + + + diff --git a/docs/superpowers/specs/2026-09-18-web-admin-wx-qr-phone-login-design.md b/docs/superpowers/specs/2026-09-18-web-admin-wx-qr-phone-login-design.md new file mode 100644 index 000000000..3f7d8742d --- /dev/null +++ b/docs/superpowers/specs/2026-09-18-web-admin-wx-qr-phone-login-design.md @@ -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": "", + "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_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`