Explorar el Código

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>
wuzilong hace 1 mes
padre
commit
ef8b59d23c

+ 479 - 0
docs/demos/web-admin-login-wx-qr-demo.html

@@ -0,0 +1,479 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>山峡一体化门户 · 登录页 Demo(扫码 + 账号密码)</title>
+  <style>
+    :root {
+      --primary: #10b981;
+      --primary-dark: #059669;
+      --primary-bg: #ecfdf5;
+      --text: #1e293b;
+      --muted: #64748b;
+      --border: #e5e7eb;
+      --danger: #dc2626;
+    }
+
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      font-family: Inter, "PingFang SC", "Microsoft YaHei", system-ui, sans-serif;
+      color: var(--text);
+      min-height: 100vh;
+    }
+
+    .page {
+      min-height: 100vh;
+      display: flex;
+      justify-content: flex-end;
+      align-items: center;
+      padding: 24px 200px 56px 24px;
+      position: relative;
+      background:
+        linear-gradient(120deg, rgba(15, 23, 42, 0.35), rgba(5, 150, 105, 0.25)),
+        radial-gradient(ellipse at 20% 30%, #86efac 0%, transparent 50%),
+        linear-gradient(135deg, #0f766e 0%, #134e4a 40%, #1e293b 100%);
+      background-size: cover;
+      background-position: center;
+    }
+
+    .page::before {
+      content: "";
+      position: absolute;
+      inset: 0;
+      background:
+        url("data:image/svg+xml,%3Csvg width='60' height='60' xmlns='http://www.w3.org/2000/svg'%3E%3Cg fill='none' fill-opacity='0.06'%3E%3Cpath d='M0 0h60v60H0z'/%3E%3Cpath stroke='%23fff' stroke-width='1' d='M0 30h60M30 0v60'/%3E%3C/g%3E%3C/svg%3E");
+      opacity: 0.5;
+      pointer-events: none;
+    }
+
+    .login-card {
+      width: 400px;
+      padding: 28px 28px 20px;
+      border-radius: 10px;
+      background: rgba(255, 255, 255, 0.72);
+      backdrop-filter: blur(12px);
+      border: 1px solid rgba(255, 255, 255, 0.35);
+      box-shadow: 0 20px 50px rgba(15, 23, 42, 0.18);
+      position: relative;
+      z-index: 1;
+    }
+
+    .brand {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      margin-bottom: 8px;
+    }
+
+    .brand-mark {
+      width: 180px;
+      height: 40px;
+      border-radius: 8px;
+      background: linear-gradient(90deg, var(--primary), var(--primary-dark));
+      color: #fff;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-weight: 700;
+      letter-spacing: 2px;
+      font-size: 15px;
+      margin-bottom: 10px;
+    }
+
+    .brand h1 {
+      font-size: 20px;
+      font-weight: 600;
+      margin-bottom: 6px;
+    }
+
+    .brand .hint {
+      font-size: 13px;
+      color: var(--muted);
+      text-align: center;
+      min-height: 20px;
+      margin-bottom: 16px;
+    }
+
+    .tabs {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      border-bottom: 1px solid var(--border);
+      margin-bottom: 20px;
+    }
+
+    .tab {
+      appearance: none;
+      border: 0;
+      background: transparent;
+      padding: 12px 8px;
+      font-size: 15px;
+      color: var(--muted);
+      cursor: pointer;
+      position: relative;
+      font-family: inherit;
+    }
+
+    .tab:hover { color: var(--primary); }
+
+    .tab.active {
+      color: var(--primary-dark);
+      font-weight: 600;
+    }
+
+    .tab.active::after {
+      content: "";
+      position: absolute;
+      left: 16%;
+      right: 16%;
+      bottom: -1px;
+      height: 2px;
+      background: var(--primary);
+      border-radius: 2px;
+    }
+
+    .panel { display: none; }
+    .panel.active { display: block; }
+
+    .qr-box {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      gap: 12px;
+      padding-top: 4px;
+    }
+
+    .qr-frame {
+      width: 200px;
+      height: 200px;
+      border: 1px solid var(--border);
+      border-radius: 10px;
+      background: #fff;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      overflow: hidden;
+      position: relative;
+    }
+
+    .qr-frame svg { width: 168px; height: 168px; }
+
+    .qr-overlay {
+      position: absolute;
+      inset: 0;
+      background: rgba(255, 255, 255, 0.88);
+      display: none;
+      align-items: center;
+      justify-content: center;
+      text-align: center;
+      padding: 16px;
+      font-size: 13px;
+      color: var(--muted);
+    }
+
+    .qr-overlay.show { display: flex; }
+
+    .qr-status {
+      font-size: 13px;
+      color: var(--muted);
+      text-align: center;
+      min-height: 20px;
+    }
+
+    .qr-status.error { color: var(--danger); }
+    .qr-status.ok { color: var(--primary-dark); }
+
+    .btn {
+      appearance: none;
+      border: 1px solid var(--border);
+      background: #fff;
+      color: var(--text);
+      border-radius: 8px;
+      height: 40px;
+      padding: 0 16px;
+      font-size: 14px;
+      cursor: pointer;
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      font-family: inherit;
+    }
+
+    .btn:hover { border-color: var(--primary); color: var(--primary-dark); }
+
+    .btn-primary {
+      width: 100%;
+      height: 48px;
+      border: 0;
+      color: #fff;
+      font-size: 16px;
+      background: linear-gradient(135deg, var(--primary) 0%, var(--primary-dark) 100%);
+    }
+
+    .btn-primary:hover { opacity: 0.92; }
+
+    .field {
+      margin-bottom: 18px;
+    }
+
+    .field label {
+      display: block;
+      font-size: 12px;
+      color: var(--muted);
+      margin-bottom: 6px;
+    }
+
+    .input {
+      width: 100%;
+      height: 44px;
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 0 14px;
+      font-size: 15px;
+      background: rgba(255, 255, 255, 0.9);
+      font-family: inherit;
+      color: var(--text);
+      outline: none;
+    }
+
+    .input:focus {
+      border-color: var(--primary);
+      box-shadow: 0 0 0 3px var(--primary-bg);
+    }
+
+    .footer {
+      position: fixed;
+      left: 0;
+      right: 0;
+      bottom: 0;
+      height: 40px;
+      line-height: 40px;
+      text-align: center;
+      color: rgba(255, 255, 255, 0.9);
+      font-size: 12px;
+      letter-spacing: 1px;
+      z-index: 2;
+    }
+
+    /* Demo controls */
+    .demo-bar {
+      position: fixed;
+      left: 20px;
+      top: 20px;
+      z-index: 10;
+      width: min(360px, calc(100vw - 40px));
+      background: rgba(15, 23, 42, 0.88);
+      color: #e2e8f0;
+      border-radius: 12px;
+      padding: 14px 16px;
+      font-size: 13px;
+      backdrop-filter: blur(8px);
+      box-shadow: 0 12px 32px rgba(0, 0, 0, 0.25);
+    }
+
+    .demo-bar h2 {
+      font-size: 14px;
+      margin-bottom: 8px;
+      color: #fff;
+    }
+
+    .demo-bar p {
+      color: #94a3b8;
+      line-height: 1.5;
+      margin-bottom: 10px;
+    }
+
+    .demo-actions {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 8px;
+    }
+
+    .demo-actions button {
+      appearance: none;
+      border: 1px solid #334155;
+      background: #1e293b;
+      color: #e2e8f0;
+      border-radius: 6px;
+      padding: 6px 10px;
+      font-size: 12px;
+      cursor: pointer;
+      font-family: inherit;
+    }
+
+    .demo-actions button:hover {
+      border-color: var(--primary);
+      color: #a7f3d0;
+    }
+
+    @media (max-width: 768px) {
+      .page {
+        justify-content: center;
+        padding: 72px 16px 64px;
+      }
+
+      .login-card { width: min(400px, 100%); }
+
+      .demo-bar {
+        left: 12px;
+        right: 12px;
+        width: auto;
+      }
+    }
+  </style>
+</head>
+<body>
+  <aside class="demo-bar">
+    <h2>登录页交互 Demo</h2>
+    <p>
+      默认「微信扫码」优先;可切换到「账号密码」。左侧按钮可模拟扫码各状态(仅演示,无真实接口)。
+    </p>
+    <div class="demo-actions">
+      <button type="button" data-sim="creating">生成中</button>
+      <button type="button" data-sim="pending">待扫码</button>
+      <button type="button" data-sim="scanned">已扫码</button>
+      <button type="button" data-sim="success">登录成功</button>
+      <button type="button" data-sim="expired">已过期</button>
+      <button type="button" data-sim="failed">失败</button>
+    </div>
+  </aside>
+
+  <div class="page">
+    <div class="login-card">
+      <div class="brand">
+        <div class="brand-mark">山峡化工</div>
+        <h1>山峡一体化门户</h1>
+        <p class="hint" id="subtitle">微信扫一扫,授权手机号后自动登录</p>
+      </div>
+
+      <div class="tabs" role="tablist">
+        <button type="button" class="tab active" data-tab="wechat" role="tab">微信扫码</button>
+        <button type="button" class="tab" data-tab="password" role="tab">账号密码</button>
+      </div>
+
+      <div class="panel active" id="panel-wechat" role="tabpanel">
+        <div class="qr-box">
+          <div class="qr-frame">
+            <!-- Decorative QR placeholder -->
+            <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+              <rect width="100" height="100" fill="#fff"/>
+              <rect x="8" y="8" width="28" height="28" fill="#0f172a"/>
+              <rect x="14" y="14" width="16" height="16" fill="#fff"/>
+              <rect x="18" y="18" width="8" height="8" fill="#0f172a"/>
+              <rect x="64" y="8" width="28" height="28" fill="#0f172a"/>
+              <rect x="70" y="14" width="16" height="16" fill="#fff"/>
+              <rect x="74" y="18" width="8" height="8" fill="#0f172a"/>
+              <rect x="8" y="64" width="28" height="28" fill="#0f172a"/>
+              <rect x="14" y="70" width="16" height="16" fill="#fff"/>
+              <rect x="18" y="74" width="8" height="8" fill="#0f172a"/>
+              <rect x="44" y="8" width="8" height="8" fill="#0f172a"/>
+              <rect x="56" y="20" width="8" height="8" fill="#0f172a"/>
+              <rect x="44" y="32" width="8" height="8" fill="#0f172a"/>
+              <rect x="44" y="44" width="12" height="12" fill="#10b981"/>
+              <rect x="64" y="44" width="8" height="8" fill="#0f172a"/>
+              <rect x="80" y="44" width="8" height="8" fill="#0f172a"/>
+              <rect x="44" y="64" width="8" height="8" fill="#0f172a"/>
+              <rect x="56" y="72" width="8" height="8" fill="#0f172a"/>
+              <rect x="72" y="64" width="20" height="8" fill="#0f172a"/>
+              <rect x="72" y="80" width="8" height="12" fill="#0f172a"/>
+              <rect x="88" y="72" width="4" height="20" fill="#0f172a"/>
+            </svg>
+            <div class="qr-overlay" id="qrOverlay"></div>
+          </div>
+          <p class="qr-status" id="qrStatus">请使用微信扫一扫</p>
+          <button type="button" class="btn" id="refreshBtn">↻ 刷新二维码</button>
+        </div>
+      </div>
+
+      <div class="panel" id="panel-password" role="tabpanel">
+        <form id="pwdForm" onsubmit="return false;">
+          <div class="field">
+            <label for="username">用户名</label>
+            <input class="input" id="username" type="text" placeholder="请输入用户名" autocomplete="username" />
+          </div>
+          <div class="field">
+            <label for="password">密码</label>
+            <input class="input" id="password" type="password" placeholder="请输入密码" autocomplete="current-password" />
+          </div>
+          <button type="button" class="btn btn-primary" id="loginBtn">登 录</button>
+        </form>
+      </div>
+    </div>
+  </div>
+
+  <div class="footer">
+    Copyright © 2025–2026 山峡化工有限公司 All Rights Reserved.
+  </div>
+
+  <script>
+    const subtitle = document.getElementById('subtitle')
+    const qrStatus = document.getElementById('qrStatus')
+    const qrOverlay = document.getElementById('qrOverlay')
+    const tabs = document.querySelectorAll('.tab')
+    const panels = {
+      wechat: document.getElementById('panel-wechat'),
+      password: document.getElementById('panel-password')
+    }
+
+    const statusMap = {
+      creating: { text: '正在生成二维码…', cls: '', overlay: '生成中…' },
+      pending: { text: '请使用微信扫一扫', cls: '', overlay: '' },
+      scanned: { text: '已扫码,请在手机上确认授权', cls: 'ok', overlay: '已扫码\n请在手机确认' },
+      success: { text: '登录成功,正在跳转…', cls: 'ok', overlay: '✓ 登录成功' },
+      expired: { text: '二维码已过期,请刷新后重扫', cls: 'error', overlay: '已过期\n请刷新' },
+      failed: { text: '扫码登录失败,请刷新后重试', cls: 'error', overlay: '登录失败' }
+    }
+
+    function setQrStatus(key) {
+      const conf = statusMap[key] || statusMap.pending
+      qrStatus.textContent = conf.text
+      qrStatus.className = 'qr-status' + (conf.cls ? ' ' + conf.cls : '')
+      if (conf.overlay) {
+        qrOverlay.textContent = conf.overlay
+        qrOverlay.classList.add('show')
+      } else {
+        qrOverlay.classList.remove('show')
+        qrOverlay.textContent = ''
+      }
+    }
+
+    function switchTab(name) {
+      tabs.forEach((t) => t.classList.toggle('active', t.dataset.tab === name))
+      Object.keys(panels).forEach((k) => panels[k].classList.toggle('active', k === name))
+      subtitle.textContent =
+        name === 'wechat'
+          ? '微信扫一扫,授权手机号后自动登录'
+          : '请输入账号密码登录系统'
+    }
+
+    tabs.forEach((tab) => {
+      tab.addEventListener('click', () => switchTab(tab.dataset.tab))
+    })
+
+    document.querySelectorAll('[data-sim]').forEach((btn) => {
+      btn.addEventListener('click', () => {
+        switchTab('wechat')
+        setQrStatus(btn.dataset.sim)
+      })
+    })
+
+    document.getElementById('refreshBtn').addEventListener('click', () => {
+      setQrStatus('creating')
+      setTimeout(() => setQrStatus('pending'), 600)
+    })
+
+    document.getElementById('loginBtn').addEventListener('click', () => {
+      const u = document.getElementById('username').value.trim()
+      const p = document.getElementById('password').value.trim()
+      if (!u || !p) {
+        alert('请输入用户名和密码(Demo 仅做前端校验)')
+        return
+      }
+      alert('Demo:账号密码登录成功(不会真实请求后端)')
+    })
+
+    setQrStatus('pending')
+  </script>
+</body>
+</html>

+ 303 - 0
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": "<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`