diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..dffa42a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,37 @@ +# Changelog + +## 0.1.0 (2026-06-17) + +### Added +- **核心算法**：完整实现 ISO/IEC 18004 QR 码生成 + - GF(2⁸) Galois 域运算（预计算 exp/log 表，0x11D 本原多项式） + - Reed-Solomon 纠错编码（动态生成多项式 + 多项式长除法 + 数据交错） + - 四种编码模式：数字 / 字母数字 / 字节 / 汉字 (Shift JIS) + - 字符串自动分段 + 最优模式选择 + - 8 种标准掩码 + 四规则惩罚评分（连续同色/2×2方块/伪定位图案/暗模块占比） + - 格式信息 BCH(15,5) + 版本信息 BCH(18,6) 编码 + - 40 版本 × 4 纠错级别完整容量表 +- **CLI 命令行工具** (`qrgen`) + - PNG/SVG/终端 ASCII 三种输出 + - 可调纠错级别、版本号、模块大小、白边 + - 反色模式 +- **GUI 桌面应用** (`qrgen-gui`) + - Tauri 2 + React 18 + TypeScript + TailwindCSS + - 7 种编码模式：文本 / URL / WiFi / vCard / Email / 电话 / SMS + - 实时预览（200ms 防抖，SVG 渲染） + - PNG/SVG 导出 + 复制到剪贴板 + - 历史记录（最近 50 条，回填/删除/清空） + - 暗色模式（跟随系统） + - 磨砂玻璃效果 (backdrop-blur) +- **程序库** (`qr-core`) + - 零外部 QR 依赖（仅 image crate 用于 PNG 输出） + - 自动版本选择 + - 完整 40 版本 × 四级纠错支持 + +### Technical +- Cargo workspace 三层架构 (core + cli + gui) +- qr-core：Serde 序列化支持（跨 IPC 传输） +- GUI：React Context + useReducer 状态管理 +- CLI：clap derive + anyhow 错误处理 +- 69 个测试（54 单元 + 15 集成） +- NSIS Windows 安装包 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6c4dcd1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,156 @@ +# 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` | 编码文本为 QR，返回 SVG + 版本/尺寸/掩码 | +| `export_png` | `text: String, level: String, margin: u8, module_size: u8` | `Result, String>` | 编码并导出 PNG 字节 | +| `save_history` | `entry: HistoryEntry` | `Result<(), String>` | 添加历史记录（最多 50 条） | +| `load_history` | — | `Result, String>` | 加载全部历史记录 | +| `clear_history` | — | `Result<(), String>` | 清空历史记录 | + +## 前端状态管理 + +``` +QrState { + mode → 当前编码模式 (text/url/wifi/vcard/email/phone/sms) + formData → 各模式表单数据 (Record) + 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:;S:;P:;;` | +| vcard | `BEGIN:VCARD\nVERSION:3.0\nFN:...\nTEL:...\nEMAIL:...\nORG:...\nADR:...\nEND:VCARD` | +| email | `mailto:?subject=&body=` | +| phone | `tel:` | +| sms | `smsto::` | + +## 关键约束 + +- **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` diff --git a/README.md b/README.md new file mode 100644 index 0000000..c690c85 --- /dev/null +++ b/README.md @@ -0,0 +1,240 @@ +

+

🀫 QRGen

+

从零手搓的 QR 码生成器 — ISO/IEC 18004 完整实现

+

+ +

+ version + tauri + react + rust + typescript + license + tests +

