From 7f3b8b4cc77c5ee46c6d7ad0eeb1da815ccb8eb7 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 21:41:49 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E5=85=A8=E9=83=A8=20?=
=?UTF-8?q?markdown=20=E6=96=87=E6=A1=A3=20=E2=80=94=20v0.3.0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- README: 测试数 81、输出格式表 + vCard 10字段、透视矫正、格式扩展
- CHANGELOG: v0.3.0 条目（格式扩展+解码增强+vCard扩展）
- ROADMAP: v0.2.0/v0.3.0 移至已交付，更新下一版本规划
- CLAUDE.md: 测试 81→105、perspective.rs 模块、Web fmt 参数
---
CHANGELOG.md | 26 +++++++++++++++++++++++++-
CLAUDE.md | 7 ++++---
README.md | 11 ++++++-----
ROADMAP.md | 33 +++++++++++++++++++++------------
4 files changed, 56 insertions(+), 21 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e306b19..651b551 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,29 @@
# Changelog
+## 0.3.0 (2026-06-19)
+
+### Added
+
+- **格式扩展** — 新增 BMP/JPEG/WebP 图像输出
+ - `core/src/render/image.rs`：`OutputFormat` 枚举 (Png/Bmp/Jpeg/WebP)
+ - `QrCode::to_image_bytes()` — 参数化格式输出
+ - CLI `-f`/`--format` (png/bmp/jpeg/webp)
+ - Web API `fmt` 参数扩展至全部 4 种格式
+- **解码增强** — 透视矫正
+ - `core/src/decoder/perspective.rs`：旋转矫正流水线
+ - 自动检测 finder → 计算旋转角 → 仿射变换 → 再解码
+ - `decode_image` 自动重试矫正路径
+- **vCard 扩展** — 新增 5 字段
+ - TITLE（职位）/ URL（网址）/ BDAY（生日）/ NOTE（备注）/ PHOTO（照片）
+ - Rust `text_builder` + TypeScript `qrText` + VCardMode UI 同步
+ - CLI 新增 `--title` `--vcard-url` `--birthday` `--note` `--photo`
+ - 中/英 i18n 翻译
+
+### Changed
+
+- `core/src/render/png.rs` → `image.rs`（格式无关化）
+- `QrCode::to_png_bytes` 保留为 `to_image_bytes` 的便捷方法
+
## 0.1.0 (2026-06-19)
### Added
@@ -65,7 +89,7 @@
- GUI：React Context + useReducer，共享文本构造工具 (utils/qrText.ts)
- CLI：clap derive + anyhow 错误处理
- Web：axum 0.8 + tokio，编译期 HTML 嵌入 (include_str!)
-- 96 个测试（72 单元 + 24 集成）
+- 105 个测试（81 单元 + 24 集成）
- NSIS Windows 安装包 + Docker Alpine 镜像
- 文档：API doc comments（rustdoc 可用）+ 3 个代码示例
- 社区：CONTRIBUTING / CODE_OF_CONDUCT / SECURITY / Issue & PR 模板
diff --git a/CLAUDE.md b/CLAUDE.md
index aca7ea0..c815b86 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -89,6 +89,7 @@ QRGen/
│ │ ├── rs_decode.rs # RS 纠错流水线
│ │ ├── mode_decode.rs # 逆向 4 种编码模式
│ │ ├── detect.rs # 定位图案检测 + 采样网格
+│ │ ├── perspective.rs # 透视矫正（旋转+仿射变换）
│ │ └── image.rs # 图像加载 + 二值化
│ ├── matrix/
│ │ ├── grid.rs # 模块矩阵 (含 reserved 保留区)
@@ -145,7 +146,7 @@ QRGen/
| Endpoint | 参数 | 返回 |
|----------|------|------|
| `GET /` | — | HTML 页面（内嵌 7 种编码模式） |
-| `GET /api/qr` | `text`, `level`(L/M/Q/H), `margin`(1-20), `size`(2-20), `fmt`(svg) | PNG 或 SVG |
+| `GET /api/qr` | `text`, `level`(L/M/Q/H), `margin`(1-20), `size`(2-20), `fmt`(png/bmp/jpeg/webp/svg) | PNG/BMP/JPEG/WebP/SVG |
| `POST /api/decode` | multipart `file` (PNG/JPEG/WebP) | JSON `{text, version, level, mask, errors_corrected}` |
## 前端状态管理
@@ -196,9 +197,9 @@ Action: SET_MODE | SET_FORM_DATA | SET_CONFIG | SET_PREVIEW | SET_LOADING
| 层级 | 数量 | 说明 |
|------|------|------|
-| 单元测试 | 72 | Galois 运算、RS 编解码、模式编解码、掩码评分、格式/版本信息 roundtrip、BCH 容错、蛇形提取等 |
+| 单元测试 | 81 | Galois 运算、RS 编解码、模式编解码、掩码评分、格式/版本信息 roundtrip、BCH 容错、蛇形提取、vCard 扩展等 |
| 集成测试 | 24 | 端到端编码、渲染输出验证、边距、特殊字符、自动版本选择、格式信息 roundtrip |
-| 总计 | 96 | `cargo test` 全部通过 |
+| 总计 | 105 | `cargo test` 全部通过 |
## 版本号升级清单
diff --git a/README.md b/README.md
index 4234844..07a4c1b 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@
- 
+ 
@@ -142,7 +142,7 @@ qrgen --decode qr.png
### GUI 桌面应用
-- **7 种编码模式**：文本 / URL / WiFi / vCard / Email / 电话 / SMS
+- **7 种编码模式**：文本 / URL / WiFi / vCard(10字段) / Email / 电话 / SMS
- **解码**：选择图片文件，解码 QR 码为文本
- **实时预览**：200ms 防抖，PNG 即时渲染
- **多格式导出**：PNG（可调模块大小）/ SVG / 复制到剪贴板
@@ -207,7 +207,7 @@ cargo run -p qrgen -- "Hello World"
cargo run -p qrgen-web # → http://localhost:3000
# Rust 测试
-cargo test --lib # 72 unit
+cargo test --lib # 81 unit
# 前端测试
cd gui/src-frontend && pnpm test # vitest
@@ -310,9 +310,10 @@ QRGen/
| QR 版本 | 1 ~ 40（21×21 ~ 177×177 模块） |
| 纠错级别 | L (7%) / M (15%) / Q (25%) / H (30%) |
| 编码模式 | 数字 / 字母数字 / 字节 / 汉字 (Shift JIS) |
-| 输出格式 | PNG / SVG / 终端 ASCII |
+| 输出格式 | PNG / BMP / JPEG / WebP / SVG / 终端 ASCII |
+| vCard 字段 | 姓名/电话/邮箱/公司/职位/地址/网址/生日/备注/照片 (10 字段) |
| 使用方式 | Library / CLI / GUI / Web API |
-| 解码 | 从图片识读 QR 码 → 文本（PNG/JPEG/WebP） |
+| 解码 | 从图片识读 QR 码 → 文本（支持旋转矫正） |
| 自动版本选择 | 根据数据长度 + 纠错级别 |
| Docker 镜像 | ~18MB (alpine) |
diff --git a/ROADMAP.md b/ROADMAP.md
index f1bfec5..d20ddc6 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -2,23 +2,17 @@
QRGen 的未来发展方向。
-## v0.2.0 (下一个版本)
+## v0.3.0 (下一个版本)
-- [ ] **CLI 编码模式** — CLI 支持 `--mode wifi` 等子命令，免去手动拼 `WIFI:T:...`
-- [ ] **Logo 嵌入** — QR 码中央嵌入自定义图片（Logo/头像）
-- [ ] **彩色 QR 码** — 自定义前景色/背景色，渐变色支持
-- [ ] **批量生成** — 从 CSV/JSON 批量生成 QR 码
-- [ ] **前端测试** — vite + vitest + React Testing Library，80% 覆盖率
- [ ] **E2E 测试** — Playwright 端到端测试（编码 → 导出 → 历史）
-- [ ] **i18n** — 中英双语界面 (i18next)
+- [ ] **解码增强 v2** — 完整透视变换（单应矩阵），模糊图像增强
+- [ ] **PWA 支持** — Web 端可安装为 PWA，离线使用
-## v0.3.0
+## v0.4.0 (未来)
-- [ ] **格式扩展** — 支持 BMP/JPEG/WEBP 输出
-- [ ] **解码增强** — 斜拍/旋转图像矫正、模糊图像增强
- [ ] **WiFi 扫码自动连接** — 移动端扫码后一键连接 WiFi
-- [ ] **vCard 扩展** — 支持更多字段（照片、社交媒体等）
- [ ] **macOS 桌面应用** — Tauri macOS 构建支持
+- [ ] **跨平台 GUI** — 完整的 Windows + macOS + Linux 桌面应用发布
## v1.0.0 (长期)
@@ -30,6 +24,21 @@ QRGen 的未来发展方向。
## 已交付
+### v0.3.0
+
+- ✅ 格式扩展（BMP/JPEG/WebP 输出 + `OutputFormat` 枚举）
+- ✅ 解码增强（旋转矫正 + 自动重试矫正流水线）
+- ✅ vCard 扩展（10 字段：TITLE/URL/BDAY/NOTE/PHOTO）
+
+### v0.2.0
+
+- ✅ 彩色 QR 码（前景色/背景色 + PNG Rgba + SVG + CLI `--fg`/`--bg`）
+- ✅ Logo 嵌入（PNG `imageops::overlay` + SVG base64）
+- ✅ CLI 编码模式（`--mode wifi/vcard/email/phone/sms`）
+- ✅ 批量生成（JSON/CSV 输入 → 自动编号输出）
+- ✅ i18n 中英双语（i18next + react-i18next）
+- ✅ 前端测试（19 tests，vitest + @vitest/coverage-v8）
+
### v0.1.0
- ✅ ISO/IEC 18004 完整 QR 码生成算法
@@ -40,7 +49,7 @@ QRGen 的未来发展方向。
- ✅ Web 服务（axum + Docker alpine 17.7MB 镜像 + `/api/decode`）
- ✅ QR 解码器（从零手写：定位→提取→RS纠错→模式解码，PNG/JPEG/WebP）
- ✅ RS 纠错解码（伴随式→Berlekamp-Massey→Chien→Forney）
-- ✅ 96 个 Rust 测试（72 单元 + 24 集成）
+- ✅ 105 个 Rust 测试（81 单元 + 24 集成）
- ✅ 前端工程化（Prettier + ESLint + vitest + husky + commitlint）
- ✅ crates.io 就绪（doc comments + 元数据 + 代码示例）
- ✅ 社区规范文件（CONTRIBUTING / CODE_OF_CONDUCT / SECURITY / ROADMAP / SUPPORT）