# Filescan - 统一文件扫描工具

Filescan 是一个强大的文档和内容扫描工具，支持多种文件格式的文本提取和模式匹配。

## 功能特性

### 核心功能

- ✅ **多格式支持**: PDF, DOCX, XLSX, PPTX, ODT, RTF, EPUB, CSV, XML, HTML, Markdown, TXT
- ✅ **灵活搜索**: 支持正则表达式和简单文本匹配
- ✅ **上下文提取**: 自动捕获匹配行周围的上下文
- ✅ **高性能扫描**: 多线程和多进程支持
- ✅ **丰富元数据**: 提取文档元数据和统计信息
- ✅ **OCR 支持**: 可选的 OCR 功能用于图像和扫描版 PDF
- ✅ **JSON 输出**: 生成结构化的 JSON 报告
- ✅ **GUI 界面**: 现代化的图形用户界面
- ✅ **CLI 工具**: 命令行接口便于自动化

### 支持的格式

#### 办公文档

- **PDF**: PyMuPDF (fitz) 或 PyPDF2
- **DOCX**: Word 文档 (python-docx)
- **XLSX**: Excel 电子表格 (openpyxl)
- **PPTX**: PowerPoint 演示文稿 (python-pptx)
- **ODT**: OpenDocument 文本 (odfpy)
- **RTF**: 富文本格式 (原生支持)

#### 网页和标记

- **HTML/HTM**: HTML 文档
- **XML**: XML 文档
- **Markdown**: Markdown 文件
- **CSV**: 逗号分隔值

#### 电子书

- **EPUB**: 电子书格式 (ebooklib)

#### 图像（需要 OCR）

- **JPG/PNG/GIF/BMP/TIFF**: 图像文件配合 OCR 识别

## 安装

### 基础安装

```bash
pip install pytola-filescan
```

### 完整安装（包含所有依赖）

```bash
pip install pytola-filescan[all]
```

### 可选依赖

```bash
# OCR 支持
pip install pytola-filescan[ocr]

# Office 文档支持
pip install pytola-filescan[office]

# 额外格式支持
pip install pytola-filescan[extra]
```

## 使用方法

### 命令行使用

```bash
# 基础用法
filescan -i /path/to/documents -r rules.json

# 完整选项
filescan -i ./documents \
        -r rules.json \
        -f "pdf,docx,txt" \
        -t 8 \
        --use-process-pool \
        --progress \
        --use-pdf-ocr \
        -v

# 启动 GUI 界面
filescan --gui
```

### 参数说明

| 参数                 | 简写 | 说明                 | 默认值       |
| -------------------- | ---- | -------------------- | ------------ |
| `--input`            | `-i` | 输入目录（必需）     | 当前目录     |
| `--rules`            | `-r` | 规则文件（必需）     | rules.json   |
| `--file-types`       | `-f` | 文件类型（逗号分隔） | 全部支持类型 |
| `--use-pdf-ocr`      | -    | 对 PDF 使用 OCR      | False        |
| `--use-process-pool` | -    | 使用进程池           | False        |
| `--batch-size`       | `-b` | 每批处理文件数       | 50           |
| `--threads`          | `-t` | 线程/进程数          | 4            |
| `--progress`         | -    | 显示进度条           | False        |
| `--verbose`          | `-v` | 详细输出             | False        |
| `--gui`              | -    | 启动 GUI             | False        |

### Python 模块使用

```python
from pytola_office.filescan import DocumentAnalyser
from pathlib import Path
import json

# 加载规则配置
with open("rules.json") as f:
    rules_config = json.load(f)

# 创建扫描器
scanner = DocumentAnalyser(
    input_dir=Path("./documents"),
    rules_config=rules_config,  # 直接使用规则配置字典
    file_types=["pdf", "docx", "txt"],
    use_pdf_ocr=False,
    use_process_pool=True,
    batch_size=50
)

# 执行扫描
results = scanner.scan(threads=8, show_progress=True)

# 保存结果
with open("results.json", "w") as f:
    json.dump(results.to_dict(), f, indent=2)
```

## 规则文件格式

### JSON 结构

```json
{
    "description": "规则集描述（可选）",
    "rules": [
        {
            "name": "规则名称",
            "pattern": "搜索模式",
            "regex": true,
            "case_sensitive": false,
            "context_lines": 3,
            "description": "规则描述"
        }
    ]
}
```

