cutThenThink/docs/P0-8_quick_reference.md

# 处理流程整合 - 快速参考指南

## 快速开始

### 1. 处理单张图片（最简单）

```python
from src.core.processor import process_single_image
from src.config.settings import get_settings

settings = get_settings()

result = process_single_image(
    image_path="/path/to/image.png",
    ai_config=settings.ai,
    db_path="data/cutnthink.db"
)

if result.success:
    print(f"成功! 分类: {result.ai_result.category.value}")
```

### 2. 使用处理器（更多控制）

```python
from src.core.processor import ImageProcessor, ProcessCallback

# 创建回调
callback = ProcessCallback()
callback.on_complete = lambda r: print(f"完成! 成功={r.success}")

# 创建处理器
processor = ImageProcessor(
    ocr_config={'mode': 'local', 'lang': 'ch'},
    ai_config=settings.ai,
    db_path="data/cutnthink.db",
    callback=callback
)

# 处理
result = processor.process_image("/path/to/image.png")
```

### 3. 创建 Markdown 结果

```python
from src.core.processor import create_markdown_result

markdown = create_markdown_result(
    ai_result=result.ai_result,
    ocr_text=result.ocr_result.full_text
)

print(markdown)
```

### 4. 复制到剪贴板

```python
from src.utils.clipboard import copy_to_clipboard

copy_to_clipboard("要复制的文本")
```

### 5. 在 GUI 中显示结果

```python
import tkinter as tk
from src.gui.widgets import ResultWidget

root = tk.Tk()
widget = ResultWidget(root)
widget.pack(fill=tk.BOTH, expand=True)
widget.set_result(result)
root.mainloop()
```

### 6. 显示对话框

```python
from src.gui.widgets import show_info, show_error, ask_yes_no

show_info("标题", "消息")
show_error("错误", "错误消息")

if ask_yes_no("确认", "继续吗？"):
    print("用户选择是")
```

### 7. 初始化日志

```python
from src.utils.logger import init_logger, get_logger

init_logger(log_dir="logs", level="INFO")
logger = get_logger(__name__)

logger.info("信息日志")
logger.error("错误日志")
```

## 常用参数

### ImageProcessor 初始化参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `ocr_config` | dict | None | OCR 配置 (mode, lang, use_gpu) |
| `ai_config` | AIConfig | None | AI 配置对象 |
| `db_path` | str | None | 数据库路径 |
| `callback` | ProcessCallback | None | 回调对象 |

### process_image 参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `image_path` | str | 必需 | 图片路径 |
| `save_to_db` | bool | True | 是否保存到数据库 |
| `skip_ocr` | bool | False | 是否跳过 OCR |
| `skip_ai` | bool | False | 是否跳过 AI 分类 |
| `ocr_text` | str | None | 直接提供的 OCR 文本 |

### ProcessResult 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `success` | bool | 是否处理成功 |
| `image_path` | str | 图片路径 |
| `ocr_result` | OCRBatchResult | OCR 结果 |
| `ai_result` | ClassificationResult | AI 结果 |
| `record_id` | int | 数据库记录 ID |
| `process_time` | float | 处理耗时（秒） |
| `steps_completed` | list | 已完成的步骤 |
| `warnings` | list | 警告信息 |

## 配置示例

### OCR 配置

```python
ocr_config = {
    'mode': 'local',      # 'local' 或 'cloud'
    'lang': 'ch',          # 'ch', 'en', 'chinese_chinese'
    'use_gpu': False       # 是否使用 GPU
}
```

### AI 配置（从设置获取）

```python
from src.config.settings import get_settings

settings = get_settings()
ai_config = settings.ai

# 或手动创建
from src.config.settings import AIConfig, AIProvider

ai_config = AIConfig(
    provider=AIProvider.ANTHROPIC,
    api_key="your-api-key",
    model="claude-3-5-sonnet-20241022",
    temperature=0.7
)
```

## 回调方法

### ProcessCallback 可实现的方法

```python
class MyCallback(ProcessCallback):
    def on_start(self, message): pass
    def on_ocr_start(self, message): pass
    def on_ocr_complete(self, result): pass
    def on_ai_start(self, message): pass
    def on_ai_complete(self, result): pass
    def on_save_start(self, message): pass
    def on_save_complete(self, record_id): pass
    def on_error(self, message, exception): pass
    def on_complete(self, result): pass
    def on_progress(self, step, progress, message): pass
```

## 错误处理

```python
try:
    result = processor.process_image(image_path)
except Exception as e:
    print(f"处理失败: {e}")

# 检查结果
if not result.success:
    print(f"错误: {result.error_message}")

# 检查警告
for warning in result.warnings:
    print(f"警告: {warning}")
```

## 常见问题

### Q: 如何跳过 OCR？

```python
result = processor.process_image(
    image_path="/path/to/image.png",
    skip_ocr=True,
    ocr_text="直接提供的文本"
)
```

### Q: 如何只运行 OCR 不进行 AI 分类？

```python
result = processor.process_image(
    image_path="/path/to/image.png",
    skip_ai=True
)
```

### Q: 如何不保存到数据库？

```python
result = processor.process_image(
    image_path="/path/to/image.png",
    save_to_db=False
)
```

### Q: 如何批量处理？

```python
image_paths = ["img1.png", "img2.png", "img3.png"]
results = processor.batch_process(image_paths)
```

## 文件位置

| 文件 | 路径 |
|------|------|
| 处理器 | `src/core/processor.py` |
| 日志工具 | `src/utils/logger.py` |
| 剪贴板工具 | `src/utils/clipboard.py` |
| 结果组件 | `src/gui/widgets/result_widget.py` |
| 消息处理 | `src/gui/widgets/message_handler.py` |
| 使用文档 | `docs/P0-8_processor_integration.md` |
| 命令行示例 | `examples/processor_example.py` |
| GUI 示例 | `examples/gui_integration_example.py` |
| 基本测试 | `tests/test_integration_basic.py` |