# EWRS

**Repository Path**: lwt520/ewrs

## Basic Information

- **Project Name**: EWRS
- **Description**: 快递面单识别系统
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-04
- **Last Updated**: 2026-04-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 快递面单识别系统

## 一、系统概述

本系统是一个基于Python的快递面单智能识别系统，能够自动识别快递面单图片/PDF中的结构化数据，并导出到Excel表格中，替代人工手动录入。

### 核心功能

- **多格式支持**：支持JPG、PNG、PDF格式文件上传
- **智能识别**：
  - OCR文字识别：自动提取寄件人、收件人、地址、电话等信息
  - 条码识别：自动识别条形码获取快递单号
- **人工校验**：识别结果可在线编辑修正
- **批量处理**：支持批量上传、批量识别、批量导出
- **Excel导出**：支持自定义模板，自动填充数据

### 技术栈

- **后端**：Python 3.8+ / FastAPI
- **OCR**：EasyOCR（开源多语言OCR，支持中文）
- **条码识别**：pyzbar + OpenCV
- **PDF处理**：pdf2image
- **Excel处理**：pandas + openpyxl
- **前端**：纯HTML/CSS/JS（无需Node环境）

> **注意**：推荐使用 Python 3.10 - 3.12 版本。Python 3.14 部分依赖可能不兼容。

## 二、目录结构

```
express_ocr_system/
├── app/                          # 应用主目录
│   ├── __init__.py
│   ├── main.py                   # FastAPI主程序
│   ├── create_template.py        # 创建Excel模板脚本
│   ├── utils/                    # 工具类目录
│   │   ├── __init__.py
│   │   ├── ocr_utils.py          # OCR识别工具
│   │   ├── barcode_utils.py      # 条码识别工具
│   │   ├── excel_utils.py        # Excel处理工具
│   │   └── express_parser.py     # 快递面单解析器
│   ├── static/                   # 静态文件目录
│   │   └── index.html            # 前端页面
│   ├── templates/                # Excel模板目录
│   ├── uploads/                  # 上传文件临时目录
│   └── output/                   # 导出文件目录
├── requirements.txt              # Python依赖清单
├── run.bat                       # Windows启动脚本
├── run.sh                        # Linux/Mac启动脚本
└── README.md                     # 说明文档
```

## 三、环境搭建与运行

### 3.1 系统要求

- Python 3.8 或更高版本
- Windows / macOS / Linux

### 3.2 Windows环境

#### 方法一：使用启动脚本（推荐）

1. 双击运行 `run.bat`
2. 脚本会自动创建虚拟环境、安装依赖、启动服务
3. 浏览器访问 http://localhost:8000

#### 方法二：手动安装

```bash
# 1. 创建虚拟环境
python -m venv venv

# 2. 激活虚拟环境
venv\Scripts\activate

# 3. 安装依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 4. 启动服务
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

### 3.3 Linux/Mac环境

```bash
# 1. 添加执行权限
chmod +x run.sh

# 2. 运行启动脚本
./run.sh

# 或手动安装
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

### 3.4 PDF支持（可选）

如果需要处理PDF文件，需要安装poppler：

**Windows:**
1. 下载 poppler: https://github.com/oschwartz10612/poppler-windows/releases
2. 解压到任意目录（如 C:\Program Files\poppler）
3. 将 `bin` 目录添加到系统环境变量 PATH

**Linux (Ubuntu/Debian):**
```bash
sudo apt-get install poppler-utils
```

**macOS:**
```bash
brew install poppler
```

## 四、使用说明

### 4.1 基本使用流程

1. **上传文件**：点击上传区域或拖拽文件上传
2. **开始识别**：点击"开始识别"按钮
3. **查看结果**：识别完成后自动显示结果表格
4. **编辑修正**：可直接在表格中编辑，或点击"编辑"按钮详细修改
5. **导出Excel**：点击"导出Excel"按钮下载数据

### 4.2 API接口说明

系统提供以下REST API接口：

| 接口 | 方法 | 说明 |
|------|------|------|
| `/` | GET | 前端页面 |
| `/api/upload` | POST | 上传并识别文件 |
| `/api/recognize` | POST | 识别单个文件 |
| `/api/results` | GET | 获取所有识别结果 |
| `/api/results/{id}` | GET/PUT/DELETE | 获取/更新/删除单个结果 |
| `/api/export` | POST | 导出数据到Excel |
| `/api/download/{filename}` | GET | 下载Excel文件 |
| `/api/templates` | GET/POST | 获取/上传模板 |
| `/api/ocr/debug` | POST | OCR调试接口 |

详细API文档：http://localhost:8000/docs

### 4.3 Excel字段映射

