oneos-backend/yudao-module-ocr/README.md

# OCR 识别模块

## 概述

OCR 识别模块（yudao-module-ocr）提供图像识别服务，支持行驶证、驾驶证等多种证件识别。采用策略模式设计，支持多厂商切换（百度、腾讯、阿里等）。

## 功能特性

- ✅ 行驶证识别（已实现）
- 🔲 驾驶证识别（预留）
- 🔲 身份证识别（预留）
- 🔲 营业执照识别（预留）

## 架构设计

```
Controller (统一入口)
    ↓
OcrService (业务服务层)
    ↓
OcrClientFactory (客户端工厂)
    ↓
OcrClient (客户端接口)
    ↓
├── BaiduOcrClient (百度实现)
├── TencentOcrClient (腾讯实现 - 预留)
└── AliyunOcrClient (阿里实现 - 预留)
```

## 快速开始

### 1. 配置

在 `application.yaml` 或 Nacos 配置中心添加：

```yaml
ocr:
  # 默认使用的厂商
  default-provider: baidu

  # 百度 OCR 配置
  baidu:
    app-id: your-app-id
    api-key: your-api-key
    secret-key: your-secret-key
```

### 2. API 调用

**识别行驶证**

```bash
POST /admin-api/ocr/vehicle-license
Content-Type: multipart/form-data

参数：
- file: 行驶证图片文件（必填）
- provider: OCR 厂商（可选，默认使用配置的厂商）

响应示例：
{
  "code": 0,
  "data": {
    "vin": "LSVAM4189E2123456",
    "plateNo": "粤A12345",
    "brand": "比亚迪秦PLUS DM-i",
    "vehicleType": "小型轿车",
    "owner": "张三",
    "useCharacter": "非营运",
    "engineNo": "BYD123456",
    "registerDate": "2023-01-01",
    "issueDate": "2023-01-01",
    "inspectionRecord": "2026-06",
    "scrapDate": "2035-12-31",
    "curbWeight": "1500",
    "totalMass": "1875",
    "approvedPassengerCapacity": "5"
  },
  "msg": "success"
}
```

## 扩展指南

### 添加新厂商

1. **创建配置类**

```java
@Data
public class TencentOcrClientConfig implements OcrClientConfig {
    private String secretId;
    private String secretKey;

    @Override
    public String getProvider() {
        return "tencent";
    }
}
```

2. **实现客户端**

```java
public class TencentOcrClient extends AbstractOcrClient<TencentOcrClientConfig> {

    public TencentOcrClient(TencentOcrClientConfig config) {
        super(config);
    }

    @Override
    protected void doInit() {
        // 初始化腾讯 OCR SDK
    }

    @Override
    public VehicleLicenseResult recognizeVehicleLicense(byte[] imageData) {
        // 调用腾讯 OCR API
    }
}
```

3. **注册到工厂**

在 `OcrClientFactoryImpl.createClient()` 中添加：

```java
case "tencent":
    return new TencentOcrClient((TencentOcrClientConfig) config);
```

4. **添加配置**

在 `OcrProperties` 中添加：

```java
private TencentOcrClientConfig tencent;
```

在 `OcrAutoConfiguration` 中初始化：

```java
if (properties.getTencent() != null) {
    factory.createOrUpdateClient("tencent", properties.getTencent());
}
```

### 添加新识别场景

1. **定义结果类**

```java
@Data
public class DriverLicenseResult {
    private String name;
    private String licenseNo;
    // ...
}
```

2. **扩展客户端接口**

```java
public interface OcrClient {
    VehicleLicenseResult recognizeVehicleLicense(byte[] imageData);
    DriverLicenseResult recognizeDriverLicense(byte[] imageData); // 新增
}
```

3. **实现各厂商客户端**

在 `BaiduOcrClient` 等类中实现新方法。

4. **添加 Service 和 Controller**

在 `OcrService` 和 `OcrController` 中添加对应方法。

## 注意事项

1. **API 密钥安全**：不要将密钥硬编码，使用配置中心管理
2. **图片大小限制**：百度 OCR 限制图片大小 4MB
3. **并发控制**：百度 OCR 有 QPS 限制，需要考虑限流
4. **错误处理**：网络异常、识别失败等需要友好的错误提示

## 错误码

| 错误码 | 说明 |
|--------|------|
| 1_009_001_000 | 不支持的 OCR 厂商 |
| 1_009_001_001 | 不支持的识别场景 |
| 1_009_001_002 | 图片格式不正确或已损坏 |
| 1_009_001_003 | 图片大小超过限制 |
| 1_009_001_004 | 识别失败 |
| 1_009_001_005 | OCR 客户端配置无效 |

## 依赖

- Spring Boot 3.5.9
- 百度 OCR SDK 4.16.18
- MyBatis Plus
- MapStruct
- Lombok

## 许可证

Apache License 2.0