### 规则字段说明

| 字段             | 类型    | 必需 | 说明                         |
| ---------------- | ------- | ---- | ---------------------------- |
| `name`           | string  | 是   | 规则唯一标识                 |
| `pattern`        | string  | 是   | 搜索模式                     |
| `regex`          | boolean | 否   | 使用正则表达式（默认 false） |
| `case_sensitive` | boolean | 否   | 区分大小写（默认 false）     |
| `context_lines`  | integer | 否   | 上下文行数（默认 3）         |
| `description`    | string  | 否   | 规则描述                     |

### 示例规则

#### 1. 查找电子邮件地址

```json
{
    "name": "emails",
    "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
    "regex": true,
    "case_sensitive": false,
    "context_lines": 2,
    "description": "查找所有电子邮件地址"
}
```

#### 2. 查找关键词

```json
{
    "name": "confidential",
    "pattern": "confidential",
    "regex": false,
    "case_sensitive": false,
    "context_lines": 3,
    "description": "查找机密关键词"
}
```

## 输出格式

扫描结果保存为 JSON 文件，结构如下：

```json
{
    "scan_info": {
        "input_directory": "/path/to/documents",
        "scan_time": "2026-01-28T10:30:00",
        "file_types_scanned": ["pdf", "docx", "txt"],
        "total_files": 150,
        "rules_count": 5,
        "files_with_matches": 23,
        "use_pdf_ocr": false,
        "use_process_pool": false
    },
    "rules": [
        {
            "name": "emails",
            "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
            "is_regex": true
        }
    ],
    "matches": [
        {
            "file_path": "/path/to/document.pdf",
            "file_type": "pdf",
            "file_size": 1024000,
            "metadata": {
                "page_count": 10,
                "title": "文档标题",
                "author": "作者姓名"
            },
            "matches": [
                {
                    "rule_name": "emails",
                    "rule_description": "查找所有电子邮件地址",
                    "type": "regex",
                    "line_number": 15,
                    "match": "user@example.com",
                    "start": 10,
                    "end": 26,
                    "context": [
                        "联系信息：",
                        "邮箱：user@example.com",
                        "电话：555-1234"
                    ]
                }
            ]
        }
    ]
}
```

## 性能优化建议

### 1. CPU 密集型任务使用进程池

对于 OCR 或复杂正则表达式：

```bash
filescan -i ./documents -r rules.json --use-process-pool -t 8
```

### 2. I/O 密集型任务增加线程数

对于大量小文件：

```bash
filescan -i ./documents -r rules.json -t 16
```

### 3. 限制文件类型

只扫描需要的类型：

```bash
filescan -i ./documents -r rules.json -f "pdf,docx"
```

### 4. 使用简单模式

简单文本搜索比正则更快：

```json
{
    "name": "keyword",
    "pattern": "keyword",
    "regex": false
}
```

## 技术架构

```bash
filescan/
├── scanners/
│   ├── base.py           # 扫描器基类
│   └── document.py       # 文档扫描器实现
├── threads/
│   ├── ScanWorker.py     # 后台扫描线程
│   ├── CountThread.py    # 计数线程
│   └── FileSearchThread.py # 文件搜索线程
├── widgets/
│   └── unified_scanner.py # 统一 GUI 界面
├── cli.py                # 命令行接口
└── config.py             # 配置管理
```

## 故障排除

### "PyMuPDF not installed"

```bash
pip install pymupdf
```

### "python-docx not installed"

```bash
pip install python-docx openpyxl python-pptx
```

### "Tesseract not found"

安装 Tesseract OCR 引擎：

- Ubuntu/Debian: `sudo apt-get install tesseract-ocr`
- macOS: `brew install tesseract`
- Windows: 从 `https://github.com/UB-Mannheim/tesseract/wiki` 下载

### OCR 功能不工作

1. 安装依赖：`pip install Pillow pytesseract`
2. 安装 Tesseract OCR 引擎
3. 确保 Tesseract 在系统 PATH 中

### 性能慢

1. 使用进程池：`--use-process-pool`
2. 限制文件类型
3. 避免不必要的 OCR
4. 使用简单文本模式代替正则

## 版本信息

- 版本：0.1.2
- Python 要求：>=3.8
- 创建时间：2026-01-28

## 许可证

本工具是 pytola 项目的一部分.
