# ALIGNMENT — 订单批量识别（OCR 元信息提取 + 批量一键处理）

## 一、目标

完善 OCR → result 完整链路，新增 3 个能力：
1. **OCR 元信息识别与持久化**：从图片 OCR 原文识别供应商、单据日期、应付金额，存 SQLite
2. **基于元信息的文件命名**：result 文件 + 原图片按"采购单_YYYYMMDD_供应商_<hash>.xls"格式命名
3. **批量一键处理**：扫描 `data/input/` 内所有图片，批量跑完整流程，每张独立出 result（默认不合并）

## 二、需求边界（已与用户确认）

### 必做
- OCR 后从原始 OCR 文本识别 3 个字段：
  - **供应商名称**：从 OCR 文本顶部识别（关键词：供货/供应/酒行/商行/批发等，取匹配行原文）
  - **单据日期**：从 OCR 文本识别（关键词：日期/单据日期/年月日；正则提取 YYYY-MM-DD / YYYY/MM/DD / YYYY.MM.DD / YYYYMMDD 等多种格式）
  - **总金额**：取"应付金额/实付金额/金额合计"字段；如无则取"总计"行最大金额
- 三个字段存到新增 SQLite 表 `order_metadata`（与现有 `product_cache.db` 共用文件）
- result 文件名格式：`采购单_{YYYYMMDD}_{供应商名}_{原文件hash}.xls`
- 原图片（input 目录）重命名为：`原名_{YYYYMMDD}_{供应商名}_{hash}.{原扩展名}`（保留扩展名，hash 不变）
- 批量处理：`data/input/` 内全部图片 → OCR → process_excel → result；输出 `data/result/采购单_*.xls`
- 完整流程跑完，日志末尾显示 3 个参数汇总（按文件列出供应商/日期/金额 + 成功/失败状态）
- 三个字段任一识别失败 → 填"未知"，文件后缀仍含原 hash 保证唯一性

### 不做
- 不修改现有 fill_template 模板
- 不改商品资料库 / 条码映射 / 单位转换逻辑
- 不合并多个订单为单个 result（用户明确"默认全部不合并"）
- 不做供应商库匹配（图片原文识别优先）
- 不做 OCR 失败重试机制增强（沿用现有 OCRService.process_image）

### 已确认决策
| 决策点 | 选择 |
|---|---|
| 供应商识别来源 | OCR 原文顶部文本（关键词匹配） |
| 总金额字段 | 应付金额/实付/金额合计，缺则取总计行最大金额 |
| 日期格式 | YYYYMMDD 作文件名后缀 |
| 识别失败默认值 | "未知供应商" + 原 hash |
| Result 输出位置 | `data/result/`（不分子目录） |

## 三、对现有项目的影响

### 需要修改的文件
- `app/core/ocr/table_ocr.py` 或新增 `app/core/ocr/metadata_extractor.py`：识别 3 个字段
- `app/core/db/product_db.py`：新增 `order_metadata` 表及 CRUD
- `app/services/order_service.py`：在 process_excel 流程里提取元信息 + 落库 + 应用新文件名
- `app/ui/main_window.py` / `action_handlers.py`：新增"批量处理"按钮 + 进度条 + 完成后日志汇总
- `app/services/processor_service.py`：新增批量入口 `process_all_inputs`

### 新增文件
- `app/core/ocr/metadata_extractor.py`：单据元信息识别器
- `tests/test_metadata_extractor.py`：单元测试

### 不需要修改
- 模板、银豹格式、单位转换、记忆库核心逻辑

## 四、验收标准

### 功能验收
- [ ] OCR 后能识别出供应商/日期/应付金额（真实单子样本）
- [ ] 三个字段存到 `data/product_cache.db` 的 `order_metadata` 表
- [ ] result 文件名 = `采购单_YYYYMMDD_供应商_<hash>.xls`
- [ ] 原图片在 input 中按相同规则重命名（保留扩展名）
- [ ] 一键处理按钮能扫描 `data/input/` 全部图片，串行处理（避免并发占资源）
- [ ] 完整流程跑完，日志显示每张的处理结果 + 3 个参数 + 状态
- [ ] 全部 191 个现有测试不破坏

### 边界验收
- [ ] 三个字段都识别不到时，使用"未知"+原 hash
- [ ] 部分识别失败，文件名仍包含原 hash 保证唯一性
- [ ] `data/input/` 为空时，按钮点击给出"无待处理图片"提示

## 五、不确定点（已澄清或可后续处理）

- **OCR 文本顶部区域范围**：取 OCR 返回的前 20 行文本（覆盖常见采购单抬头区域），如有"供应商"明确标注则取该标注
- **日期格式多样性**：正则同时支持 4 种格式，标准化为 YYYYMMDD
- **并发处理**：本期串行（10 张单子每张 1~2 秒，串行 10~20 秒可接受）；并发留待后续
- **历史 result 重命名**：本期**不**迁移历史 result（避免破坏现有用户数据）

## 六、后续文档
- DESIGN_订单批量识别.md（架构设计）
- TASK_订单批量识别.md（任务拆分）