# QR 码生成器 — 设计文档

**日期**: 2026-06-16  
**作者**: 刘航宇  
**语言**: Rust  
**项目路径**: `D:\Code\doing_exercises\programs\QRGen\`

## 1. 项目概述

从零实现 ISO/IEC 18004 QR 码生成器，不依赖任何第三方 QR 编码库。算法全手写，
输出 PNG / SVG / 终端 ASCII。后续扩展 Tauri GUI。

## 2. 支持范围

| 维度 | 范围 |
|------|------|
| **QR 版本** | 1~40（21×21 ~ 177×177 模块） |
| **纠错级别** | L (7%), M (15%), Q (25%), H (30%) |
| **编码模式** | 数字 / 字母数字 / 字节 / 汉字 (Shift JIS) |
| **输出格式** | PNG（`image` crate）、SVG、终端 ASCII |
| **自动版本选择** | 根据数据长度 + 纠错级别自动选最小版本 |

## 3. 项目结构

```
QRGen/
├── Cargo.toml          # workspace: core + cli
├── core/               # 纯算法库，尽量零依赖
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs
│       ├── qr.rs           # 顶层 API
│       ├── version.rs      # 版本参数表 (40 行硬编码)
│       ├── encoder/
│       │   ├── mod.rs
│       │   ├── mode.rs     # 编码模式定义
│       │   ├── segment.rs  # 数据分段与模式选择
│       │   └── bitstream.rs # 比特流拼接
│       ├── ecc/
│       │   ├── mod.rs
│       │   ├── galois.rs   # GF(2⁸) 运算 + 预计算表
│       │   └── reed_solomon.rs  # RS 纠错码生成
│       ├── matrix/
│       │   ├── mod.rs
│       │   ├── grid.rs     # 模块网格数据结构
│       │   ├── patterns.rs # 定位/对齐/时序图案
│       │   ├── placement.rs # 数据字节蛇形排列
│       │   └── mask.rs     # 8 种掩码 + 评分
│       └── render/
│           ├── mod.rs
│           ├── png.rs      # PNG 渲染 (image crate)
│           ├── svg.rs      # SVG 渲染
│           └── ascii.rs    # 终端 ASCII 渲染
├── cli/               # CLI 工具
│   ├── Cargo.toml
│   └── src/
│       └── main.rs
└── docs/
    └── superpowers/specs/
```

## 4. 数据流水线

```
输入字符串
  → 数据分析 (mode.rs + segment.rs)      → Vec<Segment>
  → 版本选择 (version.rs)                → Version (1~40)
  → 比特流编码 (bitstream.rs)            → Vec<u8> (data codewords)
  → RS 纠错编码 (reed_solomon.rs)        → Vec<u8> (final sequence)
  → 模块布局 (matrix/)                   → Matrix (bitmap)
  → 掩码评分 (mask.rs)                   → Matrix (best mask)
  → 渲染输出 (render/)                   → PNG / SVG / ASCII
```

### 4.1 数据分析

1. 扫描输入字符串，分析字符集
2. 根据字符分布选择最优编码模式（混合内容自动分段）
3. 每段包含：模式指示符 + 字符计数 + 编码数据

### 4.2 版本选择

硬编码 ISO 18004 附录中的容量表（40 版本 × 4 纠错级别），
根据总比特数查表选最小合适版本。用户可手动覆盖。

### 4.3 比特流编码

- 各段按模式规则编码为比特
- 添加终止符（最多 4 bit）
- 补零到 8-bit 边界
- 填充码字 0xEC/0x11 交替至满容量

### 4.4 RS 纠错编码

- GF(2⁸) 基于 `x⁸ + x⁴ + x³ + x² + 1` (0x11D)
- 预计算 exp/log 表加速乘除法
- 生成多项式动态构造
- 多项式长除法求余数（纠错码字）

### 4.5 模块布局

1. 绘制空白矩阵
2. 放置定位图案（3 个角）
3. 放置对齐图案（版本相关数量）
4. 放置时序图案 + 暗模块
5. 保留格式信息区域（15 bit）
6. 保留版本信息区域（版本 ≥ 7，18 bit）
7. 按蛇形路径填入数据比特
8. 尝试 8 种掩码，对每种：
   - 计算格式信息
   - 若版本 ≥ 7 计算版本信息
   - 评分
9. 选最低惩罚分掩码，写入最终格式/版本信息

### 4.6 掩码评分规则

| 规则 | 条件 | 惩罚 |
|------|------|------|
| 规则 1 | 连续 5+ 同色行/列 | N1 + k-5 |
| 规则 2 | 同色 2×2 方块 | 每块 +3 |
| 规则 3 | `1011101` 模式 | 每次 +40 |
| 规则 4 | 暗模块占比偏离 50% | 每 5% +10 |

### 4.7 渲染输出

- **PNG**: 依赖 `image` crate，逐模块像素填充，可调模块大小 + 白边
- **SVG**: 纯字符串拼接，无依赖，`<rect>` 逐模块
- **ASCII**: 终端输出，`██` / `  ` 双字符渲染，利用 Unicode 半方块实现近似正方形

## 5. CLI 接口

```
qrgen "content" [options]

