# CLAUDE.md - 益选 OCR 订单处理系统

## 项目概述

益选 OCR 订单处理系统 (orc-order-v2) 是一个面向零售与分销场景的采购单处理工具。

**核心流程**: 图片 OCR → Excel 规范化 → 模板填充 → 合并导出

**目标系统**: 银豹 (PosPal) POS 系统

**技术栈**: Python 3.9+, Tkinter, Pandas, Baidu OCR API, xlrd/xlwt/openpyxl

## 项目结构

```
orc-order-v2/
├── 启动器.py                    # 入口桩 (~13行, 仅导入 main)
├── headless_api.py              # CLI 自动化接口 (OpenClaw 对接)
├── build_exe.py                 # PyInstaller 打包脚本
├── config.ini                   # 全局配置 (API密钥、路径)
├── config/
│   ├── config.ini               # 配置副本
│   ├── barcode_mappings.json    # 条码映射规则
│   └── suppliers_config.json    # 供应商配置 (列映射/清洗规则/计算规则)
├── app/
│   ├── config/
│   │   ├── settings.py          # ConfigManager 单例
│   │   └── defaults.py          # 默认配置
│   ├── core/
│   │   ├── excel/
│   │   │   ├── processor.py     # ExcelProcessor - 标准化转换核心
│   │   │   ├── converter.py     # UnitConverter - 单位转换与规格推断
│   │   │   ├── merger.py        # PurchaseOrderMerger - 采购单合并
│   │   │   ├── validators.py    # ProductValidator
│   │   │   └── handlers/        # 条码映射、单位转换处理器
│   │   ├── handlers/
│   │   │   ├── rule_engine.py   # 通用规则引擎 (split/extract/normalize/mark)
│   │   │   ├── column_mapper.py # 列映射器
│   │   │   ├── data_cleaner.py  # 数据清洗器
│   │   │   └── calculator.py    # 计算器
│   │   ├── ocr/
│   │   │   ├── table_ocr.py     # OCRProcessor
│   │   │   └── baidu_ocr.py     # BaiduOCRClient
│   │   ├── processors/
│   │   │   ├── base.py          # BaseProcessor 抽象基类
│   │   │   ├── tobacco_processor.py
│   │   │   ├── ocr_processor.py
│   │   │   └── supplier_processors/
│   │   │       └── generic_supplier_processor.py
│   │   └── utils/
│   │       ├── file_utils.py    # 文件操作工具
│   │       ├── log_utils.py     # 日志工具
│   │       ├── string_utils.py  # 字符串工具
│   │       └── dialog_utils.py  # Tkinter 对话框工具
│   ├── services/
│   │   ├── order_service.py     # 订单服务 (智能路由分发)
│   │   ├── ocr_service.py       # OCR 服务
│   │   ├── processor_service.py # 处理器调度服务
│   │   ├── tobacco_service.py   # 烟草公司专用服务
│   │   └── special_suppliers_service.py  # 特殊供应商服务 (蓉城/杨碧月)
│   └── ui/                      # GUI 模块 (从启动器.py拆分)
│       ├── error_utils.py       # L0 错误对话框
│       ├── theme.py             # L0 主题管理 (THEMES, create_modern_button)
│       ├── logging_ui.py        # L0 日志队列与GUI日志处理器
│       ├── ui_widgets.py        # L0 StatusBar, ProgressReporter, center_window
│       ├── user_settings.py     # L1 用户设置与最近文件管理
│       ├── result_previews.py   # L1 处理结果预览对话框
│       ├── command_runner.py    # L1 命令执行器 (subprocess + 日志重定向)
│       ├── file_operations.py   # L2 文件选择/清理/目录操作
│       ├── action_handlers.py   # L2 业务操作 (OCR/Excel/合并/拖拽)
│       ├── barcode_editor.py    # L2 条码映射编辑
│       ├── config_dialog.py     # L3 系统设置对话框
│       ├── shortcuts.py         # L3 键盘快捷键绑定
│       └── main_window.py       # L4 main() 主窗口构建
├── templates/
│   ├── 银豹-采购单模板.xls       # 输出模板
│   └── 商品资料.xlsx             # 单价校验参考数据
├── data/
│   ├── input/                   # 输入文件
│   ├── output/                  # OCR 输出
│   ├── result/                  # 最终采购单
│   └── user_settings.json       # 用户设置
└── docs/
    └── SYSTEM_ARCHITECTURE.md   # 系统架构文档
```

## 命令与运行

```bash
# GUI 模式
python 启动器.py

# CLI 模式 (OpenClaw 对接)
python headless_api.py [input] [--excel|--tobacco|--rongcheng] [--barcode X --target Y]

# 打包 EXE
python build_exe.py

# 条码映射更新
python headless_api.py --update-mapping --barcode 6920584471055 --target 6920584471017
```

## 供应商智能识别逻辑

系统通过扫描 Excel 前 50 行内容特征自动路由:

| 供应商 | 识别特征 | 预处理逻辑 |
|--------|----------|-----------|
| 烟草公司 | "专卖证号" 或 "510109104938" | B/E/G/H 列映射, 数量*10, 单价/10 |
| 蓉城易购 | "RCDH" | E/N/Q/S 列映射, 多条码分裂均分数量 |
| 杨碧月 | "经手人" + "杨碧月" | 列对齐, 单位转换 (件→瓶) |
| 通用供应商 | suppliers_config.json 配置 | 列映射 + 规则引擎 |

## 配置系统

- **ConfigManager** (`app/config/settings.py`): 单例模式, 基于 configparser 读取 `config.ini`
- **供应商配置** (`config/suppliers_config.json`): JSON 格式, 定义列映射/清洗规则/计算规则
- **条码映射** (`config/barcode_mappings.json`): 运行时可更新的条码转换规则

## 关键约定

### 输出格式
- 银豹采购单模板: 4 列 — 条码(B), 采购量(C), 赠送量(D), 采购单价(E)
- 单价保留 4 位小数, 使用 xlwt.XFStyle
- 采购单文件名: `采购单_{原文件名}.xls`

### 单位转换规则
- "件"/"箱"/"提"/"盒" → 数量*包装数量, 单价/包装数量, 单位→"瓶"
- 赠品: 价格为 0 或金额为 0 的行标记为赠品
- 条码映射优先于单位转换

### 规格推断
- 从商品名称推断: "24入纸箱" → 1*24, "450g*15" → 1*15
- 支持三级规格: 1*5*12
- OCR 修正: "IL" → "1L", "6oo" → "600"

## 已知技术债务

1. ~~**启动器.py 过大**~~ (已拆分为 13 个 `app/ui/` 模块, 入口桩仅 13 行)
2. **代码重复**: 表头识别、列映射、金额解析在多处重复实现
3. **配置不统一**: config.ini + suppliers_config.json + 硬编码路径混用
4. **无测试**: 测试目录为空, 无自动化测试
5. **旧格式依赖**: xlrd/xlwt 仅支持 .xls, 不支持 .xlsx 写入
6. **API 密钥明文**: config.ini 中百度 OCR API 密钥未加密
7. **路径硬编码**: config.ini 中 `template_folder = E:\2025Code\python\orc-order-v2\templates`
8. **日志不统一**: 混用 `get_logger()` 和 `logging.getLogger()`