Serendipity/QRGen
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新全部 markdown 文档 — 加入解码器内容

Browse Source 
- README: 解码功能说明 + CLI/Web/GUI 解码示例 + 项目结构树 + 规格表
- CHANGELOG: 解码器条目（9 模块 + 三端入口 + RS/BCH 算法）
- ROADMAP: 解码移至已交付 + 前端工程化 + RS 纠错解码
- CLAUDE.md: 解码器架构 + Web API decode 端点 + IPC 接口
This commit is contained in:
刘航宇
2026-06-19 20:45:22 +08:00
parent 11fbe20102
commit 797a41ea50
4 changed files with 58 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+9 -1
View File
@@ -33,6 +33,14 @@
- 零外部 QR 依赖（仅 image crate 用于 PNG 输出）
- 自动版本选择
- 完整 40 版本 × 四级纠错支持
- **QR 解码器** (`core/src/decoder/`)
- 从零手写的完整解码流水线（图像→定位→提取→纠错→解码→文本）
- BCH(15,5) + BCH(18,6) 查表解码（t≤3 位纠错）
- Reed-Solomon 纠错流水线（伴随式→Berlekamp-Massey→Chien→Forney）
- 定位图案检测（1:1:3:1:1 比例扫描+聚类）
- 逆向 4 种编码模式（数字/字母/字节/汉字 Shift JIS）
- CLI `--decode <file>` / Web `POST /api/decode` / GUI 文件解码
- PNG/JPEG/WebP 多格式图像输入
### Fixed
@@ -57,7 +65,7 @@
- GUI：React Context + useReducer，共享文本构造工具 (utils/qrText.ts)
- CLI：clap derive + anyhow 错误处理
- Web：axum 0.8 + tokio，编译期 HTML 嵌入 (include_str!)
- 82 个测试（58 单元 + 24 集成）
- 96 个测试（72 单元 + 24 集成）
- NSIS Windows 安装包 + Docker Alpine 镜像
- 文档：API doc comments（rustdoc 可用）+ 3 个代码示例
- 社区：CONTRIBUTING / CODE_OF_CONDUCT / SECURITY / Issue & PR 模板
CLAUDE.md
+19 -4
View File
@@ -2,7 +2,7 @@
## 项目概述
QRGen — 从零手搓的 QR 码生成器，Rust workspace (core + cli + gui + web)，完整实现 ISO/IEC 18004 国际标准。GUI + CLI + Web + Library 四种使用方式。
QRGen — 从零手搓的 QR 码生成/解码器，Rust workspace (core + cli + gui + web)，完整实现 ISO/IEC 18004 国际标准。GUI + CLI + Web + Library 四种使用方式，支持编码+解码双向闭环。
## 构建命令
@@ -27,6 +27,9 @@ cargo run -p qrgen -- "Hello World"
# Web 服务
cargo run -p qrgen-web # → http://localhost:3000
# CLI 解码
cargo run -p qrgen -- --decode test.png
# GUI 开发模式
cd gui/src-frontend && pnpm dev # 终端1: Vite 热更新
cargo run -p qrgen-gui # 终端2: Tauri 窗口
@@ -71,12 +74,22 @@ QRGen/
│ ├── qr.rs # 顶层 API — QrCode::encode()，9 步流水线
│ ├── version.rs # 40 版本容量表 + 自动选择
│ ├── ecc/
│ │ ├── galois.rs # GF(2⁸) 运算 + exp/log 预计算表
│ │ ├── galois.rs # GF(2⁸) 运算 + exp/log 预计算表 + poly_eval
│ │ └── reed_solomon.rs # RS 纠错码 + 数据交错
│ ├── encoder/
│ │ ├── mode.rs # 4 种编码模式 (数字/字母/字节/汉字 Shift JIS)
│ │ ├── segment.rs # 字符串分析 + 自动分段
│ │ └── bitstream.rs # 比特流拼接 + 终止符/填充
│ ├── decoder/ # QR 解码器（从零手写）
│ │ ├── mod.rs # 顶层 API — decode_image() + decode_matrix()
│ │ ├── bch.rs # BCH(15,5)+BCH(18,6) 查表解码
│ │ ├── format.rs # 格式信息 + 版本信息读取
│ │ ├── extract.rs # 逆向蛇形排列提取码字
│ │ ├── deinterleave.rs # 逆向 RS 数据交错
│ │ ├── rs_decode.rs # RS 纠错流水线
│ │ ├── mode_decode.rs # 逆向 4 种编码模式
│ │ ├── detect.rs # 定位图案检测 + 采样网格
│ │ └── image.rs # 图像加载 + 二值化
│ ├── matrix/
│ │ ├── grid.rs # 模块矩阵 (含 reserved 保留区)
│ │ ├── patterns.rs # 定位/对齐/时序图案 + BCH(15,5) + BCH(18,6)
@@ -122,6 +135,7 @@ QRGen/
|---------|------|--------|------|
| `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 字节 |
| `decode_qr` | `image_bytes: Vec<u8>` | `Result<String, String>` | 解码图片为文本 |
| `save_history` | `entry: HistoryEntry` | `Result<(), String>` | 添加历史记录（最多 50 条） |
| `load_history` | — | `Result<Vec<HistoryEntry>, String>` | 加载全部历史记录 |
| `clear_history` | — | `Result<(), String>` | 清空历史记录 |
@@ -132,6 +146,7 @@ QRGen/
|----------|------|------|
| `GET /` | — | HTML 页面（内嵌 7 种编码模式） |
| `GET /api/qr` | `text`, `level`(L/M/Q/H), `margin`(1-20), `size`(2-20), `fmt`(svg) | PNG 或 SVG |
| `POST /api/decode` | multipart `file` (PNG/JPEG/WebP) | JSON `{text, version, level, mask, errors_corrected}` |
## 前端状态管理
@@ -181,9 +196,9 @@ Action: SET_MODE | SET_FORM_DATA | SET_CONFIG | SET_PREVIEW | SET_LOADING
| 层级 | 数量 | 说明 |
|------|------|------|
| 单元测试 | 58 | Galois 运算、RS 编码、模式编码、掩码评分、格式信息等 |
| 单元测试 | 72 | Galois 运算、RS 编解码、模式编解码、掩码评分、格式/版本信息 roundtrip、BCH 容错、蛇形提取等 |
| 集成测试 | 24 | 端到端编码、渲染输出验证、边距、特殊字符、自动版本选择、格式信息 roundtrip |
| 总计 | 82 | `cargo test` 全部通过 |
| 总计 | 96 | `cargo test` 全部通过 |
## 版本号升级清单
README.md
+20 -5
View File
@@ -1,6 +1,6 @@
<p align="center">
<h1>🀫 QRGen</h1>
<p>从零手搓的 QR 码生成器 — ISO/IEC 18004 完整实现</p>
<p>从零手搓的 QR 码生成/解码器 — ISO/IEC 18004 完整实现</p>
</p>
<p align="center">
@@ -11,7 +11,7 @@
<img src="https://img.shields.io/badge/axum-0.8-ff6b35" alt="axum">
<img src="https://img.shields.io/badge/docker-ready-2496ed" alt="docker">
<img src="https://img.shields.io/badge/license-MIT-green" alt="license">
<img src="https://img.shields.io/badge/tests-58%20passed-brightgreen" alt="tests">
<img src="https://img.shields.io/badge/tests-72%20passed-brightgreen" alt="tests">
<img src="https://img.shields.io/badge/clippy-clean-brightgreen" alt="clippy">
<img src="https://img.shields.io/badge/prettier-formatted-ff69b4" alt="prettier">
<img src="https://img.shields.io/badge/eslint-checked-4b32c3" alt="eslint">
@@ -22,9 +22,9 @@
## 简介
QRGen 是 **从零手写** 的 QR 码（二维码）生成器，完整实现 ISO/IEC 18004 国际标准。不依赖任何第三方 QR 编码库，所有算法（Galois 域运算、Reed-Solomon 纠错编码、BCH 格式编码、掩码评分）均从底层手搓。
QRGen 是 **从零手写** 的 QR 码（二维码）生成/解码器，完整实现 ISO/IEC 18004 国际标准。不依赖任何第三方 QR 编码/解码库，所有算法（Galois 域运算、Reed-Solomon 纠错编解码、BCH 格式编解码、掩码评分、定位检测）均从底层手搓。
支持 **四种使用方式**：程序库（`qr-core`）、命令行（`qrgen`）、桌面 GUI（`qrgen-gui`）、Web 服务（`qrgen-web`）。
支持 **四种使用方式**：程序库（`qr-core`）、命令行（`qrgen`）、桌面 GUI（`qrgen-gui`）、Web 服务（`qrgen-web`）。支持**编码**（文本→QR）和**解码**（QR→文本）双向闭环。
## 架构
@@ -120,11 +120,15 @@ qrgen "https://example.com" -o qr.png -s 8
# 生成 SVG（高纠错）
qrgen "重要数据" -o qr.svg -l H
# 解码 QR 码图片
qrgen --decode qr.png
```
### GUI 桌面应用
- **7 种编码模式**：文本 / URL / WiFi / vCard / Email / 电话 / SMS
- **解码**：选择图片文件，解码 QR 码为文本
- **实时预览**：200ms 防抖，PNG 即时渲染
- **多格式导出**：PNG（可调模块大小）/ SVG / 复制到剪贴板
- **历史记录**：最近 50 条，点击回填，支持删除和清空
@@ -134,7 +138,7 @@ qrgen "重要数据" -o qr.svg -l H
### Web 服务
- **内嵌 HTML 界面**：复刻 GUI 三栏布局，7 种编码模式
- **REST API**：`GET /api/qr?text=&level=&margin=&size=&fmt=svg` → PNG / SVG
- **REST API**：`GET /api/qr` → PNG / SVG；`POST /api/decode` → 上传图片返回文本
- **Docker 部署**：17.7MB Alpine 镜像，开箱即用
## 安装
@@ -234,6 +238,16 @@ QRGen/
│ ├── ecc/
│ │ ├── galois.rs # GF(2⁸) 运算 + exp/log 表
│ │ └── reed_solomon.rs # RS 纠错码 + 数据交错
│ ├── decoder/ # QR 解码器（从零手写）
│ │ ├── mod.rs # 顶层 API：decode_image + decode_matrix
│ │ ├── bch.rs # BCH(15,5)+BCH(18,6) 查表解码
│ │ ├── format.rs # 格式信息 + 版本信息读取
│ │ ├── extract.rs # 逆向蛇形排列提取码字
│ │ ├── deinterleave.rs # 逆向 RS 数据交错
│ │ ├── rs_decode.rs # RS 纠错（伴随式→BM→Chien→Forney）
│ │ ├── mode_decode.rs # 逆向 4 种编码模式
│ │ ├── detect.rs # 定位图案检测 + 采样网格
│ │ └── image.rs # 图像加载 + 二值化
│ ├── encoder/
│ │ ├── mode.rs # 4 种编码模式
│ │ ├── segment.rs # 字符串分段
@@ -283,6 +297,7 @@ QRGen/
| 编码模式 | 数字 / 字母数字 / 字节 / 汉字 (Shift JIS) |
| 输出格式 | PNG / SVG / 终端 ASCII |
| 使用方式 | Library / CLI / GUI / Web API |
| 解码 | 从图片识读 QR 码 → 文本（PNG/JPEG/WebP） |
| 自动版本选择 | 根据数据长度 + 纠错级别 |
| Docker 镜像 | ~18MB (alpine) |
ROADMAP.md
+10 -6
View File
@@ -14,8 +14,8 @@ QRGen 的未来发展方向。
## v0.3.0
- [ ] **QR 解码** — 内置 QR 码解码器（从图片识别 QR 内容）
- [ ] **格式扩展** — 支持 BMP/JPEG/WEBP 输出
- [ ] **解码增强** — 斜拍/旋转图像矫正、模糊图像增强
- [ ] **WiFi 扫码自动连接** — 移动端扫码后一键连接 WiFi
- [ ] **vCard 扩展** — 支持更多字段（照片、社交媒体等）
- [ ] **macOS 桌面应用** — Tauri macOS 构建支持
@@ -35,11 +35,15 @@ QRGen 的未来发展方向。
- ✅ ISO/IEC 18004 完整 QR 码生成算法
- ✅ 4 种编码模式（数字/字母/字节/汉字 Shift JIS）
- ✅ 40 版本 × 4 纠错级别支持
- ✅ CLI 命令行工具（PNG/SVG/ASCII 输出）
- ✅ GUI 桌面应用（Tauri 2 + React 18，7 种编码模式）
- ✅ Web 服务（axum + Docker alpine 17.7MB 镜像）
- ✅ 82 个 Rust 测试
- ✅ 社区规范文件（CONTRIBUTING / CODE_OF_CONDUCT / SECURITY）
- ✅ CLI 命令行工具（PNG/SVG/ASCII 输出 + `--decode` 解码）
- ✅ GUI 桌面应用（Tauri 2 + React 18，7 种编码模式 + 解码）
- ✅ Web 服务（axum + Docker alpine 17.7MB 镜像 + `/api/decode`）
- ✅ QR 解码器（从零手写：定位→提取→RS纠错→模式解码，PNG/JPEG/WebP）
- ✅ RS 纠错解码（伴随式→Berlekamp-Massey→Chien→Forney）
- ✅ 96 个 Rust 测试（72 单元 + 24 集成）
- ✅ 前端工程化（Prettier + ESLint + vitest + husky + commitlint）
- ✅ crates.io 就绪（doc comments + 元数据 + 代码示例）
- ✅ 社区规范文件（CONTRIBUTING / CODE_OF_CONDUCT / SECURITY / ROADMAP / SUPPORT）
---