# OCR 订单处理系统 - OpenClaw 对接指南 (增强版)

本指南旨在帮助 OpenClaw 实现对采购单处理系统的全功能自动化控制，涵盖图片识别、Excel 清洗、特殊供应商处理及条码映射管理。

## 1. 核心接口说明 (headless_api.py)

`headless_api.py` 是系统的统一命令行入口。它支持多种模式，通过参数切换功能。

### 1.1 图片 OCR 识别 (默认模式)
当接收到用户发送的采购单图片时使用。
```bash
# 自动处理 data/input 中最新的图片
python headless_api.py

# 处理指定图片
python headless_api.py "data/input/my_invoice.jpg"
```

### 1.2 纯 Excel 订单处理
当用户直接提供供应商导出的 Excel 文件时使用。
```bash
# 处理 data/input 中最新的 Excel
python headless_api.py --excel

# 处理指定 Excel
python headless_api.py "data/input/supplier_order.xlsx" --excel
```

### 1.3 特殊供应商预处理
针对格式极其特殊的供应商（如蓉城易购、烟草公司），系统内置了专用逻辑。
```bash
# 处理蓉城易购订单 (自动从 data/output 找最新订单文件)
python headless_api.py --rongcheng

# 处理烟草公司订单
python headless_api.py --tobacco
```

### 1.4 条码映射管理
当发现 OCR 识别出的条码与系统库不一致时，可通过此接口更新映射关系。
```bash
# 将原始条码 12345 映射为系统目标条码 67890
python headless_api.py --update-mapping --barcode "12345" --target "67890"
```

## 2. OpenClaw 集成策略

### 2.1 任务分发逻辑
OpenClaw 应根据用户输入判断调用的参数：
- **收到图片** -> 调用默认模式。
- **收到 Excel** -> 调用 `--excel` 模式。
- **用户提到“蓉城”或“易购”** -> 调用 `--rongcheng`。
- **用户提到“烟草”** -> 调用 `--tobacco`。
- **用户纠正条码错误** -> 调用 `--update-mapping`。

### 2.2 结果获取
- **成功**：脚本会在 `stdout` 打印生成的 Excel 绝对路径。OpenClaw 捕获此路径并发送文件。
- **单价预警**：脚本会在 `stderr` 输出 `WARNING: Price validation found...`。OpenClaw 应捕获并转述给用户：“文件已生成，但发现部分商品价格异常，请注意查看。”

## 3. 常见目录定义
- `data/input/`：存放待处理的原始图片或 Excel。
- `data/output/`：存放 OCR 识别后的中间文件（蓉城/烟草模式会从此目录读取）。
- `data/result/`：最终生成的标准银豹采购单。

---
*版本：2.0 | 更新日期：2026-03-25*