orc-order-v2/docs/SYSTEM_ARCHITECTURE.md

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

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

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

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)

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

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)

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)

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)

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 中实时渲染并导出为高清 PNG/SVG 格式。

---

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