+ +--- + +## 简介 + +QRGen 是 **从零手写** 的 QR 码（二维码）生成器，完整实现 ISO/IEC 18004 国际标准。不依赖任何第三方 QR 编码库，所有算法（Galois 域运算、Reed-Solomon 纠错编码、BCH 格式编码、掩码评分）均从底层手搓。 + +支持 **三种使用方式**：程序库（`qr-core`）、命令行（`qrgen`）、桌面 GUI（`qrgen-gui`）。 + +## 架构 + +```mermaid +graph TB + subgraph Frontend["React 前端 (GUI)"] + App[App.tsx 三栏布局] + Modes[7 种模式表单
文本/URL/WiFi/vCard/Email/电话/SMS] + Preview[实时预览区
SVG 渲染] + Export[导出面板
PNG/SVG/复制] + History[历史记录面板
回填/删除] + App --> Modes + App --> Preview + App --> Export + App --> History + end + + subgraph CLI["CLI 命令行"] + Clap[clap 参数解析] + end + + subgraph IPC["Tauri IPC 桥接"] + Commands[encode_qr / export_png
save_history / load_history / clear_history] + end + + subgraph Core["Rust core 库 (qr-core)"] + Encoder[编码层
mode / segment / bitstream] + ECC[纠错层
Galois GF2^8 / Reed-Solomon] + Matrix[矩阵层
patterns / placement / mask] + Render[渲染层
PNG / SVG / ASCII] + Encoder --> ECC + ECC --> Matrix + Matrix --> Render + end + + Modes --> Commands + Commands --> Encoder + Clap --> Encoder +``` + +### 数据流水线 + +```mermaid +sequenceDiagram + actor U as 用户 + participant UI as React UI / CLI + participant Q as QrCode::encode() + participant E as 编码器 + participant RS as Reed-Solomon + participant M as 矩阵布局 + participant R as 渲染器 + + U->>UI: 输入文本 + UI->>Q: encode(text, config) + Q->>E: 分析字符集 → 自动分段 + E->>E: 模式编码 (数字/字母/字节/汉字) + E->>RS: 数据码字 + RS->>RS: 分组 + 纠错码字生成 + 交错 + RS->>M: 最终码字序列 + M->>M: 功能图案 + 蛇形数据排列 + 掩码评分 + M->>R: QR 矩阵 (bool bitmap) + R->>UI: PNG bytes / SVG string / ASCII string +``` + +## 功能 + +### 核心算法（全部手写） + +| 模块 | 内容 | 说明 | +|------|------|------| +| Galois 域 | GF(2⁸) 四则运算 + 幂运算 | 预计算 exp/log 表，本原多项式 0x11D | +| Reed-Solomon | RS 纠错码生成 + 数据交错 | 生成多项式动态构造，多项式长除法 | +| 编码模式 | 数字 / 字母数字 / 字节 / 汉字 | 4 种模式，自动分段选最优 | +| 矩阵布局 | 定位/对齐/时序图案 + 蛇形排列 | 8 种掩码 + 四规则惩罚评分 | +| BCH 编码 | 格式信息 BCH(15,5) + 版本信息 BCH(18,6) | 两级纠错保护 | +| 版本容量 | 40 版本 × 4 纠错级别完整参数表 | 自动版本选择 | + +### CLI 命令行 + +```bash +# 终端 ASCII 预览 +qrgen "Hello World" + +# 生成 PNG +qrgen "https://example.com" -o qr.png -s 8 + +# 生成 SVG（高纠错） +qrgen "重要数据" -o qr.svg -l H + +# 指定版本 + 反色 +qrgen "test" -v 10 --invert +``` + +### GUI 桌面应用 + +- **7 种编码模式**：文本 / URL / WiFi / vCard / Email / 电话 / SMS +- **实时预览**：200ms 防抖，SVG 即时渲染 +- **多格式导出**：PNG（可调模块大小）/ SVG / 复制到剪贴板 +- **历史记录**：最近 50 条，点击回填，支持删除和清空 +- **暗色模式**：跟随系统，磨砂玻璃效果 +- **纠错级别可调**：L (7%) / M (15%) / Q (25%) / H (30%) + +## 安装 + +从源码构建： + +```bash +# 克隆 +git clone git@lhy-git.liuhangyv.top:Serendipity/QRGen.git +cd QRGen + +# 安装前端依赖 +cd gui/src-frontend && pnpm install && cd ../.. + +# 构建 CLI +cargo build --release -p qrgen + +# 构建 GUI + NSIS 安装包 +# 1. 先构建前端 +cd gui/src-frontend && pnpm build && cd ../.. +# 2. 打包 +cd gui && src-frontend/node_modules/.bin/tauri.cmd build +``` + +> **要求**：Windows 10+（自带 WebView2），Rust 1.95+，Node.js 22+，pnpm + +## 开发 + +```bash +# 开发模式 GUI（热更新，需先 pnpm install） +cd gui/src-frontend && pnpm dev # 终端1: 前端 +cargo run -p qrgen-gui # 终端2: Rust 后端 + +# CLI 开发 +cargo run -p qrgen -- "Hello World" + +# 全部测试 +cargo test # Rust: 69 tests + +# 前端类型检查 +cd gui/src-frontend && pnpm tsc --noEmit + +# Rust lint +cargo clippy -- -D warnings +``` + +### 技术栈 + +| 层 | 技术 | +|---|---| +| 桌面框架 | Tauri 2.x | +| GUI 前端 | React 18 + TypeScript (strict) | +| UI 样式 | TailwindCSS 3 | +| 状态管理 | React Context + useReducer | +| 核心库 | Rust (qr-core) | +| CLI | clap + anyhow | +| 前端包管理 | pnpm | +| 打包 | NSIS | + +### 项目结构 + +``` +QRGen/ +├── core/ # Rust 核心库（算法全部在此） +│ └── 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 # 模块矩阵 +│ │ ├── patterns.rs # 定位/对齐/时序图案 + BCH 码 +│ │ ├── placement.rs # 蛇形数据排列 +│ │ └── mask.rs # 8 掩码 + 四规则评分 +│ └── render/ +│ ├── png.rs # PNG 输出 (image crate) +│ ├── svg.rs # SVG 输出 +│ └── ascii.rs # 终端 ASCII +├── cli/ # CLI 命令行工具 +│ └── src/main.rs # clap 参数解析 +├── gui/ # Tauri 桌面应用 +│ ├── src/ +│ │ ├── main.rs # Windows 子系统入口 +│ │ └── lib.rs # 5 个 Tauri commands +│ ├── src-frontend/ # React 前端 +│ │ └── src/ +│ │ ├── App.tsx # 主布局（三栏+底部输入） +│ │ ├── components/ # ModePanel / QrPreview / ExportPanel / HistoryList +│ │ ├── modes/ # 7 种模式表单 +│ │ ├── hooks/ # useQrEncode（防抖+编码） +│ │ ├── store/ # Context + useReducer +│ │ └── types/ # TypeScript 类型 +│ └── tauri.conf.json # 窗口 + NSIS 打包配置 +└── Cargo.toml # Workspace: core + cli + gui +``` + +## 支持规格 + +| 维度 | 范围 | +|------|------| +| QR 版本 | 1 ~ 40（21×21 ~ 177×177 模块） | +| 纠错级别 | L (7%) / M (15%) / Q (25%) / H (30%) | +| 编码模式 | 数字 / 字母数字 / 字节 / 汉字 (Shift JIS) | +| 输出格式 | PNG / SVG / 终端 ASCII | +| 自动版本选择 | 根据数据长度 + 纠错级别 | + +## 许可证 + +MIT License + +## 作者 + +[刘航宇](https://github.com/LHY0125) — 河南理工大学人工智能协会