QRGen/docs/superpowers/specs/2026-06-17-qrcode-gui-design.md

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:<auth>;S:<ssid>;P:<pwd>;;	SSID、密码、加密方式(WPA/WEP/nopass)、隐藏网络开关
vCard	BEGIN:VCARD\n...\nEND:VCARD	姓名、电话、邮箱、公司、地址
Email	mailto:<addr>?subject=<s>&body=<b>	收件人、主题、正文
电话	tel:<number>	电话号码输入框
SMS	smsto:<number>:<message>	电话号码、消息内容

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）

#[tauri::command]
fn encode_qr(text: String, level: String, margin: u8)
    -> Result<QrResponse, String>;

#[tauri::command]
fn export_png(text: String, level: String, margin: u8, module_size: u8)
    -> Result<Vec<u8>, String>;

#[tauri::command]
fn save_history(entry: HistoryEntry) -> Result<(), String>;

#[tauri::command]
fn load_history() -> Result<Vec<HistoryEntry>, String>;

#[tauri::command]
fn clear_history() -> Result<(), String>;

8. 状态结构（TypeScript）

interface QrState {
  mode: 'text' | 'url' | 'wifi' | 'vcard' | 'email' | 'phone' | 'sms';
  formData: Record<string, string>;
  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: 打包配置 + 图标 + 最终测试