rjuqwhnt

api-web/api-interface/src/main/java/com/heyu/api/controller/car/RecognizeDrivingLicenseController.java

@@ -21,8 +21,21 @@ import java.util.Map;
 
 
 /**
- * 行驶证识别。
+ * 行驶证识别控制器
- * https://console.bce.baidu.com/support/?_=1740219852952&timestamp=1740323990690#/api?product=AI&project=%E6%96%87%E5%AD%97%E8%AF%86%E5%88%AB&parent=%E4%BA%A4%E9%80%9A%E5%9C%BA%E6%99%AFOCR&api=rest%2F2.0%2Focr%2Fv1%2Fvehicle_license&method=post
+ *
+ * <p>提供行驶证OCR识别功能，基于百度云交通场景OCR接口实现</p>
+ * <p>支持功能：</p>
+ * <ul>
+ *   <li>行驶证正面识别：包含号牌号码、车辆类型、所有人、使用性质等基本信息</li>
+ *   <li>行驶证反面识别：包含核定载人数、总质量、检验记录等详细信息</li>
+ *   <li>支持图片URL和Base64两种输入方式</li>
+ *   <li>支持图像方向自动矫正、质量告警等高级功能</li>
+ * </ul>
+ *
+ * <p>接口文档：https://console.bce.baidu.com/support/#/api?product=AI&project=文字识别&parent=交通场景OCR&api=rest%2F2.0%2Focr%2Fv1%2Fvehicle_license&method=post</p>
+ *
+ * @author heyu
+ * @since 1.0.0
  */
 @Slf4j
 @RestController
@@ -30,9 +43,13 @@ import java.util.Map;
 @SuppressWarnings("unchecked")
 public class RecognizeDrivingLicenseController extends BaseController {
 
-    // http://localhost:8888/driving/license/recognize
+    /**
-    // {"side":"front","imageUrl":"https://q1.itc.cn/q_70/images03/20241016/622799fe72cb49f49e16b7f253e75b29.jpeg"}
+     * 行驶证识别接口
-    // https://api.1024api.com/api-interface/driving/license/recognize
+     * 支持行驶证正反面识别，使用百度云OCR接口
+     *
+     * @param request 行驶证识别请求对象，包含图片URL或base64编码、正反面标识等参数
+     * @return 识别结果，正面返回 {@link RecognizeDrivingLicenseFaceResp}，反面返回 {@link RecognizeDrivingLicenseBackResp}
+     */
     @EbAuthentication(tencent = ApiConstants.TENCENT_AUTH)
     @PostMapping("/recognize")
     public R<Object> recognize(@RequestBody VehicleLicenseRequest request) {
@@ -65,6 +82,12 @@ public class RecognizeDrivingLicenseController extends BaseController {
         return result;
     }
 
+    /**
+     * 将前端请求对象转换为百度云请求对象
+     *
+     * @param request 前端行驶证识别请求
+     * @return 百度云行驶证识别请求对象
+     */
     private BVehicleLicenseRequest toBaiduRequest(VehicleLicenseRequest request) {
         BVehicleLicenseRequest bVehicleLicenseRequest = new BVehicleLicenseRequest();
         if (request == null) {
@@ -78,6 +101,12 @@ public class RecognizeDrivingLicenseController extends BaseController {
         return bVehicleLicenseRequest;
     }
 
+    /**
+     * 校验请求参数的合法性
+     *
+     * @param request 百度云请求对象
+     * @return 校验通过返回null，否则返回错误信息
+     */
     private String checkRequest(BVehicleLicenseRequest request) {
         if (!hasImage(request)) {
             return "imageUrl和imageBase64不能同时为空";
@@ -97,10 +126,22 @@ public class RecognizeDrivingLicenseController extends BaseController {
         return null;
     }
 
+    /**
+     * 检查请求中是否包含有效的图片数据
+     *
+     * @param request 百度云请求对象
+     * @return 如果包含imageUrl或imageBase64则返回true
+     */
     private boolean hasImage(BVehicleLicenseRequest request) {
         return request != null && (!isBlank(request.getImageUrl()) || !isBlank(request.getImageBase64()));
     }
 
+    /**
+     * 构建百度云OCR接口的请求参数字符串
+     *
+     * @param request 百度云请求对象
+     * @return HTTP请求参数字符串
+     */
     private String getContent(BVehicleLicenseRequest request) {
         StringBuffer sb = getImageContent(request);
         if (StringUtils.isNotBlank(request.getDetectDirection())) {
@@ -121,6 +162,12 @@ public class RecognizeDrivingLicenseController extends BaseController {
         return sb.toString();
     }
 
+    /**
+     * 获取图片相关的请求参数
+     *
+     * @param request 百度云请求对象
+     * @return 包含image或url参数的StringBuffer
+     */
     private StringBuffer getImageContent(BVehicleLicenseRequest request) {
         StringBuffer sb = new StringBuffer();
         if (StringUtils.isNotBlank(request.getImageBase64())) {
@@ -133,14 +180,33 @@ public class RecognizeDrivingLicenseController extends BaseController {
         return sb;
     }
 
+    /**
+     * 检查字符串是否不在允许的true/false范围内
+     *
+     * @param value 待检查的字符串
+     * @return 如果不是"true"或"false"返回true
+     */
     private boolean checkNotTrueFalse(String value) {
         return !ApiConstants.trueOrFalse.contains(value);
     }
 
+    /**
+     * 检查字符串是否不在允许的front/back范围内
+     *
+     * @param value 待检查的字符串
+     * @return 如果不是"front"或"back"返回true
+     */
     private boolean checkNotFrontBack(String value) {
         return !ApiConstants.frontOrback.contains(value);
     }
 
+    /**
+     * 根据正反面标识转换为对应的响应对象
+     *
+     * @param side 行驶证正反面标识（front正面，back反面）
+     * @param data 百度云OCR识别的原始数据
+     * @return 正面返回 {@link RecognizeDrivingLicenseFaceResp}，反面返回 {@link RecognizeDrivingLicenseBackResp}
+     */
     private Object toRecognizeResp(String side, Map<String, Object> data) {
         if (ApiConstants.front.equals(side)) {
             return toFaceResp(data);
@@ -148,6 +214,12 @@ public class RecognizeDrivingLicenseController extends BaseController {
         return toBackResp(data);
     }
 
+    /**
+     * 将百度云OCR识别结果转换为行驶证正面响应对象
+     *
+     * @param data 百度云OCR识别的原始数据
+     * @return 行驶证正面响应对象，包含号牌号码、车辆类型、所有人等信息
+     */
     private RecognizeDrivingLicenseFaceResp toFaceResp(Map<String, Object> data) {
         RecognizeDrivingLicenseFaceResp faceResp = new RecognizeDrivingLicenseFaceResp();
         faceResp.setIssueDate(MapUtils.getByExpr(data, "words_result.发证日期.words"));
@@ -164,6 +236,12 @@ public class RecognizeDrivingLicenseController extends BaseController {
         return faceResp;
     }
 
+    /**
+     * 将百度云OCR识别结果转换为行驶证反面响应对象
+     *
+     * @param data 百度云OCR识别的原始数据
+     * @return 行驶证反面响应对象，包含号牌号码、核定载人数、总质量等信息
+     */
     private RecognizeDrivingLicenseBackResp toBackResp(Map<String, Object> data) {
         RecognizeDrivingLicenseBackResp backResp = new RecognizeDrivingLicenseBackResp();
         backResp.setOverallDimension(MapUtils.getByExpr(data, "words_result.外廓尺寸.words"));