Options:
  -o, --output <FILE>   输出文件（.png/.svg），不指定则终端 ASCII
  -l, --level <LEVEL>   纠错级别 L/M/Q/H [default: M]
  -v, --version <VER>   手动指定版本 (1-40)，不指定则自动
  -s, --size <PX>       模块像素大小（PNG） [default: 4]
  -m, --margin <N>      白边模块数 [default: 4]
  --mode <MODE>         强制编码模式 [auto]
  --invert              反色
  -h, --help            帮助
```

示例：
```bash
qrgen "https://example.com"                    # 终端 ASCII
qrgen "hello" -o qr.png -s 10                  # 大模块 PNG
qrgen "data" -o qr.svg -l H                    # SVG, 高纠错
qrgen "12345" --mode numeric -v 5              # 纯数字, 版本5
```

## 6. 核心 API（core/lib.rs）

```rust
pub struct QrConfig {
    pub level: EcLevel,          // 默认 M
    pub version: VersionMode,    // 默认 Auto
    pub mode: ModeHint,          // 默认 Auto（混合自动分段）
    pub margin: u8,              // 默认 4
}

pub enum VersionMode {
    Auto,
    Fixed(u8),
}

pub struct QrCode {
    // 内部持有最终的 Matrix + 版本/级别元数据
}

impl QrCode {
    /// 编码字符串，失败返回 Err
    pub fn encode(text: &str, config: QrConfig) -> Result<Self>;

    /// 导出为 PNG bytes
    pub fn to_png(&self, module_size: u8) -> Vec<u8>;

    /// 导出为 SVG 字符串
    pub fn to_svg(&self) -> String;

    /// 导出为 ASCII 字符串
    pub fn to_ascii(&self, invert: bool) -> String;

    /// 获取原始模块矩阵（供外部渲染使用）
    pub fn modules(&self) -> &[Vec<bool>];
}
```

## 7. 测试策略

| 层级 | 内容 | 覆盖率目标 |
|------|------|-----------|
| **单元测试** | GF(2⁸) 运算、RS 编码、模式编码、掩码评分 | ≥ 80% |
| **集成测试** | 已知字符串 → 生成的 PNG 被 zxing 解码验证 | 关键路径 |
| **回归测试** | 固定输入 → 固定矩阵黄金数据（标准附录参考值） | 关键算法 |
| **属性测试** | 随机字符串 → 编码解码往返 | 可选 |

## 8. 不实现的范围（明确排除）

- Micro QR Code
- QR Code 解码（本项目只管生成）
- 结构化附加（Structured Append）
- FNC1 模式
- ECI 编码指示符
- 艺术 QR 码（带 logo 嵌入等）

## 9. 里程碑

1. **M1**: GF(2⁸) + Reed-Solomon — 最核心算法
2. **M2**: 编码 + 比特流 — 能产出有效码字序列
3. **M3**: 矩阵布局 + 掩码 — 能产出完整 QR 矩阵
4. **M4**: 渲染输出 — PNG + SVG + ASCII
5. **M5**: CLI — 完整的命令行工具