QRGen/docs/CLI_USAGE.md

# QRGen CLI 使用手册

`qrgen` 是 QRGen 的命令行工具，支持 QR 码的**编码**（文本 → QR 图）和**解码**（QR 图 → 文本），输出 PNG/BMP/JPEG/WebP/SVG/终端 ASCII 六种格式。

## 快速开始

```bash
# 终端预览 QR 码
qrgen encode "Hello World"

# 生成 PNG
qrgen encode "https://example.com" -o qr.png

# 生成 SVG
qrgen encode "重要数据" -o qr.svg -l H

# 解码 QR 图片
qrgen decode qr.png
```

---

## 基础编码

### 语法

```bash
qrgen encode [OPTIONS] [CONTENT]
qrgen decode [FILE]
```

### 选项

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `-o, --output <文件>` | 输出文件路径（.png/.bmp/.jpg/.webp/.svg） | 终端 ASCII 输出 |
| `-l, --level <级别>` | 纠错级别：`L`(7%) `M`(15%) `Q`(25%) `H`(30%) | `M` |
| `-v, --version <1-40>` | 手动指定 QR 版本 | 自动选择 |
| `-s, --size <像素>` | 每个模块的像素大小（图像输出） | `4` |
| `-m, --margin <模块>` | 白边宽度（模块数） | `4` |
| `-f, --format <格式>` | 图像输出格式：`png` `bmp` `jpeg` `webp` | 从文件扩展名推断 |
| `--fg <颜色>` | 前景色 `#RRGGBB` 或 `#RGB` | `#000` |
| `--bg <颜色>` | 背景色 `#RRGGBB` 或 `#RGB` | `#FFF` |
| `--logo <文件>` | 在 QR 码中央叠加 Logo 图片 | 无 |
| `--invert` | 反色输出（终端 ASCII） | — |

### 示例

```bash
# 基础生成
qrgen encode "Hello World" -o hello.png

# 高纠错 + 大尺寸
qrgen encode "重要合同编号: ABC-12345678" -o contract.png -l H -s 8 -m 6

# 彩色 QR 码
qrgen encode "My Brand" -o brand.png --fg "#FF5733" --bg "#FFF8E7"

# 带 Logo
qrgen encode "https://mycompany.com" -o logo.png -l H --logo avatar.png

# JPEG 输出
qrgen encode "JPEG test" -o qr.jpg -f jpeg

# WebP 输出
qrgen encode "WebP test" -o qr.webp -f webp

# 指定版本（强制版本 5）
qrgen encode "Fixed version" -o fixed.png -v 5
```

---

## 编码模式

通过 `--mode` 参数可以使用 7 种编码模式，自动构造标准格式文本，无需手动拼接。

### 文本模式（默认）

```bash
qrgen encode "任意文本内容" -o text.png
```

等同于：
```bash
qrgen encode --mode text "任意文本内容" -o text.png
```

### URL 模式

```bash
qrgen encode --mode url --url "https://github.com/LHY0125/QRGen" -o url.png
```

### WiFi 模式

```bash
# 基础 WiFi
qrgen encode --mode wifi --ssid MyWiFi --password pass123 -o wifi.png

# 无密码 WiFi
qrgen encode --mode wifi --ssid FreeWiFi --encryption nopass -o free-wifi.png

# 隐藏网络 + WPA2
qrgen encode --mode wifi --ssid HiddenNet --password secret --encryption WPA2 --hidden -o hidden.png
```

生成的 QR 内容格式：`WIFI:T:WPA;S:MyWiFi;P:pass123;;`

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--ssid` | WiFi 名称 | 必填 |
| `--password` | WiFi 密码 | 空 |
| `--encryption` | 加密方式：`WPA` `WPA2` `WEP` `nopass` | `WPA` |
| `--hidden` | 隐藏网络标志 | false |

### vCard 模式（电子名片）

```bash
# 基础名片
qrgen encode --mode vcard \
  --name "张三" \
  --phone "13800138000" \
  --email "zhangsan@example.com" \
  -o card.png

