feat: 港澳台居民居住证 protocol

Author: Sean-LL

api/sdk/src/main/java/com/ke/bella/openapi/protocol/ocr/OcrFieldNamingStandard.java

@@ -0,0 +1,75 @@
+package com.ke.bella.openapi.protocol.ocr;
+
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * OCR证件字段命名规范
+ * 定义所有允许使用的OCR字段名称（超集）
+ */
+public class OcrFieldNamingStandard {
+
+    /**
+     * 所有允许使用的字段名称（超集）
+     * 所有OCR响应类的字段名必须在此集合中
+     */
+    private static final Set<String> ALLOWED_FIELD_NAMES = new HashSet<>();
+
+    static {
+        // 个人信息字段
+        ALLOWED_FIELD_NAMES.add("name");                // 姓名
+        ALLOWED_FIELD_NAMES.add("sex");                 // 性别
+        ALLOWED_FIELD_NAMES.add("nationality");         // 民族
+        ALLOWED_FIELD_NAMES.add("birth_date");          // 出生日期
+
+        // 地址信息字段
+        ALLOWED_FIELD_NAMES.add("address");             // 地址/住址
+
+        // 证件信息字段
+        ALLOWED_FIELD_NAMES.add("idcard_number");       // 证件号/身份证号/公民身份号码
+
+        // 签发信息字段
+        ALLOWED_FIELD_NAMES.add("issue_authority");     // 签发机关
+        ALLOWED_FIELD_NAMES.add("valid_date_start");    // 有效期开始
+        ALLOWED_FIELD_NAMES.add("valid_date_end");      // 有效期结束
+
+        // 银行卡字段
+        ALLOWED_FIELD_NAMES.add("card_number");         // 银行卡号
+        ALLOWED_FIELD_NAMES.add("bank_name");           // 银行名称
+        ALLOWED_FIELD_NAMES.add("card_type");           // 卡类型
+        ALLOWED_FIELD_NAMES.add("valid_date");          // 有效期
+
+        // 特殊字段
+        ALLOWED_FIELD_NAMES.add("eep_number");          // 通行证号
+
+    }
+
+    /**
+     * 检查字段名是否允许使用
+     *
+     * @param fieldName 字段名
+     *
+     * @return true 如果字段名在允许列表中
+     */
+    public static boolean isAllowedFieldName(String fieldName) {
+        return ALLOWED_FIELD_NAMES.contains(fieldName);
+    }
+
+    /**
+     * 获取所有允许的字段名
+     *
+     * @return 所有允许使用的字段名集合
+     */
+    public static Set<String> getAllAllowedFieldNames() {
+        return new HashSet<>(ALLOWED_FIELD_NAMES);
+    }
+
+    /**
+     * 添加新的允许字段名（用于扩展）
+     *
+     * @param fieldName 字段名
+     */
+    public static void addAllowedFieldName(String fieldName) {
+        ALLOWED_FIELD_NAMES.add(fieldName);
+    }
+}

api/sdk/src/main/java/com/ke/bella/openapi/protocol/ocr/residencepermit/OcrResidencePermitResponse.java

@@ -0,0 +1,76 @@
+package com.ke.bella.openapi.protocol.ocr.residencepermit;
+
+import java.io.Serializable;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonValue;
+import com.ke.bella.openapi.protocol.OpenapiResponse;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.experimental.SuperBuilder;
+
+/**
+ * OCR港澳台居民居住证识别响应
+ */
+@JsonInclude(JsonInclude.Include.NON_NULL)
+@EqualsAndHashCode(callSuper = true)
+@Data
+@NoArgsConstructor
+@SuperBuilder
+public class OcrResidencePermitResponse extends OpenapiResponse {
+    private static final long serialVersionUID = 1L;
+
+    private String request_id;              // 请求唯一标识
+    private ResidencePermitSide side;       // 居住证面类型
+    private Object data;                    // 识别结果数据
+
+    /**
+     * 居住证面类型枚举
+     */
+    @Getter
+    @AllArgsConstructor
+    public enum ResidencePermitSide {
+        PORTRAIT("portrait", "人像面"),
+        NATIONAL_EMBLEM("national_emblem", "国徽面");
+
+        @JsonValue
+        private final String code;
+        private final String description;
+    }
+
+    // 人像面数据结构
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @JsonInclude(JsonInclude.Include.NON_NULL)
+    public static class PortraitData implements Serializable {
+        private static final long serialVersionUID = 1L;
+
+        private String name;                // 姓名
+        private String sex;                 // 性别
+        private String birth_date;          // 出生日期
+        private String address;             // 住址
+        private String idcard_number;       // 公民身份号码
+    }
+
+    // 国徽面数据结构
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @JsonInclude(JsonInclude.Include.NON_NULL)
+    public static class NationalEmblemData implements Serializable {
+        private static final long serialVersionUID = 1L;
+
+        private String issue_authority;     // 签发机关
+        private String valid_date_start;    // 有效期开始日期
+        private String valid_date_end;      // 有效期结束日期
+        private String eep_number;          // 通行证号
+    }
+}

api/server/pom.xml

@@ -301,6 +301,12 @@
             <artifactId>oapi-sdk</artifactId>
             <version>2.4.19</version>
         </dependency>
