From 1a910850b181ca0514ec3cae75d17cc61dc86e41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E8=88=AA=E5=AE=87?= <3364451258@qq.com> Date: Wed, 17 Jun 2026 00:04:54 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20QRGen=20GUI=20=E7=89=88=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../specs/2026-06-17-qrcode-gui-design.md | 206 ++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-17-qrcode-gui-design.md diff --git a/docs/superpowers/specs/2026-06-17-qrcode-gui-design.md b/docs/superpowers/specs/2026-06-17-qrcode-gui-design.md new file mode 100644 index 0000000..dc2de64 --- /dev/null +++ b/docs/superpowers/specs/2026-06-17-qrcode-gui-design.md @@ -0,0 +1,206 @@ +# QRGen GUI 版 — 设计文档 + +**日期**: 2026-06-17 +**作者**: 刘航宇 +**技术栈**: Tauri 2 + React 18 + TypeScript + TailwindCSS + +## 1. 项目概述 + +为 QRGen 添加桌面 GUI，采用和 PathEditor 一致的 Tauri 2 + React 架构， +复用已有 `qr-core` 库。支持 7 种编码模式、实时预览、多格式导出和历史记录。 + +## 2. 架构 + +``` +QRGen/ +├── Cargo.toml # workspace: core + cli + gui +├── core/ # 已有 qr-core 库（不动） +├── cli/ # 已有 CLI（不动） +└── gui/ # ★ 新增 Tauri 桌面应用 + ├── Cargo.toml + ├── tauri.conf.json + ├── src/ # Rust 后端 + │ ├── main.rs + │ └── lib.rs # Tauri commands + └── src-frontend/ # React 前端 + ├── package.json + ├── tsconfig.json + ├── tailwind.config.ts + ├── index.html + └── src/ + ├── main.tsx + ├── App.tsx + ├── components/ + │ ├── ModePanel.tsx + │ ├── QrPreview.tsx + │ ├── ControlBar.tsx + │ └── ExportPanel.tsx + ├── modes/ + │ ├── TextMode.tsx + │ ├── UrlMode.tsx + │ ├── WifiMode.tsx + │ ├── VCardMode.tsx + │ ├── EmailMode.tsx + │ ├── PhoneMode.tsx + │ └── SmsMode.tsx + ├── hooks/ + │ └── useQrEncode.ts + ├── store/ + │ └── history.ts + └── types/ + └── index.ts +``` + +## 3. 技术栈 + +| 层 | 技术 | 说明 | +|---|------|------| +| 桌面框架 | Tauri 2.6 | Rust 后端 + WebView 前端 | +| 前端 | React 18 + TypeScript | 组件化 UI | +| 样式 | TailwindCSS 4 | 磨砂玻璃效果 (backdrop-blur) | +| 状态管理 | React Context + useReducer | 全局 QR 状态 | +| 历史存储 | Tauri Plugin Store | 本地 JSON 持久化 | +| QR 编码 | qr-core | 已有 Rust 库 | +| 包管理 | pnpm | 与 PathEditor 一致 | + +## 4. 界面布局（三栏 + 底部输入） + +``` +┌─────────────────────────────────────────────────┐ +│ 🀫 QRGen _ □ × │ +├──────────┬──────────────────┬───────────────────┤ +│ │ │ │ +│ 模式面板 │ 实时预览区 │ 导出选项 │ +│ │ │ │ +│ ● 文本 │ ┌───────────┐ │ 模块: ──○── │ +│ ○ URL │ │ │ │ 纠错: [M ▼] │ +│ ○ WiFi │ │ QR 码 │ │ 边距: ──○── │ +│ ○ vCard │ │ SVG │ │ │ +│ ○ Email │ │ 实时预览 │ │ [复制] [PNG] │ +│ ○ 电话 │ │ │ │ [SVG] │ +│ ○ SMS │ │ │ │ │ +│ │ └───────────┘ │ 📋 历史记录 │ +│ │ │ · item 1 │ +│ │ 版本:5 61×61 │ · item 2 │ +├──────────┴──────────────────┴───────────────────┤ +│ 输入区（根据模式切换表单） │ +│ ┌─────────────────────────────────────────────┐│ +│ │ [模式专用表单字段] ││ +│ └─────────────────────────────────────────────┘│ +└─────────────────────────────────────────────────┘ +``` + +### 各区域说明 + +| 区域 | 宽度 | 内容 | +|------|------|------| +| 左侧模式面板 | ~200px | 7 个模式单选按钮、历史记录入口 | +| 中间预览区 | 自适应 | SVG QR 码实时预览、虚线边框、元信息 | +| 右侧导出面板 | ~220px | 模块大小滑块、纠错级别、边距、导出按钮组、历史列表 | +| 底部输入区 | 全宽 | 根据选中模式动态渲染表单组件 | + +## 5. 编码模式 & 表单字段 + +| 模式 | QR 内容格式 | 表单字段 | +|------|-----------|---------| +| 文本 | 直接编码 | 文本输入框 (textarea) | +| URL | 直接编码 | URL 输入框 + 协议自动补全 (https://) | +| WiFi | `WIFI:T:;S:;P:;;` | SSID、密码、加密方式(WPA/WEP/nopass)、隐藏网络开关 | +| vCard | `BEGIN:VCARD\n...\nEND:VCARD` | 姓名、电话、邮箱、公司、地址 | +| Email | `mailto:?subject=&body=` | 收件人、主题、正文 | +| 电话 | `tel:` | 电话号码输入框 | +| SMS | `smsto::` | 电话号码、消息内容 | + +## 6. 数据流 + +``` +用户输入 (200ms 防抖) + → React useReducer (QrState) + → Tauri invoke("encode_qr", { text, level, margin }) + → Rust: qr_core::QrCode::encode() + → 返回 { svg, version, size, mask } + → React 更新 preview 状态 + → SVG 渲染到预览区 +``` + +## 7. Tauri Commands（Rust → Frontend API） + +```rust +#[tauri::command] +fn encode_qr(text: String, level: String, margin: u8) + -> Result; + +#[tauri::command] +fn export_png(text: String, level: String, margin: u8, module_size: u8) + -> Result, String>; + +#[tauri::command] +fn save_history(entry: HistoryEntry) -> Result<(), String>; + +#[tauri::command] +fn load_history() -> Result, String>; + +#[tauri::command] +fn clear_history() -> Result<(), String>; +``` + +## 8. 状态结构（TypeScript） + +```typescript +interface QrState { + mode: 'text' | 'url' | 'wifi' | 'vcard' | 'email' | 'phone' | 'sms'; + formData: Record; + config: { + level: 'L' | 'M' | 'Q' | 'H'; + margin: number; + moduleSize: number; + }; + preview: { + svg: string | null; + version: number; + size: number; + mask: number; + } | null; + history: HistoryEntry[]; +} + +interface HistoryEntry { + id: string; + mode: string; + content: string; + timestamp: number; +} +``` + +## 9. 历史记录 + +- 最近 50 条，FIFO +- Tauri Plugin Store 持久化为本地 JSON +- 右侧面板显示列表，点击回填 +- 支持逐条删除 + 一键清空 + +## 10. 视觉效果 + +- 磨砂玻璃效果：`backdrop-blur-xl bg-white/70 dark:bg-gray-900/70` +- 圆角卡片：`rounded-2xl` +- 柔和阴影：`shadow-lg shadow-black/5` +- 预览区虚线边框：`border-2 border-dashed border-gray-300` +- 模式选中态高亮：渐变蓝色 `bg-gradient-to-r from-blue-500 to-cyan-500` +- 暗色模式支持（跟随系统） +- 窗口最小尺寸：900×650 + +## 11. 不实现的范围 + +- QR 码解码/扫描 +- 批量生成 +- 自定义 Logo 嵌入（艺术 QR） +- 打印功能 +- 自动更新 + +## 12. 里程碑 + +1. **M1**: Tauri 脚手架 + qr-core 集成 + 基础布局 +2. **M2**: 文本模式 + URL 模式 + 实时预览 +3. **M3**: WiFi + vCard + Email + 电话 + SMS 全模式 +4. **M4**: 导出功能 + 历史记录 + 暗色模式 +5. **M5**: 打包配置 + 图标 + 最终测试