# OCR 订单处理系统 - 系统架构文档 (v2.2)

本文件详述了“OCR 订单处理系统”的技术架构、业务流向、数据模型及部署方案。

## 1. 系统整体架构图 (System Overall Architecture)

```mermaid
graph TB
    subgraph 用户交互层
        UI[启动器.py / Tkinter GUI]
        CLI[headless_api.py / CLI]
    end

    subgraph 核心业务逻辑层
        OS[OrderService / 订单调度]
        OCR[OCRService / 图片识别]
        SSS[SpecialSuppliersService / 特殊供应商处理]
        TS[TobaccoService / 烟草处理]
        EP[ExcelProcessor / 标准化转换]
    end

    subgraph 基础设施与存储
        CONFIG[ConfigManager / JSON 配置]
        FS[FileSystem / Excel 数据存储]
        LOG[QueueLogger / 异步日志队列]
    end

    subgraph 第三方集成
        OPENCLAW[OpenClaw 自动化平台]
        POSPAL[银豹 POS 系统 (导出模板)]
    end

    UI --> OS
    CLI --> OS
    OPENCLAW -- 调用 --> CLI
    OS --> OCR
    OS --> SSS
    OS --> TS
    OS --> EP
    EP --> FS
    EP --> CONFIG
    SSS --> EP
    TS --> EP
    OS -- 验证 --> FS
```

### 图例说明
- **用户交互层**：支持桌面 GUI 操作及专为 OpenClaw 设计的无界面 API 接入。
- **核心业务层**：各服务高度解耦，通过 `OrderService` 进行智能路由分发。
- **存储层**：系统采用“文件即数据库”的设计，利用 Excel 存储模板和商品资料，JSON 存储映射关系。
- **第三方集成**：与 OpenClaw 平台通过 CLI 接口对接，最终生成符合银豹 POS 要求的采购单。

---

## 2. 核心业务逻辑流程图 (Core Business Logic)

以“智能订单识别与预处理”为例：

```mermaid
sequenceDiagram
    participant User as 用户/OpenClaw
    participant OS as OrderService
    participant SSS as SpecialSuppliersService
    participant TS as TobaccoService
    participant EP as ExcelProcessor

    User->>OS: 提交 Excel 文件
    OS->>OS: 扫描前50行内容特征
    
    alt 包含 "RCDH"
        OS->>SSS: 路由至蓉城易购预处理
        SSS->>SSS: 按 E, N, Q, S 列强制清洗
        SSS-->>OS: 返回清洗后的临时文件
    else 包含 "专卖证号"
        OS->>TS: 路由至烟草专用预处理
        TS->>TS: 数量*10 / 单价/10 / B,E,G,H列映射
        TS-->>OS: 返回清洗后的临时文件
    else 包含 "杨碧月"
        OS->>SSS: 路由至杨碧月列对齐流程
        SSS-->>OS: 返回标准列临时文件
    else 通用格式
        OS->>OS: 直接跳过预处理
    end

    OS->>EP: 执行标准条码映射与模板填充
    EP->>EP: 校验单价 (与商品资料比对)
    EP-->>User: 输出最终银豹采购单 (data/result)
```

### 技术注解
- **智能指纹识别**：通过 `header=None` 读取前 50 行，避免了因标题行位置不固定导致的识别失败。
- **原子化预处理**：每个供应商逻辑独立，预处理结果均为统一格式的中间文件，确立了系统的可扩展性。

---

## 3. 技术架构分层图 (Layered Architecture)

| 分层 | 技术栈 / 组件 | 功能描述 |
| :--- | :--- | :--- |
| **表现层 (Presentation)** | Tkinter, headless_api.py | 桌面 GUI 交互与 OpenClaw 命令行接口 |
| **业务逻辑层 (Business)** | Python 3.x, Pandas, OCRService | 核心数据清洗、条码分裂、供应商特征识别 |
| **数据访问层 (Data)** | Pandas (Excel Engine), Json | 对 Excel 模板、映射表、用户设置的读写 |
| **基础设施层 (Infrastructure)** | Queue, Logging, PyInstaller | 异步日志分发、全局错误处理、EXE 打包工具 |

---

## 4. 数据架构设计 (Data Architecture)

系统未采用传统关系型数据库，而是基于 **JSON + Excel** 的混合存储架构。

