# OFD CLI 工具使用指南

## 概述

这是一个用于处理 OFD (Open Fixed-layout Document) 文件的命令行工具，支持查看文档信息、提取文本/图片、转换为 PDF/图片、批量处理等功能。

## 安装与构建

```bash
# 构建项目
cargo build --release

# 安装到系统
cargo install --path .
```

## 命令参考

### 1. 查看文档信息

```bash
# 查看基本信息
ofd-cli info document.ofd

# 输出 JSON 格式
ofd-cli info document.ofd --json
```

### 2. 提取文本

```bash
# 提取全部文本并打印
ofd-cli extract-text document.ofd

# 提取第 3 页
ofd-cli extract-text document.ofd --page 3

# 保存到文件
ofd-cli extract-text document.ofd --output output.txt

# 混合使用
ofd-cli extract-text document.ofd -p 5 -o page5.txt
```

### 3. 提取图片

```bash
# 提取全部图片到 ./images 目录
ofd-cli extract-images document.ofd

# 提取第 2 页的图片
ofd-cli extract-images document.ofd --page 2

# 指定输出目录
ofd-cli extract-images document.ofd -o ./my_images
```

### 4. 转换为 PDF

```bash
# 转换为同名的 PDF
ofd-cli to-pdf document.ofd

# 指定输出路径和图片质量
ofd-cli to-pdf document.ofd -o output.pdf -q 90
```

### 5. 转换为图片

```bash
# 转换为 PNG（默认）
ofd-cli to-images document.ofd

# 转换为 JPG，质量 85
ofd-cli to-images document.ofd -f jpg -q 85

# 指定 DPI 和输出目录
ofd-cli to-images document.ofd -o ./pages -d 200
```

### 6. 批量处理

```bash
# 批量提取文本
ofd-cli batch ./docs --operation text -o ./output


# 使用正则匹配特定文件
ofd-cli batch ./docs --operation images -o ./images --pattern "report.*\.ofd"

# 批量获取信息 (JSON)
ofd-cli batch ./docs --operation info -o ./info
```

### 7. 验证文件

```bash
# 基本验证
ofd-cli validate document.ofd

# 详细验证（含文档信息）
ofd-cli validate document.ofd --verbose
```

## 参数说明

### 通用参数

| 参数 | 简写 | 说明 |
|------|------|------|
| `--help` | `-h` | 显示帮助信息 |
| `--version` | `-V` | 显示版本号 |

### Info 命令

| 参数 | 简写 | 说明 |
|------|------|------|
| `--json` | `-j` | 输出 JSON 格式 |

### Extract-text 命令

| 参数 | 简写 | 说明 |
|------|------|------|
| `--page` | `-p` | 指定页码（从1开始） |
| `--output` | `-o` | 输出文件路径 |

### Extract-images 命令

| 参数 | 简写 | 默认值 | 说明 |
|------|------|--------|------|
| `--output` | `-o` | `./images` | 输出目录 |
| `--page` | `-p` | 无 | 指定页码 |

### To-pdf 命令

| 参数 | 简写 | 默认值 | 说明 |
|------|------|--------|------|
| `--output` | `-o` | 同名字+.pdf | 输出 PDF 路径 |
| `--quality` | `-q` | 95 | 图片质量 (1-100) |

### To-images 命令

| 参数 | 简写 | 默认值 | 说明 |
|------|------|--------|------|
| `--output` | `-o` | `./images` | 输出目录 |
| `--format` | `-f` | `png` | 图片格式 (png/jpg) |
| `--quality` | `-q` | 95 | JPG 质量 (1-100) |
| `--dpi` | `-d` | 150 | DPI 分辨率 |

### Batch 命令

| 参数 | 简写 | 说明 |
|------|------|------|
| `--operation` | `-o` | 操作类型: info, text, images, pdf |
| `--output` | `-o` | 输出目录 |
| `--pattern` | `-p` | 正则匹配模式 |

## 工作流程示例

### 完整的文档处理流程

```bash
# 1. 先查看文档信息
ofd-cli info report.ofd --json > info.json

# 2. 验证文件完整性
ofd-cli validate report.ofd --verbose

# 3. 提取全部文本
ofd-cli extract-text report.ofd -o full_text.txt

# 4. 提取所有图片
ofd-cli extract-images report.ofd -o images/

# 5. 转换为可分享的 PDF
ofd-cli to-pdf report.ofd -q 90

# 6. 生成预览图
ofd-cli to-images report.ofd -o preview/ -d 72
```

### 批量处理多文件

```bash
# 假设有多个 OFD 文件需要统一处理
ofd-cli batch ./invoices --operation pdf -o ./pdfs
ofd-cli batch ./invoices --operation text -o ./texts
```

## 常见问题

### 1. 文件解析失败

```bash
# 先验证文件
ofd-cli validate file.ofd --verbose

# 确保文件是有效的 OFD 格式
```

### 2. 图片提取为空

- 确认文档中确实包含图片
- 尝试不指定页码提取全部
- 使用 `--verbose` 模式查看详细信息

### 3. PDF 转换质量

- 默认质量 95 已经较高
- 如需减小文件体积，可降至 75-80
- 文字识别效果与 DPI 相关，转换图片时提高 DPI

## 退出码

| 退出码 | 说明 |
|--------|------|
| 0 | 执行成功 |
| 1 | 执行失败 |

## 依赖模块

需要实现以下模块（代码中已有引用但未实现）：

- `ofd_core` - OFD 文档解析核心库
- `extractor` - 文本/图片提取模块
- `converter` - PDF/图片转换模块
- `walkdir` - 目录遍历
- `indicatif` - 进度条显示
- `regex` - 正则匹配
- `serde_json` - JSON 处理