# OCR图像识别测试功能使用说明

## 📚 功能概述

OCR图像识别测试页面用于测试阿里云OCR服务，支持通用文字识别、发票识别、身份证识别等功能。

## 🎯 已实现的功能

### 后端部分

#### 1. OCRController
**路径**: `ruoyi-system/src/main/java/com/ruoyi/system/controller/OCRController.java`

**接口列表**:
- `POST /system/ocr/recognize` - 上传图片进行OCR识别
- `GET /system/ocr/recognizeByUrl` - 通过URL进行OCR识别
- `POST /system/ocr/extractFields` - 提取OCR结果中的目标字段

#### 2. AliOCRUtil工具类
**路径**: `ruoyi-system/src/main/java/com/ruoyi/system/utils/AliOCRUtil.java`

**主要方法**:
- `recognizeTextByFile()` - 本地文件识别
- `recognizeTextByUrl()` - URL图片识别
- `recognizeInvoice()` - 发票识别
- `recognizeIdCard()` - 身份证识别
- `recognizeGeneral()` - 通用文字识别
- `extractTargetFields()` - 字段提取

### 前端部分

#### 1. OCR测试页面
**路径**: `ruoyi-ui/src/views/system/ocr/index.vue`

**功能特性**:
- 拖拽上传图片
- 图片预览
- 识别类型选择（通用/发票/身份证）
- 实时显示识别结果
- 自动提取关键字段
- 原始JSON数据查看
- 一键复制识别结果

#### 2. API接口封装
**路径**: `ruoyi-ui/src/api/system/ocr.js`

## 🚀 部署步骤

### 1. 执行菜单SQL

```bash
# 在MySQL中执行
mysql -u root -p your_database < sql/ocr_test_menu.sql
```

或在Navicat等工具中执行 `sql/ocr_test_menu.sql` 文件

### 2. 配置阿里云AccessKey

**文件**: `ruoyi-admin/src/main/resources/application.yml`

```yaml
ocr:
  accessKeyId: YOUR_ACCESS_KEY_ID
  accessKeySecret: YOUR_ACCESS_KEY_SECRET
```

**重要**: 请替换为你自己的阿里云AccessKey

### 3. 重启后端服务

```bash
cd ruoyi-admin
mvn spring-boot:run
```

### 4. 分配权限

登录后台管理系统：
1. 进入 **系统管理 > 角色管理**
2. 选择需要使用OCR功能的角色
3. 分配权限：`system:ocr:test` 和 `system:ocr:recognize`

### 5. 访问页面

菜单路径：**系统工具 > OCR测试**

URL: `http://localhost/system/ocr`

## 📖 使用指南

### 基本操作流程

1. **选择识别类型**
   - 通用文字识别：适用于普通文字内容
   - 发票识别：专门识别发票信息
   - 身份证识别：识别身份证正反面

2. **上传图片**
   - 拖拽图片到上传区域
   - 或点击上传区域选择文件
   - 支持JPG、PNG、BMP格式
   - 文件大小不超过4MB

3. **开始识别**
   - 点击"开始识别"按钮
   - 等待识别完成（通常1-3秒）

4. **查看结果**
   - 提取字段：自动提取的关键信息（金额、日期、备注等）
   - 完整识别内容：所有识别的文字
   - 原始JSON数据：阿里云返回的完整数据

5. **复制结果**
   - 点击"复制结果"按钮一键复制识别内容

### 识别类型说明

#### 通用文字识别 (General)
- 适用场景：各类文档、图片中的文字
- 返回内容：所有识别的文字及位置信息

#### 发票识别 (Invoice)
- 适用场景：增值税发票、普通发票、收据等
- 自动提取：发票号码、金额、日期、购买方、销售方等

#### 身份证识别 (IdCard)
- 适用场景：身份证正面和反面
- 自动提取：姓名、身份证号、地址、有效期等

## 🔧 配置说明

### OCRConfig配置类
**路径**: `ruoyi-system/src/main/java/com/ruoyi/system/config/OCRConfig.java`

```java
@Component
@ConfigurationProperties(prefix = "ocr")
public class OCRConfig {
    private String accessKeyId;
    private String accessKeySecret;
    // getter和setter
}
```

### 阿里云OCR API端点
默认使用杭州节点：`ocr-api.cn-hangzhou.aliyuncs.com`

如需更改，修改 `AliOCRUtil.java` 中的 `ENDPOINT` 常量。

## ⚠️ 注意事项

### 1. AccessKey安全
- **不要**将AccessKey提交到Git仓库
- 建议使用环境变量或配置中心管理
- 定期更换AccessKey

### 2. 文件大小限制
- 前端限制：4MB
- 阿里云限制：根据套餐不同，通常为4-10MB
- 超过限制会导致识别失败

### 3. 识别准确率
- 图片清晰度影响识别准确率
- 建议使用300dpi以上的图片
- 避免模糊、倾斜、反光的图片

### 4. 费用说明
- 阿里云OCR按调用次数收费
- 新用户有免费额度
- 建议在生产环境中设置调用限制

### 5. 临时文件处理
- 上传的图片会保存到临时目录
- 识别完成后自动删除
- 临时目录：`System.getProperty("java.io.tmpdir")`

## 🐛 常见问题

### 1. 识别失败：AccessKey错误
**原因**: 配置的AccessKey不正确

**解决**:
- 检查 `application.yml` 中的配置
- 确认AccessKey ID和Secret正确
- 确认账号已开通OCR服务

### 2. 上传后无响应
**原因**: 文件过大或网络问题

**解决**:
- 检查图片大小是否超过4MB
- 检查网络连接
- 查看浏览器控制台错误信息

### 3. 识别结果为空
**原因**: 图片质量问题或不支持的图片格式

**解决**:
- 使用清晰的图片
- 确保图片包含可识别的文字
- 尝试转换图片格式

### 4. 权限不足
**原因**: 用户角色未分配OCR权限

**解决**:
- 联系管理员分配权限
- 或在角色管理中勾选相关权限

## 📝 扩展开发

### 添加新的识别类型

1. 在前端页面添加选项：
```vue
<el-option label="营业执照识别" value="BusinessLicense" />
```

2. 后端会自动支持，无需修改代码

### 自定义字段提取

修改 `AliOCRUtil.java` 中的 `extractTargetFields()` 方法：

```java
// 添加自定义提取逻辑
if (text.contains("自定义关键字")) {
    extracted.put("customField", text);
}
```

## 📚 相关文档

- [阿里云OCR官方文档](https://help.aliyun.com/document_detail/442275.html)
- [RuoYi框架文档](http://doc.ruoyi.vip/)

## 📞 技术支持

如有问题，请联系技术支持团队或提交Issue。