| Excel列名 | 字段名 | 说明 |
|-----------|--------|------|
| 序 | sequence | 序号 |
| 日期 | date | 收发日期 |
| 寄件单位 | sender_company | 寄件公司 |
| 寄件人 | sender_name | 寄件人姓名 |
| 文件内容 | content | 托寄物 |
| 件数 | package_count | 包裹件数 |
| 重量 | weight | 包裹重量 |
| 收件人 | receiver_name | 收件人姓名 |
| 收件公司 | receiver_company | 收件公司 |
| 收件地址 | receiver_address | 收件地址 |
| 联系电话 | receiver_phone | 收件人电话 |
| 快递公司 | express_company | 快递公司名称 |
| 收发编号 | tracking_number | 快递单号 |
| 费用 | fee | 运费 |
| 促销 | promotion | 促销信息 |
| 付款方式 | payment_method | 付款方式 |
| 实收费用 | actual_fee | 实际费用 |

## 五、自定义配置

### 5.1 自定义Excel模板

1. 准备一个xlsx格式的Excel文件，第一行为表头
2. 表头名称需与默认模板一致，或修改 `excel_utils.py` 中的 `DEFAULT_HEADERS`
3. 将模板文件放到 `app/templates/` 目录
4. 通过API `/api/templates` 上传模板

### 5.2 添加新的快递公司

编辑 `express_parser.py` 中的 `EXPRESS_COMPANIES` 列表：

```python
EXPRESS_COMPANIES = [
    '顺丰', '顺丰速运', ...
    # 添加新的快递公司名称
]
```

### 5.3 修改识别规则

在 `express_parser.py` 中可以修改：
- 电话号码识别规则
- 地址识别规则
- 姓名识别规则
- 日期格式识别

## 六、打包为EXE（Windows）

使用 PyInstaller 打包：

```bash
# 安装PyInstaller
pip install pyinstaller

# 打包
pyinstaller --name "快递面单识别系统" \
    --onefile \
    --windowed \
    --add-data "app/static;app/static" \
    --add-data "app/templates;app/templates" \
    --hidden-import paddleocr \
    --hidden-import paddle \
    run.py
```

## 七、服务器部署

### 7.1 使用Gunicorn（Linux）

```bash
pip install gunicorn
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
```

### 7.2 使用Docker

创建 `Dockerfile`:

```dockerfile
FROM python:3.9-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

RUN apt-get update && apt-get install -y poppler-utils

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

构建并运行：

```bash
docker build -t express-ocr .
docker run -d -p 8000:8000 express-ocr
```

### 7.3 Nginx反向代理

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location /static {
        alias /path/to/express_ocr_system/app/static;
    }
}
```

## 八、常见问题与解决方案

### Q1: OCR识别不准确

**解决方案：**
1. 确保图片清晰，分辨率足够高
2. 检查图片是否有倾斜，可使用图像预处理
3. 尝试使用 `ocr_utils.py` 中的 `recognize_with_preprocess` 方法
4. 对于特定快递公司，可微调识别规则

### Q2: 条码识别失败

**解决方案：**
1. 确保条码区域清晰、无遮挡
2. 检查图片分辨率，建议300DPI以上
3. 尝试使用 `barcode_utils.py` 中的 `recognize_with_preprocess` 方法
4. 某些条码可能需要特定的识别参数

### Q3: PDF转换失败

**解决方案：**
1. 确保已正确安装 poppler
2. Windows用户检查环境变量是否配置正确
3. 尝试使用其他PDF库（如PyMuPDF）

### Q4: 内存占用过高

**解决方案：**
1. 减少批量处理的文件数量
2. 降低PDF转换的DPI（默认200）
3. 使用GPU版本的PaddlePaddle可提高效率

### Q5: 启动时报错 "DLL load failed"

**解决方案：**
1. 安装 Visual C++ Redistributable
2. 检查Python版本是否兼容
3. 尝试重新安装依赖

## 九、优化建议

### 9.1 识别准确率优化

1. **图像预处理**：对上传图片进行去噪、增强对比度等预处理
2. **模板匹配**：为不同快递公司创建识别模板
3. **规则优化**：根据实际数据调整识别规则
4. **模型微调**：使用快递面单数据微调OCR模型

### 9.2 性能优化

1. **批量处理**：使用异步处理提高批量识别效率
2. **缓存机制**：缓存OCR模型，避免重复加载
3. **GPU加速**：使用GPU版本的PaddlePaddle
4. **分布式部署**：多实例负载均衡

### 9.3 功能扩展

1. **数据库存储**：将识别结果存入数据库
2. **用户管理**：添加用户登录、权限管理
3. **历史记录**：保存识别历史，支持查询
4. **统计报表**：生成统计图表
5. **API集成**：对接快递公司API获取更多信息

## 十、技术支持

如有问题，请通过以下方式获取帮助：

1. 查看API文档：http://localhost:8000/docs
2. 检查日志输出
3. 使用 `/api/ocr/debug` 接口调试OCR识别结果

## 十一、许可证

本项目仅供学习和内部使用，请勿用于商业用途。