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

docs: 更新 README + CHANGELOG — web 端 / Docker / 修复记录

Browse Source 
- README: 四种使用方式,新增 Web 服务/Docker 章节
- CHANGELOG: 完整的 Fixed 列表 (14 项修复)
- 测试数 69→82, Docker badge, axum badge

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
刘航宇
2026-06-19 15:24:50 +08:00
parent 15b3119588
commit 4dc5f62b2e
2 changed files with 96 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+34 -11
View File
@@ -1,6 +1,6 @@
# Changelog
## 0.1.0 (2026-06-17)
## 0.1.0 (2026-06-18)
### Added
@@ -9,31 +9,54 @@
- Reed-Solomon 纠错编码（动态生成多项式 + 多项式长除法 + 数据交错）
- 四种编码模式：数字 / 字母数字 / 字节 / 汉字 (Shift JIS)
- 字符串自动分段 + 最优模式选择
- 8 种标准掩码 + 四规则惩罚评分（连续同色/2×2方块/伪定位图案/暗模块占比）
- 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 渲染）
- 实时预览（200ms 防抖）、历史记录（50 条 + 持久化）
- PNG/SVG 导出 + 复制到剪贴板
- 历史记录（最近 50 条，回填/删除/清空）
- 暗色模式（跟随系统）
- 磨砂玻璃效果 (backdrop-blur)
- WiFi 密码脱敏、错误提示
- 暗色模式（跟随系统）、磨砂玻璃效果
- **Web 服务** (`qrgen-web`)
- axum 0.8 + tokio HTTP 服务
- 内嵌 GUI 风格 HTML 页面（三栏 + 7 模式 + 实时预览）
- REST API: `GET /api/qr` → PNG / SVG
- Docker: rust-alpine 多阶段构建 → 17.7MB 镜像
- docker-compose: 资源限制 + 健康检查 + 日志轮转
- **程序库** (`qr-core`)
- 零外部 QR 依赖（仅 image crate 用于 PNG 输出）
- 自动版本选择
- 完整 40 版本 × 四级纠错支持
### Fixed
- **QR 扫描失败**：修复 PNG margin `saturating_sub` 导致 quiet zone 全黑（扫描器无法定位）
- **QR 扫描失败**：修复 finder pattern separator 缺少左侧和顶部预留（数据模块破坏 finder 检测比率 1:1:3:1:1）
- **GUI 导出失败**：修复 `tauri-plugin-fs` 插件未注册（writeFile 调用无后端 handler）
- **GUI 导出 ACL**：修复 `fs:allow-write-file` 缺少路径 scope
- **GUI 预览模糊**：修复 SVG size=1 拉伸到 216px 导致的模糊
- **历史记录**：删除/清空后持久化到 store、WiFi 密码脱敏、点击回填用 formData
- **CSP**：从 null 改为最小权限策略
- **CLI 安全**：添加路径遍历防护
- **Kanji 编码**：修复 Shift JIS 第二字节空洞、fallback 段内模式混用
- **编码器**：`encode_numeric`/`encode_alphanumeric` 添加 debug_assert 前置条件
- **SVG 渲染**：`dangerouslySetInnerHTML` 改为 `<img>` + data URL
- **Web 界面**：预览改用 PNG size=8 避免拉伸模糊
### Technical
- Cargo workspace 三层架构 (core + cli + gui)
- Cargo workspace 四层架构 (core + cli + gui + web)
- Tauri v2 capabilities + ACL 权限配置
- qr-core：Serde 序列化支持（跨 IPC 传输）
- GUI：React Context + useReducer 状态管理
- GUI：React Context + useReducer，共享文本构造工具 (utils/qrText.ts)
- CLI：clap derive + anyhow 错误处理
- 69 个测试（54 单元 + 15 集成）
- NSIS Windows 安装包
- Web：axum 0.8 + tokio，编译期 HTML 嵌入 (include_str!)
- 82 个测试（58 单元 + 24 集成）
- NSIS Windows 安装包 + Docker Alpine 镜像
- GitHub Actions 就绪（测试 + clippy + fmt）
README.md
+62 -22
View File
@@ -7,10 +7,11 @@
<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/axum-0.8-ff6b35" alt="axum">
<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/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-69%20passed-brightgreen" alt="tests">
<img src="https://img.shields.io/badge/tests-82%20passed-brightgreen" alt="tests">
</p>
---
@@ -19,7 +20,7 @@
QRGen 是 **从零手写** 的 QR 码（二维码）生成器，完整实现 ISO/IEC 18004 国际标准。不依赖任何第三方 QR 编码库，所有算法（Galois 域运算、Reed-Solomon 纠错编码、BCH 格式编码、掩码评分）均从底层手搓。
支持 **三种使用方式**：程序库（`qr-core`）、命令行（`qrgen`）、桌面 GUI（`qrgen-gui`）。
支持 **四种使用方式**：程序库（`qr-core`）、命令行（`qrgen`）、桌面 GUI（`qrgen-gui`）、Web 服务（`qrgen-web`）。
## 架构
@@ -37,12 +38,17 @@ graph TB
App --> History
end
subgraph Web["Web 服务 (axum)"]
HTML[内嵌 HTML 页面<br/>三栏 + 7 模式 + 实时预览]
API[/api/qr → PNG/SVG]
end
subgraph CLI["CLI 命令行"]
Clap[clap 参数解析]
end
subgraph IPC["Tauri IPC 桥接"]
Commands[encode_qr / export_png<br/>save_history / load_history / clear_history]
subgraph IPC["Tauri IPC"]
Commands[5 个 Tauri commands]
end
subgraph Core["Rust core 库 (qr-core)"]
@@ -58,6 +64,8 @@ graph TB
Modes --> Commands
Commands --> Encoder
Clap --> Encoder
HTML --> API
API --> Encoder
```
### 数据流水线
@@ -65,7 +73,7 @@ graph TB
```mermaid
sequenceDiagram
actor U as 用户
participant UI as React UI / CLI
participant UI as React UI / CLI / Web
participant Q as QrCode::encode()
participant E as 编码器
participant RS as Reed-Solomon
@@ -108,56 +116,75 @@ 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 即时渲染
- **实时预览**：200ms 防抖，PNG 即时渲染
- **多格式导出**：PNG（可调模块大小）/ SVG / 复制到剪贴板
- **历史记录**：最近 50 条，点击回填，支持删除和清空
- **暗色模式**：跟随系统，磨砂玻璃效果
- **纠错级别可调**：L (7%) / M (15%) / Q (25%) / H (30%)
### Web 服务
- **内嵌 HTML 界面**：复刻 GUI 三栏布局，7 种编码模式
- **REST API**：`GET /api/qr?text=&level=&margin=&size=&fmt=svg` → PNG / SVG
- **Docker 部署**：17.7MB Alpine 镜像，开箱即用
## 安装
从源码构建：
### 从源码构建
```bash
# 克隆
git clone git@lhy-git.liuhangyv.top:Serendipity/QRGen.git
cd QRGen
# 安装前端依赖
cd gui/src-frontend && pnpm install && cd ../..
# 构建 CLI
# CLI
cargo build --release -p qrgen
# 构建 GUI + NSIS 安装包
# 1. 先构建前端
# Web 服务
cargo build --release -p qrgen-web
# GUI + NSIS 安装包
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
> **要求**：Windows 10+（GUI 需 WebView2），Rust 1.95+，Node.js 22+
### Docker（Web 服务）
```bash
# 拉取镜像（或本地构建）
docker build -t qrgen-web -f web/Dockerfile .
# 运行
docker run -d --name qrgen-web --restart unless-stopped -p 3000:3000 qrgen-web
# docker-compose
# 见 G:\qrgen-web\docker-compose.yaml（NAS 部署用）
```
## 开发
```bash
# 开发模式 GUI（热更新，需先 pnpm install）
# 开发模式 GUI（热更新）
cd gui/src-frontend && pnpm dev # 终端1: 前端
cargo run -p qrgen-gui # 终端2: Rust 后端
# CLI 开发
cargo run -p qrgen -- "Hello World"
# Web 开发
cargo run -p qrgen-web # → http://localhost:3000
# 全部测试
cargo test # Rust: 69 tests
cargo test # Rust: 82 tests
# 前端类型检查
cd gui/src-frontend && pnpm tsc --noEmit
@@ -174,10 +201,12 @@ cargo clippy -- -D warnings
| GUI 前端 | React 18 + TypeScript (strict) |
| UI 样式 | TailwindCSS 3 |
| 状态管理 | React Context + useReducer |
| Web 服务 | axum 0.8 + tokio |
| 核心库 | Rust (qr-core) |
| CLI | clap + anyhow |
| 前端包管理 | pnpm |
| 打包 | NSIS |
| 桌面打包 | NSIS |
| 容器化 | Docker (alpine, 17.7MB) |
### 项目结构
@@ -206,6 +235,7 @@ QRGen/
├── cli/ # CLI 命令行工具
│ └── src/main.rs # clap 参数解析
├── gui/ # Tauri 桌面应用
│ ├── capabilities/default.json # ACL 权限
│ ├── src/
│ │ ├── main.rs # Windows 子系统入口
│ │ └── lib.rs # 5 个 Tauri commands
@@ -216,9 +246,17 @@ QRGen/
│ │ ├── modes/ # 7 种模式表单
│ │ ├── hooks/ # useQrEncode（防抖+编码）
│ │ ├── store/ # Context + useReducer
│ │ └── types/ # TypeScript 类型
│ │ ├── types/ # TypeScript 类型
│ │ └── utils/ # qrText.ts 文本构造工具
│ └── tauri.conf.json # 窗口 + NSIS 打包配置
└── Cargo.toml # Workspace: core + cli + gui
├── web/ # Web 服务
│ ├── Dockerfile # rust-alpine 多阶段构建
│ ├── src/
│ │ ├── main.rs # axum HTTP 服务
│ │ └── templates/
│ │ └── index.html # 内嵌 GUI 风格页面
├── .dockerignore
└── Cargo.toml # Workspace: core + cli + gui + web
```
## 支持规格
@@ -229,7 +267,9 @@ QRGen/
| 纠错级别 | L (7%) / M (15%) / Q (25%) / H (30%) |
| 编码模式 | 数字 / 字母数字 / 字节 / 汉字 (Shift JIS) |
| 输出格式 | PNG / SVG / 终端 ASCII |
| 使用方式 | Library / CLI / GUI / Web API |
| 自动版本选择 | 根据数据长度 + 纠错级别 |
| Docker 镜像 | ~18MB (alpine) |
## 许可证