diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/bankcard/BankCard4MetaController.java b/api-web/api-interface/src/main/java/com/heyu/api/controller/bankcard/BankCard4MetaController.java
index 009d9cd..9f392c6 100644
--- a/api-web/api-interface/src/main/java/com/heyu/api/controller/bankcard/BankCard4MetaController.java
+++ b/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
+ */
+/**
+ * 银行卡四要素核验控制器
+ *
+ * 继承BaseController，提供银行卡四要素核验的HTTP接口
+ * 主要用于验证用户输入的银行卡号、姓名、身份证号和手机号是否完全匹配
+ *
*/
@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
+ /**
+ * 银行卡四要素核验接口
+ *
+ * 测试地址：
+ * - 本地：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
+ *
+ *
+ * @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 {
}
+ /**
+ * 执行银行卡四要素核验业务逻辑
+ *
+ * 核验结果码说明：
+ * - 0：银行卡号+姓名+身份证号+手机号信息一致（核验通过）
+ * - 1：银行卡号+姓名+身份证号+手机号信息不一致（核验失败）
+ * - 2：查无此卡（卡状态异常或已注销）
+ *
+ *
+ * 四要素核验相比二、三要素核验提供更高级别的安全保障，
+ * 适用于金融支付、大额转账、实名认证等对安全性要求较高的场景
+ *
+ *
+ * @param bankCard4MetaRequest 银行卡四要素核验请求对象
+ * @return R 返回核验结果，包含核验状态码和描述信息
+ */
public R doVerifyBankCard4(ABank4MetaVerifyRequest bankCard4MetaRequest) {
BankCard2MetaResp bankCard2MetaResp = new BankCard2MetaResp();
- // //1 一致 0 不一致，2查无(卡状态异常或已注销)
+
+ // 调用阿里云API进行银行卡四要素核验
ApiR 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());