feat: implement PaddleOCR adapter with Baidu Qianfan protocol support for PDF OCR

[XinyuZhang132]

No description provided.

[szl97]

@claude 检查提交的代码，使用中文回复

[szl97]

Claude finished @szl97's task —— View job

---

代码审查任务清单

• 阅读并分析所有变更的文件
• 审查PaddleOCR适配器的实现
• 检查请求和响应模型的设计
• 审查验证逻辑的修改
• 检查代码规范和最佳实践
• 提供详细的审查反馈

代码审查结果

✅ 总体评价

这是一个高质量的PaddleOCR PDF OCR功能实现，代码结构清晰，遵循了现有的架构模式。整体实现符合项目的编码规范和设计原则。

🔍 详细审查反馈

1. 架构设计 (优秀)

• 正确继承了 GeneralAdaptor<BaiduOcrProperty> 接口
• 遵循了项目现有的协议适配器模式
• 使用了合适的依赖注入（@Autowired）和组件注册（@Component("paddleOCR")）

2. 请求处理逻辑 (良好，有改进空间)

优点：

• 支持多种输入方式：file_id、URL、Base64 编码
• 正确处理了 extra_body 字段的映射
• 合理的参数校验机制

建议改进：

// api/server/src/main/java/com/ke/bella/openapi/protocol/ocr/general/PaddleOCRAdaptor.java:84-89
if (extraBody == null || !extraBody.containsKey("fileType")) {
    throw new IllegalArgumentException(
        "fileType is required when using file_id. " +
        "Please specify fileType in request body: 0 for PDF, 1 for image"
    );
}

问题： 异常信息使用英文，建议本地化为中文以保持一致性

3. 输入验证 (优秀)

ExactlyOneOfValidator 类的更新：

• 正确扩展了验证逻辑以支持 extra_body 中的 file 字段
• 验证逻辑严谨，确保四选一的约束

ExactlyOneOf 注解的更新：

• 错误消息已本地化为中文，与系统一致

4. 内存管理 (优秀)

PaddleOCRRequest 类：

// api/server/src/main/java/com/ke/bella/openapi/protocol/ocr/general/PaddleOCRRequest.java:99-105
@Override
public void clearLargeData() {
    if (!isCleared()) {
        this.file = null;
        super.clearLargeData();
    }
}

• 正确重写了 clearLargeData() 方法
• 清理 file 字段而不是默认的 image 字段，符合 PaddleOCR 的数据结构

5. 错误处理 (良好)

响应转换逻辑：

// api/server/src/main/java/com/ke/bella/openapi/protocol/ocr/general/PaddleOCRAdaptor.java:171-182
private OcrGeneralResponse responseConvert(PaddleOCRResponse response) {
    if (response.getError() != null) {
        return buildErrorResponse(response);
    }
    
    return OcrGeneralResponse.builder()
            .requestId(response.getId())
            .data(response.getResult())
            .build();
}

• 正确处理了 PaddleOCR 的错误响应格式
• 保留了完整的 result 对象，避免信息丢失

6. 代码规范 (优秀)

• 使用了 Lombok 注解减少样板代码
• 正确的 Jackson 注解配置（@JsonNaming, @JsonInclude）
• 方法命名清晰，注释详细
• 遵循了项目的代码风格

⚠️ 潜在改进点

1. 异常信息本地化

   // 建议将英文异常信息改为中文，保持一致性
   throw new IllegalArgumentException("使用file_id时必须提供fileType参数，请在请求体中指定：0表示PDF，1表示图像");

2. 参数提取逻辑

   // api/server/src/main/java/com/ke/bella/openapi/protocol/ocr/general/PaddleOCRAdaptor.java:144-153
   @SuppressWarnings("unchecked")
   private <T> void extractField(Map<String, Object> map, String key, Class<T> type,
                                  java.util.function.Consumer<T> setter) {
       if (map.containsKey(key)) {
           Object value = map.get(key);
           if (type.isInstance(value)) {
               setter.accept((T) value);
           }
       }
   }

   建议： 考虑添加类型转换失败的日志记录，便于调试

3. 常量定义

   // 建议为文件类型定义常量
   public static final int FILE_TYPE_PDF = 0;
   public static final int FILE_TYPE_IMAGE = 1;

✅ 测试建议

1. 测试不同输入方式的场景：file_id、URL、Base64
2. 测试 fileType 参数的校验逻辑
3. 测试错误响应的处理
4. 测试内存清理功能

🎯 总结

这是一个高质量的实现，代码结构清晰，错误处理完善，符合项目架构。主要建议是将异常信息本地化为中文，以及考虑添加更详细的参数转换日志。整体来说，代码可以合并。

---

[Jiakaic]

不太清楚ocr其他渠道对file的要求，感觉这个多种file的转换适合往外部放一放？（如果有别的渠道也需要的话） 可以先不动