diff --git a/CHANGELOG.md b/CHANGELOG.md
index e82a67b..e306b19 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -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 模板
diff --git a/CLAUDE.md b/CLAUDE.md
index 6f6f537..aca7ea0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -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` 全部通过 |
 
 ## 版本号升级清单
 
diff --git a/README.md b/README.md
index 652602f..f10582f 100644
--- a/README.md
+++ b/README.md
@@ -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) |
 
diff --git a/ROADMAP.md b/ROADMAP.md
index defef89..f1bfec5 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -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）
 
 ---