# 完整名片（10 字段）
qrgen encode --mode vcard \
  --name "张三" \
  --phone "13800138000" \
  --email "zhangsan@example.com" \
  --company "科技有限公司" \
  --title "高级工程师" \
  --address "北京市海淀区" \
  --vcard-url "https://zhangsan.com" \
  --birthday "1995-06-15" \
  --note "爱好: 编程, 摄影" \
  --photo "https://zhangsan.com/avatar.jpg" \
  -o full-card.png
```

| 参数 | 说明 |
|------|------|
| `--name` | 姓名 |
| `--phone` | 电话 |
| `--email` | 邮箱 |
| `--company` | 公司 |
| `--title` | 职位 |
| `--address` | 地址 |
| `--vcard-url` | 个人网址 |
| `--birthday` | 生日 `YYYY-MM-DD` |
| `--note` | 备注 |
| `--photo` | 照片 URL |

### Email 模式

```bash
qrgen encode --mode email \
  --to "hello@example.com" \
  --subject "合作洽谈" \
  --body "您好，我对贵公司的产品很感兴趣。" \
  -o email.png
```

生成的 QR 内容格式：`mailto:hello@example.com?subject=...&body=...`

### 电话模式

```bash
qrgen encode --mode phone --number "13800138000" -o phone.png
```

扫描后直接拨号。

### 短信模式

```bash
qrgen encode --mode sms \
  --number "13800138000" \
  --message "你好，方便电话吗？" \
  -o sms.png
```

---

## 批量生成

从 JSON 或 CSV 文件批量生成 QR 码。

### JSON 格式

```json
[
  {"content": "产品 A", "level": "H"},
  {"content": "产品 B", "level": "M"},
  {"content": "产品 C"}
]
```

```bash
qrgen encode --batch items.json --output-dir ./qr_output/
# 输出: qr_output/qr_0001.png, qr_output/qr_0002.png, ...
```

### CSV 格式

```csv
content,level
"产品 A",H
"产品 B",M
"产品 C",M
```

```bash
qrgen encode --batch items.csv --output-dir ./qr_output/ -s 8
```

### 批量 WiFi 名片

JSON 中可以用模式专用字段：

```json
[
  {"ssid": "Office-1F", "password": "pass1", "encryption": "WPA2"},
  {"ssid": "Office-2F", "password": "pass2", "encryption": "WPA2"},
  {"ssid": "Guest", "encryption": "nopass"}
]
```

支持的批量字段：`content` `url` `ssid` `password` `encryption` `hidden` `name` `phone` `email` `company` `address` `to` `subject` `body` `number` `message`

---

## 解码

从图片文件解码 QR 码内容。

```bash
qrgen decode qr.png
qrgen -d qr.jpg
```

输出示例：
```
解码成功:
  文本: https://example.com
  版本: 3
  纠错级别: M
  掩码: 2
  纠正错误: 0 码字
```

支持格式：PNG、JPEG、WebP、BMP。

解码器会自动对倾斜图片做旋转矫正。

---

## 纠错级别说明

| 级别 | 纠错率 | 适用场景 |
|------|--------|----------|
| L | ~7% | 屏幕显示、数字传输 |
| M | ~15% | 日常打印（默认） |
| Q | ~25% | 可能被遮挡的场景 |
| H | ~30% | Logo 嵌入、户外使用 |

**注意：** 纠错越高，相同尺寸下可存储的文本越少。H 级建议与 Logo 嵌入配合使用。

---

## 文件格式对比

| 格式 | 特点 | 适用场景 |
|------|------|----------|
| PNG | 无损压缩，支持透明 | 通用推荐 |
| SVG | 矢量，无限缩放 | 印刷、网页嵌入 |
| JPEG | 有损压缩，文件小 | 照片场景 |
| WebP | 现代格式，文件最小 | Web 优化 |
| BMP | 无压缩，文件大 | 嵌入式系统 |
| ASCII | 终端字符画 | 快速预览 |

---

## 完整参数列表

```
Usage: qrgen <COMMAND>

Commands:
  encode  编码：文本 → QR 码
  decode  解码：QR 码图片 → 文本

