docs: 添加系统架构文档
添加 SYSTEM_ARCHITECTURE.md 文档，详细说明 OCR 订单处理系统的整体架构、业务流程图、技术栈、数据模型、部署方案及安全策略。文档包含 Mermaid 图表，用于可视化系统组件交互和数据处理流程，为项目维护和团队协作提供技术参考。
This commit is contained in:
parent
96cdb0f62e
commit
10ebe9240b
208
docs/SYSTEM_ARCHITECTURE.md
Normal file
208
docs/SYSTEM_ARCHITECTURE.md
Normal file
@ -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*
|
||||
Loading…
Reference in New Issue
Block a user