# OCR 订单处理系统 - OpenClaw 对接指南

本指南旨在帮助 OpenClaw（或任何自动化 AI 代理）理解如何与本项目进行对接，实现“发送图片 -> 自动处理 -> 返回 Excel”的闭环流程。

## 1. 项目概览
本项目是一个自动化的采购单处理系统。它通过 OCR 技术识别图片中的表格数据，并根据预设的规则进行清洗（如拆分单位、推算规格），最后生成标准格式的 Excel 采购单。

## 2. 核心工作流
自动化对接建议遵循以下步骤：

1.  **图片准备**：将收到的采购单图片保存至项目的 `data/input/` 目录。
2.  **触发处理**：运行 `headless_api.py` 脚本。
3.  **捕获路径**：从脚本的标准输出（stdout）中获取生成的 Excel 绝对路径。
4.  **读取结果**：根据获取的路径读取文件并发送回给用户。

## 3. API 接口说明 (headless_api.py)

这是专门为自动化对接设计的入口。

### 运行方式
```bash
# 方式 A：自动处理 input 目录中最新的一张图片
python headless_api.py

# 方式 B：处理指定路径的图片
python headless_api.py "E:/2025Code/python/orc-order-v2/data/input/invoice_001.jpg"
```

### 输出规范
-   **标准输出 (stdout)**：仅在处理成功时打印**最终生成的 Excel 文件的绝对路径**。
    -   *示例*：`E:\2025Code\python\orc-order-v2\data\result\采购单_invoice_001.xlsx`
-   **标准错误 (stderr)**：输出所有的运行日志、进度信息、警告以及错误详情。
    -   *注意*：如果发生“单价校验”差异（即生成价格与商品资料价格差异 > 1 元），相关警告会打印在此流中。

## 4. 关键目录结构
-   `data/input/`：存放待处理的原始图片（支持 jpg, png, bmp）。
-   `data/result/`：存放最终生成的标准 Excel 采购单。
-   `templates/商品资料.xlsx`：系统会自动根据此文件进行单价校验。
-   `config/suppliers_config.json`：存储供应商的清洗规则。

## 5. 错误代码与异常处理
-   如果脚本退出码为 `0`：表示处理成功，stdout 包含文件路径。
-   如果脚本退出码为 `1`：表示处理失败，具体原因请查看 stderr。

## 6. 给 OpenClaw 的建议策略
1.  **轮询或触发**：当检测到用户发送图片时，先清空或直接写入 `data/input/`。
2.  **路径捕获**：使用类似 `subprocess.check_output` 的方法运行脚本，捕获最后一行输出作为文件路径。
3.  **价格预警**：OpenClaw 可以扫描 stderr，如果发现包含 `WARNING: Price validation found...` 字样，可以主动提醒用户：“处理完成，但发现部分商品单价与资料库不符，请核对。”

---
*由系统自动生成于 2026-03-25*