### 4.1 表间关系示意 (JSON Mapping)
```mermaid
erDiagram
    CONFIG_JSON ||--o{ BARCODE_MAPPING_JSON : "存储映射"
    BARCODE_MAPPING_JSON {
        string original_barcode "OCR识别出的原始条码"
        string target_barcode "系统目标条码"
    }
    ITEM_DATA_EXCEL ||--o{ PURCHASE_ORDER_EXCEL : "验证单价"
    ITEM_DATA_EXCEL {
        string barcode "条码 (主键)"
        float cost_price "进货价"
    }
```

### 4.2 存储方案
- **映射关系**：`barcode_mappings.json`。支持运行时动态更新，通过 `headless_api.py --update-mapping` 修改。
- **业务数据**：`templates/商品资料.xlsx`。作为单价校验的权威数据源。

---

## 5. 微服务与模块化设计 (Microservices & Modularity)

虽然系统目前采用单体架构（Monolithic Architecture）以适配桌面部署环境，但在逻辑上采用了**微服务式的模块化设计**：

- **服务拆分**：每个供应商逻辑（Rongcheng, Tobacco, YangBiyue）都是独立的类，具备高度自治性。
- **解耦机制**：通过统一的 `preprocess` 契约（输入：原始文件，输出：清洗后文件）进行交互，未来可轻松迁移至独立服务。
- **进程隔离**：GUI 主进程与业务处理线程通过 `queue.Queue` 进行解耦，确保处理逻辑不阻塞用户界面。

---

## 6. 部署架构图 (Deployment)

```mermaid
graph LR
    subgraph 生产服务器 (Windows)
        APP[orc-order-v2.exe]
        DATA[data/ 目录]
        LOGS[logs/ 目录]
    end

    subgraph 自动化平台
        OC[OpenClaw]
    end

    OC -- 命令行调用 --> APP
    APP -- 读写 --> DATA
    APP -- 记录 --> LOGS
```

### 部署要点
- **便携化**：通过 PyInstaller 将 Python 运行环境与依赖打包，实现单文件/单目录部署。
- **路径无关性**：系统内部通过 `os.path.abspath` 动态计算路径，支持安装在任意盘符。

---

## 6. 安全架构图 (Security)

```mermaid
graph TD
    A[外部输入] --> B{文件类型校验}
    B -- 非图片/Excel --> C[拒绝处理]
    B -- 图片/Excel --> D[清洗逻辑]
    D --> E{单价偏差校验}
    E -- 差值 > 1.0 --> F[生成警告日志/弹窗]
    E -- 正常 --> G[生成采购单]
    G --> H[日志埋点与审计]
```

### 安全策略
- **数据隔离**：所有处理后的文件存放在 `data/output` 和 `data/result`，不修改原始输入文件。
- **权限控制**：系统运行于用户权限下，利用 Windows 文件系统权限保护配置文件。

---

## 7. 技术债务与优化建议 (Tech Debt & Optimization)

### 7.1 当前技术债务
1. **并发限制**：目前为单进程串行处理，面对超大规模订单（万行级）可能存在阻塞。
2. **持久化局限**：使用 JSON 存储映射关系在条码量达到万级时，查询性能会下降。
3. **环境依赖**：OCR 引擎高度依赖 Tesseract/PaddleOCR 等本地二进制库，部署复杂。

### 7.2 单点故障风险 (SPOF Analysis)
1. **本地环境强依赖**：所有 OCR 与 Excel 处理均在单一 Windows 节点，若该节点故障，OpenClaw 对接将完全中断。
2. **核心模板丢失**：`templates/` 下的商品资料或采购单模板缺失会导致全流程崩溃。
3. **OCR 精度波动**：OCR 结果受图片质量影响，若 OCR 识别条码错误且无映射表，则该行数据将丢失。

### 7.3 架构优化建议方案
- **容灾备份**：建议将 `templates/` 和 `barcode_mappings.json` 定期备份至远程 Git 仓库（如 Gitea）。
- **分布式识别**：引入 PaddleOCR 服务端，支持多节点并发 OCR 识别，减少本地算力依赖。
- **配置热更新**：支持从远程 URL 加载 `barcode_mappings.json`，实现多机条码库同步。
- **数据回退机制**：增加中间文件持久化策略，允许在处理失败时手动干预已清洗的 Excel。

---
*附注：本文档图表均采用 Mermaid 标准编写，可直接在 VS Code (需安装 Mermaid 插件) 或 [Mermaid Live Editor](https://mermaid.live/) 中实时渲染并导出为高清 PNG/SVG 格式。*

---
*文档版本：2.2.0 | 生成日期：2026-03-31*