oneos-backend/yudao-module-ocr

OCR 识别模块

概述

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

功能特性

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

架构设计

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

快速开始

1. 配置

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

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

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

2. API 调用

识别行驶证

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. 创建配置类

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

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

2. 实现客户端

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() 中添加：

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

4. 添加配置

在 OcrProperties 中添加：

private TencentOcrClientConfig tencent;

在 OcrAutoConfiguration 中初始化：

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

添加新识别场景

1. 定义结果类

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

2. 扩展客户端接口

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