docs: README + CLAUDE.md + CHANGELOG
This commit is contained in:
@@ -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) — 河南理工大学人工智能协会
|
||||
Reference in New Issue
Block a user