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

# OCR 模块 API 集成规划

## 目标
按照 BPM/System 模块的 API 集成模式，将 OCR 模块改造为标准的 RPC API 服务，供其他模块（如 Asset 模块）通过 Feign 调用。

## 当前架构分析

### BPM/System 模块的 API 模式

**API 模块（yudao-module-xxx-api）**
- 定义 Feign 接口（如 `BpmProcessInstanceApi.java`）
- 使用 `@FeignClient(name = ApiConstants.NAME)` 注解
- 定义 API 常量（`ApiConstants.java`）
- 定义 DTO 对象（用于 RPC 传输）

**Server 模块（yudao-module-xxx-server）**
- 实现 API 接口（如 `BpmProcessInstanceApiImpl.java`）
- 使用 `@RestController` 注解（提供 RESTful API）
- 注入 Service 层，调用业务逻辑
- 返回 `CommonResult<T>` 包装结果

## OCR 模块改造规划

### Phase 1: 重构 OCR API 模块

#### 1.1 创建 ApiConstants
**文件**: `yudao-module-ocr-api/src/main/java/cn/iocoder/yudao/module/ocr/enums/ApiConstants.java`

```java
package cn.iocoder.yudao.module.ocr.enums;

import cn.iocoder.yudao.framework.common.enums.RpcConstants;

public class ApiConstants {
    /**
     * 服务名（需要和 spring.application.name 保持一致）
     */
    public static final String NAME = "ocr-server";

    public static final String PREFIX = RpcConstants.RPC_API_PREFIX + "/ocr";

    public static final String VERSION = "1.0.0";
}
```

#### 1.2 创建 DTO 对象
**文件**: `yudao-module-ocr-api/src/main/java/cn/iocoder/yudao/module/ocr/api/dto/VehicleLicenseRespDTO.java`

```java
package cn.iocoder.yudao.module.ocr.api.dto;

import lombok.Data;
import java.io.Serializable;
import java.time.LocalDate;

@Data
public class VehicleLicenseRespDTO implements Serializable {
    private String vin;
    private String plateNo;
    private String brand;
    private String vehicleType;
    private String owner;
    private String useCharacter;
    private String engineNo;
    private LocalDate registerDate;
    private LocalDate issueDate;
    private String inspectionRecord;
    private LocalDate scrapDate;
    private String curbWeight;
    private String totalMass;
    private String approvedPassengerCapacity;
}
```

#### 1.3 创建 Feign API 接口
**文件**: `yudao-module-ocr-api/src/main/java/cn/iocoder/yudao/module/ocr/api/OcrApi.java`

```java
package cn.iocoder.yudao.module.ocr.api;

import cn.iocoder.yudao.framework.common.pojo.CommonResult;
import cn.iocoder.yudao.module.ocr.api.dto.VehicleLicenseRespDTO;
import cn.iocoder.yudao.module.ocr.enums.ApiConstants;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;

@FeignClient(name = ApiConstants.NAME)
@Tag(name = "RPC 服务 - OCR 识别")
public interface OcrApi {

    String PREFIX = ApiConstants.PREFIX + "/recognition";

    @PostMapping(PREFIX + "/vehicle-license")
    @Operation(summary = "识别行驶证（提供给内部模块）")
    @Parameter(name = "imageData", description = "图片数据（Base64编码）", required = true)
    @Parameter(name = "provider", description = "OCR厂商（可选）", example = "baidu")
    CommonResult<VehicleLicenseRespDTO> recognizeVehicleLicense(
            @RequestParam("imageData") String imageData,
            @RequestParam(value = "provider", required = false) String provider);
}
```

### Phase 2: 实现 OCR API

#### 2.1 创建 API 实现类
**文件**: `yudao-module-ocr-server/src/main/java/cn/iocoder/yudao/module/ocr/api/OcrApiImpl.java`

```java
package cn.iocoder.yudao.module.ocr.api;

import cn.hutool.core.codec.Base64;
import cn.iocoder.yudao.framework.common.pojo.CommonResult;
import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
import cn.iocoder.yudao.module.ocr.api.dto.VehicleLicenseRespDTO;
import cn.iocoder.yudao.module.ocr.framework.ocr.core.client.OcrClient;
import cn.iocoder.yudao.module.ocr.framework.ocr.core.client.OcrClientFactory;
import cn.iocoder.yudao.module.ocr.framework.ocr.core.result.VehicleLicenseResult;
import lombok.extern.slf4j.Slf4j;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.RestController;

import jakarta.annotation.Resource;

import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;

@RestController
@Validated
@Slf4j
public class OcrApiImpl implements OcrApi {

    @Resource
    private OcrClientFactory ocrClientFactory;

    @Override
    public CommonResult<VehicleLicenseRespDTO> recognizeVehicleLicense(String imageData, String provider) {
        log.info("[recognizeVehicleLicense][开始识别行驶证，provider：{}]", provider);

        // Base64 解码图片数据
        byte[] imageBytes = Base64.decode(imageData);

        // 获取 OCR 客户端
        OcrClient ocrClient = provider != null
            ? ocrClientFactory.getClient(provider)
            : ocrClientFactory.getDefaultClient();

        // 调用识别
        VehicleLicenseResult result = ocrClient.recognizeVehicleLicense(imageBytes);

        // 转换为 DTO
        VehicleLicenseRespDTO respDTO = BeanUtils.toBean(result, VehicleLicenseRespDTO.class);

        log.info("[recognizeVehicleLicense][识别完成，VIN：{}，车牌号：{}]",
                respDTO.getVin(), respDTO.getPlateNo());

        return success(respDTO);
    }
}
```

