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:
1 parent
1ba1f38321
commit
ef8b59d23c
2 files changed
+782
No files matched your search
@@ -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`
|
||||
Reference in new issue
Block a user