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>
This commit is contained in:
wuzilongandCursor committed 2026-09-18 18:08:11 +08:00
1 parent 1ba1f38321
commit ef8b59d23c
2 files changed
+782

No files matched your search

+479
View File
@@ -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>
@@ -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`