From 4dc5f62b2ef77deef88874dd7a003755d9fcc1b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E8=88=AA=E5=AE=87?= <3364451258@qq.com> Date: Fri, 19 Jun 2026 15:24:50 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README=20+=20CHANG?= =?UTF-8?q?ELOG=20=E2=80=94=20web=20=E7=AB=AF=20/=20Docker=20/=20=E4=BF=AE?= =?UTF-8?q?=E5=A4=8D=E8=AE=B0=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: 四种使用方式,新增 Web 服务/Docker 章节 - CHANGELOG: 完整的 Fixed 列表 (14 项修复) - 测试数 69→82, Docker badge, axum badge Co-Authored-By: Claude --- CHANGELOG.md | 45 +++++++++++++++++++++------- README.md | 84 ++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 96 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 26d9b4d..78897bc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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` 改为 `` + 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） diff --git a/README.md b/README.md index c690c85..3cb0f7d 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,11 @@ version tauri react + axum rust - typescript + docker license - tests + tests

--- @@ -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 页面
三栏 + 7 模式 + 实时预览] + API[/api/qr → PNG/SVG] + end + subgraph CLI["CLI 命令行"] Clap[clap 参数解析] end - subgraph IPC["Tauri IPC 桥接"] - Commands[encode_qr / export_png
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) | ## 许可证