提交修改

api-web/api-interface/src/main/java/com/heyu/api/controller/bankcard/BankCard4MetaController.java

@@ -16,27 +16,68 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
 /***
- * 识别身份证
+ * 银行卡四要素核验控制器
  *
- * https://market.aliyun.com/apimarket/detail/cmapi00066584#sku=yuncode60584000011
+ * 功能说明：
+ * 提供银行卡号+姓名+身份证号+手机号四要素核验接口，验证用户输入的完整银行卡信息是否真实匹配
  *
+ * 接口文档：
+ * - 阿里云市场：https://market.aliyun.com/apimarket/detail/cmapi00066584#sku=yuncode60584000011
  *
+ * 核验要素：
+ * - 二要素：银行卡号 + 姓名
+ * - 三要素：银行卡号 + 姓名 + 身份证号
+ * - 四要素：银行卡号 + 姓名 + 身份证号 + 手机号
  *
+ * 安全性：
+ * 四要素核验相比二、三要素提供更高级别的身份验证，适用于金融支付、实名认证等高安全场景
+ *
+ * @author 系统生成
+ * @version 1.0
+ */
+/**
+ * 银行卡四要素核验控制器
+ * <p>
+ * 继承BaseController，提供银行卡四要素核验的HTTP接口
+ * 主要用于验证用户输入的银行卡号、姓名、身份证号和手机号是否完全匹配
+ * </p>
  */
 @Slf4j
 @RestController
 @RequestMapping("/bank/card/4")
 public class BankCard4MetaController extends BaseController {
 
+    /**
+     * 阿里云银行卡四要素核验处理器
+     */
     @Autowired
     private ABank4MetaVerifyHandle bank4MetaVerifyHandle;
 
-
+    /**
+     * 四要素核验成功提示信息
+     */
     public static final String SUCCESS_MSG = "银⾏卡号+姓名+身份证号+手机号信息匹配";
+
+    /**
+     * 四要素核验失败提示信息
+     */
     public static final String FAILED_MSG = "银⾏卡号+姓名+身份证号码+手机号信息不匹配";
 
-    // http://localhost:8888/bank/card/4/verify?bankCard=6214855713516769&realName=瞿贻晓&idCardNumber=430529199209255030&mobile=18458195149
+    /**
-    // https://api.1024api.com/api-interface/bank/card/4/verify?bankCard=6214855713516761&realName=瞿贻晓&idCardNumber=430529199209255030&mobile=18458195149
+     * 银行卡四要素核验接口
+     * <p>
+     * 测试地址：
+     * - 本地：http://localhost:8888/bank/card/4/verify?bankCard=6214855713516769&realName=瞿贻晓&idCardNumber=430529199209255030&mobile=18458195149
+     * - 生产：https://api.1024api.com/api-interface/bank/card/4/verify?bankCard=6214855713516761&realName=瞿贻晓&idCardNumber=430529199209255030&mobile=18458195149
+     * </p>
+     *
+     * @param bankCard4MetaRequest 银行卡四要素核验请求对象，包含：
+     *                             - bankCard: 银行卡号
+     *                             - realName: 真实姓名
+     *                             - idCardNumber: 身份证号
+     *                             - mobile: 手机号
+     * @return R 返回核验结果，包含核验状态和描述信息
+     */
     @RequestMapping("/verify")
     @EbAuthentication(tencent = ApiConstants.TENCENT_AUTH)
     public R verify(ABank4MetaVerifyRequest bankCard4MetaRequest) {
@@ -44,28 +85,55 @@ public class BankCard4MetaController extends BaseController {
     }
 
 
+    /**
+     * 执行银行卡四要素核验业务逻辑
+     * <p>
+     * 核验结果码说明：
+     * - 0：银行卡号+姓名+身份证号+手机号信息一致（核验通过）
+     * - 1：银行卡号+姓名+身份证号+手机号信息不一致（核验失败）
+     * - 2：查无此卡（卡状态异常或已注销）
+     * </p>
+     * <p>
+     * 四要素核验相比二、三要素核验提供更高级别的安全保障，
+     * 适用于金融支付、大额转账、实名认证等对安全性要求较高的场景
+     * </p>
+     *
+     * @param bankCard4MetaRequest 银行卡四要素核验请求对象
+     * @return R 返回核验结果，包含核验状态码和描述信息
+     */
     public R doVerifyBankCard4(ABank4MetaVerifyRequest bankCard4MetaRequest) {
         BankCard2MetaResp bankCard2MetaResp = new BankCard2MetaResp();
-        // //1 一致 0 不一致，2查无(卡状态异常或已注销)
+
+        // 调用阿里云API进行银行卡四要素核验
         ApiR<TBankMetaVerifyResponse> aR = bank4MetaVerifyHandle.handle(bankCard4MetaRequest);
+
+        // API调用成功
         if (aR.isSuccess()) {
             TBankMetaVerifyResponse bankMetaVerifyResponse = aR.getData();
             if (bankMetaVerifyResponse != null) {
+                // 业务错误处理（如参数错误、服务异常等）
                 if (bankMetaVerifyResponse.getCode() == 400) {
                     bankCard2MetaResp.setCheckResult(ApiConstants.FAILED);
                     bankCard2MetaResp.setDesc(bankMetaVerifyResponse.getMsg());
                     return R.ok().setData(bankCard2MetaResp);
                 }
 
+                // 业务成功处理，解析核验结果
                 if (bankMetaVerifyResponse.getCode() == 200 && bankMetaVerifyResponse.getData() != null) {
                     int result = bankMetaVerifyResponse.getData().getResult();
+
+                    // 核验通过：四要素信息完全一致
                     if (result == 0) {
                         bankCard2MetaResp.setCheckResult(ApiConstants.SUCCESS);
                         bankCard2MetaResp.setDesc(SUCCESS_MSG);
-                    } else if (result == 1) {
+                    }
+                    // 核验失败：四要素信息不一致
+                    else if (result == 1) {
                         bankCard2MetaResp.setCheckResult(ApiConstants.FAILED);
                         bankCard2MetaResp.setDesc(FAILED_MSG);
-                    } else {
+                    }
+                    // 其他情况：查无此卡或其他异常状态
+                    else {
                         bankCard2MetaResp.setCheckResult(result + "");
                         bankCard2MetaResp.setDesc(bankMetaVerifyResponse.getData().getMsg());
                     }
@@ -74,6 +142,7 @@ public class BankCard4MetaController extends BaseController {
             }
         }
 
+        // API调用失败，返回错误信息
         bankCard2MetaResp.setCheckResult(ApiConstants.FAILED);
         bankCard2MetaResp.setDesc(aR.getErrorMsg());