feat: 实现 OCR 模块和车辆上牌管理功能

- 新增 yudao-module-ocr 模块 - OCR API 模块：定义 Feign 接口和 DTO - OCR Server 模块：实现行驶证识别功能 - 集成百度 OCR SDK - 支持多厂商扩展（百度/腾讯/阿里云） - 新增车辆上牌管理功能 - 数据库表：asset_vehicle_registration - 完整的 CRUD 接口 - 行驶证识别接口（集成 OCR） - 车辆匹配功能（根据 VIN） - 确认上牌功能（更新车辆信息） - 技术实现 - 遵循 BPM/System 模块的 RPC API 模式 - 使用 Feign 实现服务间调用 - Base64 编码传输图片数据 - 统一返回格式 CommonResult<T> - 文档 - OCR 模块使用文档 - OCR 部署指南 - 车辆上牌管理总结 - API 集成规划和总结
2026-03-12 20:33:21 +08:00
parent 0706b51acd
commit 78a6cde22d
50 changed files with 3886 additions and 0 deletions
--- a/yudao-module-ocr/README.md
+++ b/yudao-module-ocr/README.md
@@ -0,0 +1,206 @@
+# 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