### Phase 3: Asset 模块集成 OCR API

#### 3.1 添加 OCR API 依赖
**文件**: `yudao-module-asset/yudao-module-asset-server/pom.xml`

```xml
<!-- OCR 模块 API -->
<dependency>
    <groupId>cn.iocoder.cloud</groupId>
    <artifactId>yudao-module-ocr-api</artifactId>
    <version>${revision}</version>
</dependency>
```

#### 3.2 修改 VehicleRegistrationServiceImpl
**文件**: `VehicleRegistrationServiceImpl.java`

```java
@Service
@Validated
@Slf4j
public class VehicleRegistrationServiceImpl implements VehicleRegistrationService {

    @Resource
    private VehicleRegistrationMapper vehicleRegistrationMapper;

    @Resource
    private VehicleBaseMapper vehicleBaseMapper;

    @Resource
    private OcrApi ocrApi; // 注入 OCR API

    @Override
    public VehicleLicenseRecognizeRespVO recognizeVehicleLicense(byte[] imageData) {
        long startTime = System.currentTimeMillis();

        // Base64 编码图片数据
        String imageDataBase64 = Base64.encode(imageData);

        // 调用 OCR API
        CommonResult<VehicleLicenseRespDTO> result = ocrApi.recognizeVehicleLicense(imageDataBase64, null);

        if (!result.isSuccess()) {
            throw exception(new ErrorCode(500, "OCR识别失败：" + result.getMsg()));
        }

        VehicleLicenseRespDTO ocrResult = result.getData();
        long costTime = System.currentTimeMillis() - startTime;

        // 转换为响应 VO
        VehicleLicenseRecognizeRespVO respVO = new VehicleLicenseRecognizeRespVO();
        BeanUtil.copyProperties(ocrResult, respVO);
        respVO.setOcrProvider("baidu");
        respVO.setOcrCostTime((int) costTime);

        // 根据 VIN 查找车辆
        if (StrUtil.isNotBlank(ocrResult.getVin())) {
            VehicleBaseDO vehicle = vehicleBaseMapper.selectOne(new LambdaQueryWrapper<VehicleBaseDO>()
                    .eq(VehicleBaseDO::getVin, ocrResult.getVin())
                    .last("LIMIT 1"));

            if (vehicle != null) {
                respVO.setVehicleId(vehicle.getId());
                respVO.setVehicleModelId(vehicle.getVehicleModelId());
                respVO.setMatchMethod("exact");
                respVO.setMatchConfidence(new BigDecimal("100.00"));
                log.info("[recognizeVehicleLicense][找到匹配车辆，车辆ID：{}]", vehicle.getId());
            } else {
                respVO.setMatchMethod("none");
                respVO.setMatchConfidence(BigDecimal.ZERO);
                log.warn("[recognizeVehicleLicense][未找到匹配车辆，VIN：{}]", ocrResult.getVin());
            }
        }

        return respVO;
    }

    // ... 其他方法保持不变
}
```

## 实施步骤

### Step 1: 重构 OCR API 模块
1. ✅ 创建 `ApiConstants.java`
2. ✅ 创建 `VehicleLicenseRespDTO.java`
3. ✅ 创建 `OcrApi.java` 接口
4. ✅ 移除现有的错误码常量（已在 api 模块中）

### Step 2: 实现 OCR API
1. ✅ 创建 `OcrApiImpl.java`
2. ✅ 实现 `recognizeVehicleLicense` 方法
3. ✅ 添加日志和异常处理

### Step 3: 集成到 Asset 模块
1. ✅ 修改 `VehicleRegistrationServiceImpl.java`
2. ✅ 注入 `OcrApi`
3. ✅ 实现车辆匹配逻辑
4. ✅ 测试端到端流程

### Step 4: 测试验证
1. ✅ 单元测试
2. ✅ 集成测试
3. ✅ 端到端测试

## 关键改动点

### 1. 图片传输方式
- **原方案**: 直接传输 `byte[]`（不适合 Feign）
- **新方案**: Base64 编码后传输 `String`（适合 HTTP/Feign）

### 2. 返回值类型
- **原方案**: 直接返回 `VehicleLicenseResult`（内部类）
- **新方案**: 返回 `CommonResult<VehicleLicenseRespDTO>`（标准 RPC 响应）

### 3. 模块依赖
- **原方案**: Asset 模块依赖 OCR Server 模块（耦合）
- **新方案**: Asset 模块只依赖 OCR API 模块（解耦）

## 优势

1. **标准化**: 遵循项目统一的 RPC API 模式
2. **解耦**: Asset 模块不依赖 OCR 的实现细节
3. **可扩展**: 其他模块也可以轻松集成 OCR 服务
4. **可测试**: 可以 Mock OcrApi 进行单元测试
5. **可维护**: 清晰的模块边界和职责划分

## 注意事项

1. **服务名配置**: 确保 `ocr-server` 的 `spring.application.name` 与 `ApiConstants.NAME` 一致
2. **Feign 配置**: 确保 Feign 客户端配置正确（超时、重试等）
3. **图片大小限制**: Base64 编码后会增大约 33%，需要注意 HTTP 请求大小限制
4. **性能考虑**: 对于大图片，考虑使用文件服务 + URL 传递方式

---

**规划版本**: v1.0
**创建日期**: 2026-03-12
**状态**: 待实施