+        <dependency>
+            <groupId>org.reflections</groupId>
+            <artifactId>reflections</artifactId>
+            <version>0.10.2</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

api/server/src/main/java/com/ke/bella/openapi/protocol/ocr/OcrResidencePermitAdaptor.java

@@ -0,0 +1,14 @@
+package com.ke.bella.openapi.protocol.ocr;
+
+import com.ke.bella.openapi.protocol.IProtocolAdaptor;
+import com.ke.bella.openapi.protocol.ocr.residencepermit.OcrResidencePermitResponse;
+
+public interface OcrResidencePermitAdaptor<T extends OcrProperty> extends IProtocolAdaptor {
+
+    OcrResidencePermitResponse residencePermit(OcrRequest request, String url, T property);
+
+    @Override
+    default String endpoint() {
+        return "/v1/ocr/residence_permit";
+    }
+}

api/server/src/test/java/com/ke/bella/openapi/protocol/ocr/OcrFieldNamingStandardTest.java

@@ -0,0 +1,118 @@
+package com.ke.bella.openapi.protocol.ocr;
+
+import static org.junit.Assert.assertTrue;
+
+import java.io.Serializable;
+import java.lang.reflect.Field;
+import java.lang.reflect.Modifier;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+
+import org.junit.Test;
+import org.reflections.Reflections;
+
+import com.ke.bella.openapi.protocol.OpenapiResponse;
+
+/**
+ * OCR证件字段命名规范测试
+ * 验证所有字段名是否在允许的超集中
+ */
+public class OcrFieldNamingStandardTest {
+
+    /**
+     * 自动扫描所有OCR数据类
+     */
+    private List<Class<?>> findAllOcrDataClasses() {
+        List<Class<?>> classes = new ArrayList<>();
+
+        Reflections reflections = new Reflections("com.ke.bella.openapi.protocol.ocr");
+        Set<Class<? extends OpenapiResponse>> responseClasses = reflections.getSubTypesOf(OpenapiResponse.class);
+
+        for (Class<?> responseClass : responseClasses) {
+            for (Class<?> innerClass : responseClass.getDeclaredClasses()) {
+                if(innerClass.getSimpleName().endsWith("Data") &&
+                        Modifier.isStatic(innerClass.getModifiers()) &&
+                        Modifier.isPublic(innerClass.getModifiers()) &&
+                        Serializable.class.isAssignableFrom(innerClass)) {
+                    classes.add(innerClass);
+                }
+            }
+        }
+
+        return classes;
+    }
+
+    /**
+     * 主测试: 验证所有OCR字段命名规范
+     */
+    @Test
+    public void testAllOcrResponseFieldNamingStandard() {
+        System.out.println("=== OCR字段命名规范验证 ===\n");
+
+        // 1. 打印允许的字段名超集
+        Set<String> allowedFields = OcrFieldNamingStandard.getAllAllowedFieldNames();
+        System.out.println("允许的字段名超集(" + allowedFields.size() + "个):");
+        for (String field : allowedFields) {
+            System.out.println("  - " + field);
+        }
+        System.out.println();
+
+        // 2. 打印扫描到的类
+        List<Class<?>> ocrDataClasses = findAllOcrDataClasses();
+        System.out.println("扫描到的OCR数据类(" + ocrDataClasses.size() + "个):");
+        for (Class<?> clazz : ocrDataClasses) {
+            System.out.println("  - " + clazz.getName());
+        }
+        System.out.println();
+
+        // 3. 验证每个类的字段是否符合要求
+        List<String> violations = new ArrayList<>();
+
+        for (Class<?> clazz : ocrDataClasses) {
+            System.out.println("检查: " + clazz.getSimpleName());
+            Field[] fields = clazz.getDeclaredFields();
+
+            for (Field field : fields) {
+                String fieldName = field.getName();
+
+                // 跳过特殊字段
+                if(fieldName.equals("serialVersionUID") ||
+                        fieldName.startsWith("$") ||
+                        fieldName.equals("INSTANCE")) {
+                    continue;
+                }
+
+                // 检查字段是否在超集中
+                if(!OcrFieldNamingStandard.isAllowedFieldName(fieldName)) {
+                    String violation = clazz.getSimpleName() + "." + fieldName;
+                    violations.add(violation);
+                    System.out.println("  ❌ " + fieldName + " - 不在超集中");
+                } else {
+                    System.out.println("  ✅ " + fieldName);
+                }
+            }
+            System.out.println();
+        }
+
+        // 结果汇总
+        System.out.println("=== 验证结果 ===");
+        System.out.println("总类数: " + ocrDataClasses.size());
+        System.out.println("不符合规范的字段数: " + violations.size());
+
+        if(!violations.isEmpty()) {
+            System.out.println("\n不符合规范的字段:");
+            for (String violation : violations) {
+                System.out.println("  ❌ " + violation);
+            }
+            System.out.println("\n提示: 请在 OcrFieldNamingStandard 中添加缺失的字段名");
+        }
+
+        // 断言
+        assertTrue(
+                "发现 " + violations.size() + " 个字段不在允许的超集中",
+                violations.isEmpty());
+
+        System.out.println("\n✅ 所有字段命名规范验证通过!");
+    }
+}