通用选项:
  --generate-completions <SHELL>  生成 Shell 补全脚本 (bash/zsh/fish/powershell/elvish)
  -h, --help                      显示帮助
  -V, --version                   显示版本

编码子命令 — qrgen encode [OPTIONS] [CONTENT]
  -o, --output <FILE>     输出文件 (.png/.bmp/.jpg/.webp/.svg)
  -l, --level <L/M/Q/H>   纠错级别 [default: M]
  -V, --version <1-40>    手动指定版本 [default: auto]
  -s, --size <PIXELS>     模块像素大小 [default: 4]
  -m, --margin <MODULES>  白边模块数 [default: 4]
  -f, --format <FORMAT>   图像格式: png/bmp/jpeg/webp [default: png]
  --fg <#RRGGBB>          前景色 [default: #000]
  --bg <#RRGGBB>          背景色 [default: #FFF]
  --logo <FILE>           Logo 图片文件
  --mode <MODE>           编码模式: text/url/wifi/vcard/email/phone/sms/batch
  --ssid <NAME>           WiFi 名称
  --password <PWD>        WiFi 密码
  --encryption <TYPE>     加密方式: WPA/WPA2/WEP/nopass [default: WPA]
  --hidden                隐藏网络
  --name <NAME>           姓名 (vCard)
  --phone <NUMBER>        电话 (vCard)
  --email <ADDR>          邮箱 (vCard)
  --company <NAME>        公司 (vCard)
  --title <TITLE>         职位 (vCard)
  --address <ADDR>        地址 (vCard)
  --vcard-url <URL>       个人网址 (vCard)
  --birthday <DATE>       生日 YYYY-MM-DD (vCard)
  --note <TEXT>           备注 (vCard)
  --photo <URL>           照片 URL (vCard)
  --to <ADDR>             收件人 (Email)
  --subject <TEXT>        主题 (Email)
  --body <TEXT>           正文 (Email)
  --number <NUMBER>       电话号码 (Phone/SMS)
  --message <TEXT>        短信内容 (SMS)
  --url <URL>             URL 链接
  --batch <FILE>          批量输入文件 (JSON/CSV)
  --output-dir <DIR>      批量输出目录

解码子命令 — qrgen decode [FILE]
  [FILE]  图片文件路径（传 - 从 stdin 读取）
```

### stdin 管道

```bash
# 编码：从管道读入
echo "Hello" | qrgen encode - -o qr.png
cat long_text.txt | qrgen encode - -o qr.png

# 解码：从管道读入
curl -s https://api.example.com/qr.png | qrgen decode -
```

### Shell 补全

```bash
# 生成补全脚本
qrgen --generate-completions bash > /usr/share/bash-completion/completions/qrgen
qrgen --generate-completions zsh > /usr/share/zsh/site-functions/_qrgen
qrgen --generate-completions fish > ~/.config/fish/completions/qrgen.fish
```

### 退出码

| 码 | 含义 |
|----|------|
| 0 | 成功 |
| 1 | 输入错误（内容为空、模式不匹配、解码失败） |
| 2 | 系统错误（文件不存在、IO 错误） |

---

## 常见问题

### Q: 生成的 QR 码扫不出来？

1. 确保静区足够：`-m 4` 或更大
2. 提高纠错级别：`-l H`
3. 增大模块尺寸：`-s 8` 或更高
4. 如果是彩色 QR，确保前景/背景对比度足够

### Q: 如何生成超大文本的 QR 码？

降低纠错级别（L 级容量最大），或让系统自动选择版本：

```bash
qrgen encode "很长的文本..." -o big.png -l L
```

### Q: Logo 叠加后扫不出来？

1. 使用 H 级纠错（`-l H`）
2. Logo 尺寸占 QR 区域约 25%，系统会自动缩放
3. 确保 Logo 图片是 PNG 格式

### Q: 批量生成时如何指定纠错级别？

JSON 中每个条目可以设置 `"level": "H"`，也可以在命令行用 `-l H` 统一设置。

### Q: CSV 和 JSON 格式如何选择？

- JSON：支持嵌套字段，推荐用于 WiFi/vCard 等复杂模式
- CSV：简单表格，适合纯文本批量生成