From 10ebe9240b5743cdd6a4f62fd33684b8d8a7b1c4 Mon Sep 17 00:00:00 2001
From: houhuan <houhuanya@gmail.com>
Date: Tue, 31 Mar 2026 09:27:00 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E7=B3=BB=E7=BB=9F?=
 =?UTF-8?q?=E6=9E=B6=E6=9E=84=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

添加 SYSTEM_ARCHITECTURE.md 文档，详细说明 OCR 订单处理系统的整体架构、业务流程图、技术栈、数据模型、部署方案及安全策略。文档包含 Mermaid 图表，用于可视化系统组件交互和数据处理流程，为项目维护和团队协作提供技术参考。
---
 docs/SYSTEM_ARCHITECTURE.md | 208 ++++++++++++++++++++++++++++++++++++
 1 file changed, 208 insertions(+)
 create mode 100644 docs/SYSTEM_ARCHITECTURE.md

diff --git a/docs/SYSTEM_ARCHITECTURE.md b/docs/SYSTEM_ARCHITECTURE.md
new file mode 100644
index 0000000..c6d3521
--- /dev/null
+++ b/docs/SYSTEM_ARCHITECTURE.md
@@ -0,0 +1,208 @@
+# 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*