# CLAUDE.md

## 项目概述

QRGen — 从零手搓的 QR 码生成器，Rust workspace (core + cli + gui)，完整实现 ISO/IEC 18004 国际标准。GUI + CLI + Library 三种使用方式。

## 构建命令

```bash
# 安装前端依赖（首次或 package.json 变更后）
cd gui/src-frontend && pnpm install && cd ../..

# 全 workspace 编译检查
cargo check

# 全部测试
cargo test                          # 69 tests

# 仅核心库
cargo test -p qr-core
cargo build -p qr-core

# CLI 构建
cargo build --release -p qrgen
cargo run -p qrgen -- "Hello World"

# GUI 开发模式
cd gui/src-frontend && pnpm dev    # 终端1: Vite 热更新
cargo run -p qrgen-gui             # 终端2: Tauri 窗口

# GUI 前端类型检查
cd gui/src-frontend && pnpm tsc --noEmit

# GUI 前端构建
cd gui/src-frontend && pnpm build

# GUI 完整打包（生成 NSIS 安装包）
# 需要先手动构建前端，再运行 tauri build
cd gui/src-frontend && pnpm build && cd ..
src-frontend/node_modules/.bin/tauri.cmd build

# Rust lint
cargo clippy -- -D warnings
```

## 架构

Cargo workspace 三层，前后端分离，Tauri IPC 通信。

```
QRGen/
├── core/                         # Rust 库 crate（零 Tauri 依赖）
│   └── src/
│       ├── qr.rs                 # 顶层 API — QrCode::encode()
│       ├── version.rs            # 40 版本容量表 + 自动选择
│       ├── ecc/
│       │   ├── galois.rs         # GF(2⁸) 运算 + exp/log 预计算表
│       │   └── reed_solomon.rs   # RS 纠错码 + 数据交错
│       ├── encoder/
│       │   ├── mode.rs           # 4 种编码模式 (数字/字母/字节/汉字)
│       │   ├── segment.rs        # 字符串分析 + 自动分段
│       │   └── bitstream.rs      # 比特流拼接 + 终止符/填充
│       ├── matrix/
│       │   ├── grid.rs           # 模块矩阵 (含 reserved 保留区)
│       │   ├── patterns.rs       # 定位/对齐/时序图案 + BCH(15,5) + BCH(18,6)
│       │   ├── placement.rs      # 蛇形数据排列
│       │   └── mask.rs           # 8 种掩码 + 四规则惩罚评分
│       └── render/
│           ├── png.rs            # PNG 输出 (image crate)
│           ├── svg.rs            # SVG 输出
│           └── ascii.rs          # 终端 ASCII (██/  )
├── cli/                          # CLI 命令行 (依赖 core + clap + anyhow)
│   └── src/main.rs               # Args { content, -o, -l, -v, -s, -m, --invert }
├── gui/                          # Tauri 桌面应用 (依赖 core)
│   ├── src/
│   │   ├── main.rs               # Windows 子系统入口
│   │   └── lib.rs                # 5 个 Tauri commands + AppState
│   ├── src-frontend/             # React 18 + TypeScript + TailwindCSS
│   │   └── src/
│   │       ├── App.tsx           # 三栏 + 底部输入布局
│   │       ├── components/       # ModePanel / QrPreview / ExportPanel / HistoryList
│   │       ├── modes/            # TextMode / UrlMode / WifiMode / VCardMode / EmailMode / PhoneMode / SmsMode
│   │       ├── hooks/            # useQrEncode (200ms 防抖 + Tauri invoke)
│   │       ├── store/            # QrProvider + useReducer
│   │       └── types/            # ModeType / QrState / QrAction / ...
│   ├── tauri.conf.json           # 窗口 900×650 + NSIS 打包配置
│   └── WebView2Loader.dll        # WebView2 运行时（打包用）
└── Cargo.toml                    # Workspace 根 + [workspace.package]
```

## IPC 接口（Rust → Frontend）

| Command | 参数 | 返回值 | 功能 |
|---------|------|--------|------|
| `encode_qr` | `text: String, level: String, margin: u8` | `Result<QrResponse, String>` | 编码文本为 QR，返回 SVG + 版本/尺寸/掩码 |
| `export_png` | `text: String, level: String, margin: u8, module_size: u8` | `Result<Vec<u8>, String>` | 编码并导出 PNG 字节 |
| `save_history` | `entry: HistoryEntry` | `Result<(), String>` | 添加历史记录（最多 50 条） |
| `load_history` | — | `Result<Vec<HistoryEntry>, String>` | 加载全部历史记录 |
| `clear_history` | — | `Result<(), String>` | 清空历史记录 |

## 前端状态管理

```
QrState {
  mode         → 当前编码模式 (text/url/wifi/vcard/email/phone/sms)
  formData     → 各模式表单数据 (Record<string, string>)
  config       → { level: L|M|Q|H, margin: 1-10, moduleSize: 2-20 }
  preview      → { svg, version, size, mask } | null
  history      → HistoryEntry[] (最多 50 条，FIFO)
  loading      → boolean
}

Action: SET_MODE | SET_FORM_DATA | SET_CONFIG | SET_PREVIEW | SET_LOADING
      | SET_HISTORY | ADD_HISTORY | REMOVE_HISTORY | RESET
```

## 编码模式文本格式

| 模式 | QR 内容格式 |
|------|-----------|
| text | 原始文本 |
| url | 原始 URL（失焦自动补全 `https://`） |
| wifi | `WIFI:T:<auth>;S:<ssid>;P:<pwd>;;` |
| vcard | `BEGIN:VCARD\nVERSION:3.0\nFN:...\nTEL:...\nEMAIL:...\nORG:...\nADR:...\nEND:VCARD` |
| email | `mailto:<addr>?subject=<s>&body=<b>` |
| phone | `tel:<number>` |
| sms | `smsto:<number>:<message>` |

## 关键约束

- **Rust 工具链**：`stable-x86_64-pc-windows-gnu`，MinGW-Builds GCC 15.2.0
- **MinGW 兼容**：`.cargo/config.toml` 已添加 `-lmcfgthread` 链接标志
- **qr-core 纯算法**：除 `image` (PNG) 外无外部依赖，不依赖任何 QR 编码库
- **qrcode crate 代码冲突**：如果系统安装了 `qrcode` Rust crate，需注意 QRGen 是从零实现的替代品
- **WebView2**：Windows 10+ 自带，打包需 `WebView2Loader.dll`
- **前端 beforeBuildCommand**：tauri build 前需确保 `pnpm` 在 PATH

## 测试覆盖

| 层级 | 数量 | 说明 |
|------|------|------|
| 单元测试 | 54 | Galois 运算、RS 编码、模式编码、掩码评分、格式信息等 |
| 集成测试 | 15 | 端到端编码、渲染输出验证、边距、特殊字符、自动版本选择 |
| 总计 | 69 | `cargo test` 全部通过 |

## 版本号升级清单

| 文件 | 字段 | 说明 |
|------|------|------|
| `Cargo.toml` | `[workspace.package] version` | Rust 全量自动继承 |
| `gui/tauri.conf.json` | `version` | 打包版本号 |
| `gui/tauri.conf.json` | 窗口 `title` | 窗口标题栏 |

Release 操作：
- `git tag vX.Y.Z && git push --tags`
- `tea release create --login cloud --repo Serendipity/QRGen --tag vX.Y.Z`