docs: README + CLAUDE.md + CHANGELOG

2026-06-17 08:43:04 +08:00
parent a46144f4dc
commit 7c13fb8f1c
3 changed files with 433 additions and 0 deletions
@@ -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 安装包
@@ -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<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`
@@ -0,0 +1,240 @@
+<p align="center">
+  <h1>🀫 QRGen</h1>
+  <p>从零手搓的 QR 码生成器 — ISO/IEC 18004 完整实现</p>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.1.0-blue" alt="version">
+  <img src="https://img.shields.io/badge/tauri-2.x-ffa03a" alt="tauri">
+  <img src="https://img.shields.io/badge/react-18-61dafb" alt="react">
+  <img src="https://img.shields.io/badge/rust-1.95-000000" alt="rust">
+  <img src="https://img.shields.io/badge/typescript-strict-blue" alt="typescript">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="license">
+  <img src="https://img.shields.io/badge/tests-69%20passed-brightgreen" alt="tests">
+</p>
+
+---
+
+## 简介
+
+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 种模式表单<br/>文本/URL/WiFi/vCard/Email/电话/SMS]
+        Preview[实时预览区<br/>SVG 渲染]
+        Export[导出面板<br/>PNG/SVG/复制]
+        History[历史记录面板<br/>回填/删除]
+        App --> Modes
+        App --> Preview
+        App --> Export
+        App --> History
+    end
+
+    subgraph CLI["CLI 命令行"]
+        Clap[clap 参数解析]
+    end
+
+    subgraph IPC["Tauri IPC 桥接"]
+        Commands[encode_qr / export_png<br/>save_history / load_history / clear_history]
+    end
+
+    subgraph Core["Rust core 库 (qr-core)"]
+        Encoder[编码层<br/>mode / segment / bitstream]
+        ECC[纠错层<br/>Galois GF2^8 / Reed-Solomon]
+        Matrix[矩阵层<br/>patterns / placement / mask]
+        Render[渲染层<br/>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) — 河南理工大学人工智能协会