diff --git a/README.md b/README.md
index f10582f..4234844 100644
--- a/README.md
+++ b/README.md
@@ -44,23 +44,25 @@ graph TB
 
     subgraph Web["Web 服务 (axum)"]
         HTML[内嵌 HTML 页面]
-        API[GET /api/qr]
+        API[GET /api/qr + POST /api/decode]
     end
 
     subgraph CLI["CLI 命令行"]
-        Clap[clap 参数解析]
+        Clap[clap 编码 + --decode 解码]
     end
 
     subgraph IPC["Tauri IPC 桥接"]
-        Commands[5 个 Tauri commands]
+        Commands[6 个 Tauri commands]
     end
 
     subgraph Core["Rust core 库 (qr-core)"]
         Encoder[编码层]
+        Decoder[解码层]
         ECC[纠错层]
         Matrix[矩阵层]
         Render[渲染层]
         Encoder --> ECC
+        Decoder --> ECC
         ECC --> Matrix
         Matrix --> Render
     end
@@ -94,6 +96,19 @@ sequenceDiagram
     M->>M: 功能图案 + 蛇形排列 + 掩码
     M->>R: QR 矩阵
     R->>UI: PNG / SVG / ASCII
+
+    Note over U,R: --- 解码流水线 (逆向) ---
+
+    U->>UI: 上传图片
+    UI->>Q: decode_image(bytes)
+    Q->>R: 图像二值化 + 定位图案检测
+    R->>M: 布尔矩阵
+    M->>M: 读取格式/版本信息 + 解掩码 + 蛇形提取
+    M->>RS: 数据码字 + 纠错码字
+    RS->>RS: 去交错 + 伴随式 + Berlekamp-Massey + Chien + Forney
+    RS->>E: 纠错后数据码字
+    E->>E: 模式解码(数字/字母/字节/汉字)
+    E->>UI: 解码文本
 ```
 
 ## 功能
@@ -192,7 +207,7 @@ cargo run -p qrgen -- "Hello World"
 cargo run -p qrgen-web              # → http://localhost:3000
 
 # Rust 测试
-cargo test                          # 58 unit
+cargo test --lib                    # 72 unit
 
 # 前端测试
 cd gui/src-frontend && pnpm test    # vitest
@@ -267,7 +282,7 @@ QRGen/
 │   ├── capabilities/default.json # ACL 权限
 │   ├── src/
 │   │   ├── main.rs               # Windows 子系统入口
-│   │   └── lib.rs                # 5 个 Tauri commands
+│   │   └── lib.rs                # 6 个 Tauri commands
 │   ├── src-frontend/             # React 前端
 │   │   └── src/
 │   │       ├── App.tsx           # 主布局（三栏+底部输入）
@@ -316,15 +331,21 @@ cargo run --example high_ecc
 cargo run --example custom_config
 ```
 
-作为程序库使用：
+作为程序库使用（编码 + 解码）：
 
 ```rust
 use qr_core::qr::{QrCode, QrConfig};
+use qr_core::decoder;
 
+// 编码：文本 → QR
 let qr = QrCode::encode("Hello QR!", QrConfig::default())?;
-println!("{}", qr.to_ascii(false));     // 终端预览
 qr.to_png_bytes(8)?;                     // PNG 字节
 let svg = qr.to_svg();                   // SVG 字符串
+
+// 解码：QR 图片 → 文本
+let bytes = std::fs::read("qr.png")?;
+let result = decoder::decode_image(&bytes)?;
+println!("解码结果: {}", result.text);
 ```
 
 ## 发布到 crates.io