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）

```rust
#[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）

```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**: 打包配置 + 图标 + 最终测试