houhuan
5e69e5a841
- Dockerfile.backend: Python 3.11 + FastAPI + uvicorn - Dockerfile.frontend: Node 20 build + Nginx serve - docker-compose.yml: orchestration with data volume mount - nginx.conf: API/WebSocket proxy to backend - web/backend/requirements.txt: Python dependencies - .dockerignore: exclude venv/node_modules/data from build Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
230 lines
9.0 KiB
Markdown
230 lines
9.0 KiB
Markdown
# 益选 OCR 订单处理系统
|
||
|
||
面向零售与分销场景的采购单处理工具，支持图片 OCR → Excel 规范化 → 模板填充 → 合并导出全流程，输出适配银豹 (PosPal) POS 系统。
|
||
|
||
## 核心功能
|
||
|
||
- **智能供应商识别**：自动扫描 Excel 前 50 行内容特征，路由到对应的预处理逻辑（蓉城易购、烟草公司、杨碧月等）
|
||
- **图片 OCR**：调用百度 OCR 表格识别 API，将采购单图片转为结构化 Excel
|
||
- **规则引擎**：支持列映射、数据清洗、单位转换、规格推断、赠品标记等自动化规则
|
||
- **条码映射**：可配置的条码转换规则，支持运行时编辑和云端同步
|
||
- **单价校验**：自动比对 `商品资料.xlsx`，价差超过 1.0 元触发预警
|
||
- **云端同步**：通过 Gitea REST API 在多台设备间同步配置文件（条码映射、供应商配置、商品资料、采购模板）
|
||
- **拖拽一键处理**：拖入图片或 Excel 自动走完 OCR → 规范化 → 合并全流程
|
||
- **CLI 接口**：`headless_api.py` 支持无界面自动化调用
|
||
|
||
## 快速开始
|
||
|
||
### 桌面端 (GUI / CLI)
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# GUI 模式
|
||
python 启动器.py
|
||
|
||
# CLI 模式
|
||
python headless_api.py data/input/xxx.xlsx
|
||
python headless_api.py data/input/xxx.jpg --barcode 6920584471055 --target 6920584471017
|
||
|
||
# 打包 EXE
|
||
python build_exe.py
|
||
```
|
||
|
||
### Web 端
|
||
|
||
```bash
|
||
# 后端依赖
|
||
cd web/backend && pip install -r requirements.txt
|
||
|
||
# 前端依赖
|
||
cd web/frontend && npm install
|
||
|
||
# 启动后端 (端口 8000)
|
||
cd web && python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload
|
||
|
||
# 启动前端开发服务器 (端口 5173)
|
||
cd web/frontend && npm run dev
|
||
|
||
# 构建前端到后端静态目录
|
||
cd web/frontend && npm run build
|
||
# 构建后直接访问 http://localhost:8000 即可
|
||
|
||
# 生产部署 (仅后端，前端已内嵌)
|
||
cd web && python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
**默认账号：** `admin` / `admin123`（首次登录后建议修改密码）
|
||
|
||
### Docker 部署
|
||
|
||
```bash
|
||
# 构建并启动
|
||
docker-compose up -d --build
|
||
|
||
# 访问
|
||
# 前端: http://服务器IP:18888
|
||
# 后端 API: http://服务器IP:18889
|
||
|
||
# 查看日志
|
||
docker-compose logs -f
|
||
|
||
# 停止
|
||
docker-compose down
|
||
```
|
||
|
||
**端口说明：**
|
||
- `18888` — 前端 (Nginx)
|
||
- `18889` — 后端 API (FastAPI)
|
||
|
||
**数据持久化：** `data/` 目录挂载到宿主机，数据库和上传文件不会丢失。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├── 启动器.py # GUI 入口
|
||
├── headless_api.py # CLI 自动化接口
|
||
├── config.ini # 全局配置（API密钥、路径、Gitea）
|
||
├── config/
|
||
│ ├── config.ini # 配置副本
|
||
│ ├── barcode_mappings.json # 条码映射规则
|
||
│ └── suppliers_config.json # 供应商配置（列映射/规则引擎）
|
||
├── app/
|
||
│ ├── config/ # 配置管理（ConfigManager 单例）
|
||
│ ├── core/
|
||
│ │ ├── excel/ # Excel 处理（标准化、转换、合并、校验）
|
||
│ │ ├── handlers/ # 规则引擎、列映射、数据清洗、计算器
|
||
│ │ ├── ocr/ # 百度 OCR 客户端
|
||
│ │ ├── processors/ # 处理器（通用/烟草/OCR）
|
||
│ │ └── utils/ # 工具（日志、文件、字符串、云端同步、对话框）
|
||
│ ├── services/ # 业务服务（订单、OCR、处理器调度）
|
||
│ └── ui/ # GUI 模块（主题、日志、快捷键、主窗口）
|
||
├── web/ # Web 端
|
||
│ ├── backend/
|
||
│ │ ├── main.py # FastAPI 入口
|
||
│ │ ├── auth/ # JWT 认证（登录、Token、权限）
|
||
│ │ ├── routers/ # API 路由（文件、处理、记忆、条码、同步、任务、日志）
|
||
│ │ ├── services/ # 后端服务（任务管理、数据库、文件同步）
|
||
│ │ └── middleware/ # HTTP 日志中间件
|
||
│ └── frontend/
|
||
│ ├── src/
|
||
│ │ ├── views/ # 页面（Dashboard、Layout、文件管理、任务、日志等）
|
||
│ │ ├── stores/ # Pinia 状态管理（auth、processing）
|
||
│ │ ├── composables/ # 共享逻辑（useDebounce、useFileUtils、useFilePreview）
|
||
│ │ ├── api.ts # Axios 封装
|
||
│ │ └── router/ # Vue Router 路由
|
||
│ ├── package.json
|
||
│ └── vite.config.ts
|
||
├── templates/
|
||
│ ├── 银豹-采购单模板.xls # 输出模板（条码/采购量/赠送量/单价）
|
||
│ └── 商品资料.xlsx # 单价校验参考数据
|
||
├── data/
|
||
│ ├── input/ # 输入文件
|
||
│ ├── output/ # OCR 输出
|
||
│ ├── result/ # 最终采购单
|
||
│ └── web_data.db # Web 端数据库（SQLite）
|
||
└── tests/ # 单元测试（191 个）
|
||
```
|
||
|
||
## Web 端功能
|
||
|
||
基于 Vue 3 + Element Plus + FastAPI 的浏览器端管理界面，与桌面端共享同一个 `data/` 目录。
|
||
|
||
### 处理中心 (Dashboard)
|
||
|
||
- **一键全流程**：上传图片或 Excel 后，一键完成 OCR → 标准化 → 合并全流程
|
||
- **批量 OCR / 批量处理**：可单独执行 OCR 识别或 Excel 标准化步骤
|
||
- **实时进度**：WebSocket 推送任务进度、日志、状态变更
|
||
- **多任务监控**：同时查看多个运行中任务的进度和日志
|
||
- **任务重试**：失败任务可查看错误详情并一键重试
|
||
|
||
### 文件管理
|
||
|
||
- **图片处理**：管理 `data/input/` 中的图片文件，支持上传、预览、批量 OCR、批量生成采购单
|
||
- **表格处理**：管理 `data/output/` 中的 Excel 文件，支持上传、预览、批量标准化处理
|
||
- **采购单管理**：管理 `data/result/` 中的采购单，支持预览、下载、合并、批量删除
|
||
- **实时同步**：页面加载时自动同步磁盘文件到数据库，新文件立即可见
|
||
- **清除处理缓存**：删除已处理的输出文件，允许重新处理
|
||
|
||
### 任务与日志
|
||
|
||
- **任务历史**：查看所有处理任务的状态、进度、日志，支持按状态和类型筛选
|
||
- **HTTP 日志**：记录所有 API 请求，支持按方法和状态码筛选
|
||
|
||
### 记忆库
|
||
|
||
- **产品记忆**：自动从 OCR 和处理结果中学习产品信息
|
||
- **置信度系统**：根据出现次数自动评估记忆可靠度
|
||
- **搜索与管理**：支持搜索、编辑、删除记忆条目
|
||
|
||
### 条码映射
|
||
|
||
- **映射规则管理**：添加、编辑、删除条码转换规则
|
||
- **批量操作**：支持批量导入和删除映射
|
||
|
||
### 云端同步
|
||
|
||
- **Gitea 同步**：通过 Gitea REST API 在多台设备间同步配置文件
|
||
- **一键推拉**：选择文件推送或拉取，无需 git 客户端
|
||
|
||
### 系统配置
|
||
|
||
- **配置编辑**：在浏览器中编辑系统配置（API 密钥、路径、参数）
|
||
- **修改密码**：支持修改 Web 端登录密码
|
||
|
||
### UI/UX
|
||
|
||
- **响应式布局**：适配桌面和移动端，小屏幕自动切换为抽屉式导航
|
||
- **全局错误处理**：未捕获的 Vue 错误自动显示用户提示
|
||
- **表单验证**：修改密码等操作有完整的输入验证
|
||
|
||
## 供应商智能路由
|
||
|
||
| 供应商 | 识别特征 | 处理逻辑 |
|
||
|--------|----------|----------|
|
||
| 烟草公司 | "专卖证号" 或 "510109104938" | B/E/G/H 列映射，数量×10，单价÷10 |
|
||
| 蓉城易购 | "RCDH" | E/N/Q/S 列映射，多条码分裂均分数量 |
|
||
| 杨碧月 | "经手人" + "杨碧月" | 列对齐，单位转换（件→瓶） |
|
||
| 通用供应商 | `suppliers_config.json` 配置 | 列映射 + 规则引擎 |
|
||
|
||
## 云端同步
|
||
|
||
通过 Gitea REST API 在多台设备间同步配置，无需 git 客户端。
|
||
|
||
**支持同步的文件：**
|
||
- 条码映射 (`barcode_mappings.json`)
|
||
- 供应商配置 (`suppliers_config.json`)
|
||
- 商品资料 (`templates/商品资料.xlsx`)
|
||
- 采购单模板 (`templates/银豹-采购单模板.xls`)
|
||
|
||
**配置方式：**
|
||
1. 系统设置 → 填入 Gitea 地址、仓库信息、Access Token
|
||
2. 主窗口 → "云端同步" 按钮 → 选择文件推拉
|
||
|
||
**Gitea 仓库：** `https://gitea.94kan.cn/houhuan/yixuan-sync-data`
|
||
|
||
## 配置说明
|
||
|
||
| 配置项 | 文件 | 说明 |
|
||
|--------|------|------|
|
||
| API 密钥 | `.env` 或 `config.ini` | 百度 OCR API，优先从环境变量读取 |
|
||
| Gitea Token | `.env` 或 `config.ini` | 云端同步 Token，优先从环境变量读取 |
|
||
| 供应商规则 | `config/suppliers_config.json` | 列映射、清洗规则、计算规则 |
|
||
| 条码映射 | `config/barcode_mappings.json` | 条码转换规则，运行时可更新 |
|
||
|
||
## 构建打包
|
||
|
||
```bash
|
||
pip install pyinstaller
|
||
python build_exe.py
|
||
# 输出: dist/OCR订单处理系统.exe
|
||
# 便携包: release/OCR订单处理系统.exe（含模板和商品资料）
|
||
```
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
python -m pytest tests/ -v
|
||
```
|