Эх сурвалжийг харах

test(guhe.l1.shellGuard): S-cfc-89 add RED contract tests for empty-shell rate guard (T13/L1-4)

契约锚点:2026-11-08-浠艾福平台程序修改计划.md §三-T13 空壳率防错(L1-4)
- guhe_v2 解析后校验增量 11 键齐全(21 旧键 + 11 增量键 = 32 键)
- 空壳(曾误用艾德范思提取器产 26 键)→ 换正确提取器 extract_guhe_v2

RED 预期:实现未落地,5 用例红(守卫入口/11 键基准/32 键边界/26 键空壳签名/提取器寻址),
2 用例说明性绿(parseReport 挂载点 + 权限流不适用)。纯反射结构契约,无 Spring/DB/外部服务。

GREEN 指引:ReportParserDispatchService 提供空壳守卫入口(方法名含 Shell/KeyComplete/ValidateKeys),
L1 层声明 11/32 键边界与 26 键空壳签名、增量 11 键集合,并寻址 extract_guhe_v2。
Sisyphus Agent 1 долоо хоног өмнө
parent
commit
15c7ce949

+ 305 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/GuheShellGuardContractTest.java

@@ -0,0 +1,305 @@
+package com.etotem.cfc.unit;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
+import java.util.Collection;
+import java.util.List;
+import java.util.Set;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * 契约级单测:guhe_v2 报告「空壳率防错」(能力键 {@code guhe.l1.shellGuard})。
+ *
+ * <p><b>契约来源</b>(计划 2026-11-08-浠艾福平台程序修改计划.md §三-T13 / §一-L1 接入归一化 ④ / §2.1):
+ * <blockquote>
+ *   T13 空壳率防错(L1-4):guhe_v2 解析后<b>校验增量 11 键齐全</b>;
+ *   空壳(曾误用艾德范思提取器产 <b>26 键</b>)→ <b>换正确提取器</b>。
+ * </blockquote>
+ * 输入基线 §2.1:guhe_v2 新版标准报告 = 旧 21 键打底 + 11 增量键 = <b>32 键</b>;
+ * 增量键不齐 → 判为空壳(解析产物仅 26 键,即误用艾德范思提取器)→ 触发换用正确提取器。</p>
+ *
+ * <p><b>平台现状(src/main 探测,C 档 #1 Adapter 形态 / #4 合规门禁挂载点)</b>:L1 接入归一化层为
+ * <ul>
+ *   <li>{@code PdfParseService}(文本解析,{@code reportFormat} 仅取值 {@code "beijing"} / {@code "guhe"},无版本维度)</li>
+ *   <li>{@code ReportParserDispatchService#parseReport}(指纹检测 → 专用解析器 / 2b. LLM 兜底)</li>
+ *   <li>{@code ReportFingerprintService#detect}(DB 指纹规则 → Python 引擎 → {@code typeId})</li>
+ * </ul>
+ * 全库无 {@code guhe_v2}、无增量 11 键完整性校验、无空壳(26 键)签名检测、无 {@code extract_guhe_v2} 寻址——
+ * 本能力<b>实现未落地</b>。因此本测试以「反射结构契约」探测契约所需标记缺失:
+ * 能编译通过、能运行、断言失败(红),失败断言原文清晰可贴。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者在 L1 接入归一化层落地三件事后,本测试自动转绿——
+ * <ol>
+ *   <li>{@code ReportParserDispatchService} 提供空壳守卫入口(方法名含 {@code Shell}/{@code KeyComplete}/
+ *       {@code ValidateKeys},如 {@code guardShell}),guhe_v2 解析后校验增量 11 键齐全;</li>
+ *   <li>L1 层声明键数边界与空壳签名(静态 int 常量 {@code 11}(增量键数)与 {@code 32}(guhe_v2 总键数)并存,
+ *       以及空壳签名 {@code 26}(误用艾德范思提取器产物),使空壳可被识别);</li>
+ *   <li>L1 层声明增量 11 键集合(静态集合常量 size=11)并寻址正确提取器(静态 String 常量含
+ *       {@code extract_guhe_v2}),空壳检测到 26 键时切换用正确提取器。</li>
+ * </ol>
+ * 届时可将结构探测升级为行为级验证(mock 分派服务断言 26 键→触发换提取器、32 键→通过)。</p>
+ *
+ * <p><b>权限流说明</b>:本能力为 L1 接入归一化层的内部解析/路由管道(报告上传 → 解析 → 空壳检测 → 提取器切换),
+ * 无用户权限维度,「权限(适用时)」三流中的权限流不适用,以说明性用例标注。</p>
+ */
+class GuheShellGuardContractTest {
+
+    // ------------------------------------------------------------------
+    // 契约锚点(计划 §三-T13 / L1-4 / §2.1)
+    // ------------------------------------------------------------------
+
+    /** 增量键数(§2.1:guhe_v2 = 旧 21 键打底 + 11 增量键) */
+    private static final int INCREMENTAL_KEYS_11 = 11;
+
+    /** guhe_v2 总键数(§2.1:21 + 11 = 32) */
+    private static final int GUHE_V2_KEYS_32 = 32;
+
+    /** 空壳签名(曾误用艾德范思提取器产物,仅 26 键)——判为空壳 → 换正确提取器(T13) */
+    private static final int EMPTY_SHELL_KEYS_26 = 26;
+
+    /** 正确提取器脚本名(空壳时切换目标,T13「换正确提取器」) */
+    private static final String GUHE_V2_PARSER_SCRIPT = "extract_guhe_v2";
+
+    // L1 接入归一化层现有类(src/main 现状探测;实现者在其上落地空壳守卫)
+    private static final String PARSED_REPORT_RESULT = "com.etotem.cfc.dto.ParsedReportResult";
+    private static final String DISPATCH_SERVICE = "com.etotem.cfc.service.ReportParserDispatchService";
+    private static final String FINGERPRINT_SERVICE = "com.etotem.cfc.service.ReportFingerprintService";
+    private static final String PDF_PARSE_SERVICE = "com.etotem.cfc.service.PdfParseService";
+
+    /** 空壳守卫入口方法名探针(大小写不敏感) */
+    private static final String[] GUARD_ENTRY_FRAGMENTS = {
+            "shell", "keycomplete", "validatekeys", "assertkeys", "emptyshell"
+    };
+
+    // ------------------------------------------------------------------
+    // 正常流:空壳守卫入口(guhe_v2 解析后校验增量 11 键齐全)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-1:ReportParserDispatchService 应提供空壳守卫入口")
+    void dispatchService_providesShellGuardEntry() {
+        Class<?> clazz = loadClass(DISPATCH_SERVICE);
+        if (clazz == null) {
+            fail("[guhe.l1.shellGuard] ReportParserDispatchService 类不存在(L1 分派入口),"
+                    + "无法验证空壳守卫入口(T13/L1-4)。");
+        }
+        boolean hasEntry = hasMethodNamedLike(clazz, GUARD_ENTRY_FRAGMENTS);
+        assertTrue(hasEntry,
+                "[guhe.l1.shellGuard] ReportParserDispatchService 应提供空壳守卫入口"
+                        + "(方法名含 Shell / KeyComplete / ValidateKeys / AssertKeys,如 guardShell),"
+                        + "在 guhe_v2 解析后校验增量 11 键齐全(T13/L1-4)。"
+                        + "当前 parseReport 仅做 指纹→专用解析器/LLM 兜底,无空壳检测步骤。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:L1 层应声明增量 11 键集合(校验齐全的基准)")
+    void l1Layer_declaresIncrementalKeys11() {
+        boolean has11Keys = hasKeyCollectionOfSize(loadClass(PARSED_REPORT_RESULT), INCREMENTAL_KEYS_11)
+                || hasKeyCollectionOfSize(loadClass(DISPATCH_SERVICE), INCREMENTAL_KEYS_11)
+                || hasKeyCollectionOfSize(loadClass(FINGERPRINT_SERVICE), INCREMENTAL_KEYS_11)
+                || hasKeyCollectionOfSize(loadClass(PDF_PARSE_SERVICE), INCREMENTAL_KEYS_11);
+        boolean has11Const = hasIntConstant(loadClass(PARSED_REPORT_RESULT), INCREMENTAL_KEYS_11)
+                || hasIntConstant(loadClass(DISPATCH_SERVICE), INCREMENTAL_KEYS_11)
+                || hasIntConstant(loadClass(FINGERPRINT_SERVICE), INCREMENTAL_KEYS_11)
+                || hasIntConstant(loadClass(PDF_PARSE_SERVICE), INCREMENTAL_KEYS_11);
+        assertTrue(has11Keys || has11Const,
+                "[guhe.l1.shellGuard] L1 层应声明增量 11 键基准(静态 String 键集合常量 size=11 且字段名含 "
+                        + "KEY/KEYS/INCREMENTAL/增量,或静态 int 常量 11),"
+                        + "作为 guhe_v2 解析后校验『增量 11 键齐全』的基准(§2.1 旧 21 键 + 11 增量键 = 32 键)。"
+                        + "当前无增量键基准,无法判定空壳(T13/L1-4)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流:guhe_v2 总键数 32 边界(21 + 11)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-1:L1 层应声明 guhe_v2 总键数 32(21 旧键 + 11 增量键)")
+    void l1Layer_declaresGuheV2KeyBoundary32() {
+        boolean has32 = hasIntConstant(loadClass(PARSED_REPORT_RESULT), GUHE_V2_KEYS_32)
+                || hasIntConstant(loadClass(DISPATCH_SERVICE), GUHE_V2_KEYS_32)
+                || hasIntConstant(loadClass(FINGERPRINT_SERVICE), GUHE_V2_KEYS_32)
+                || hasIntConstant(loadClass(PDF_PARSE_SERVICE), GUHE_V2_KEYS_32);
+        assertTrue(has32,
+                "[guhe.l1.shellGuard] L1 层应声明 guhe_v2 总键数 32(静态 int 常量 32,§2.1 旧 21 键 + 11 增量键),"
+                        + "以区分完整 guhe_v2 报告(32 键)与空壳(不足 32 键)。当前无 32 键边界(T13/L1-4)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流:空壳签名 26 键(误用艾德范思提取器产物)→ 换正确提取器
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-2:L1 层应识别空壳签名 26 键(误用艾德范思提取器产物)")
+    void l1Layer_recognizesEmptyShell26() {
+        boolean has26 = hasIntConstant(loadClass(PARSED_REPORT_RESULT), EMPTY_SHELL_KEYS_26)
+                || hasIntConstant(loadClass(DISPATCH_SERVICE), EMPTY_SHELL_KEYS_26)
+                || hasIntConstant(loadClass(FINGERPRINT_SERVICE), EMPTY_SHELL_KEYS_26)
+                || hasIntConstant(loadClass(PDF_PARSE_SERVICE), EMPTY_SHELL_KEYS_26);
+        assertTrue(has26,
+                "[guhe.l1.shellGuard] L1 层应识别空壳签名 26 键(静态 int 常量 26,"
+                        + "曾误用艾德范思提取器仅产 26 键),判为空壳后换正确提取器(T13)。"
+                        + "当前无空壳签名检测,26 键空壳将不被识别。");
+    }
+
+    @Test
+    @DisplayName("边界流-3:L1 层应寻址正确提取器 extract_guhe_v2(空壳时切换目标)")
+    void l1Layer_addressesCorrectExtractor() {
+        boolean addressed = hasStringConstantContaining(loadClass(DISPATCH_SERVICE), GUHE_V2_PARSER_SCRIPT)
+                || hasStringConstantContaining(loadClass(FINGERPRINT_SERVICE), GUHE_V2_PARSER_SCRIPT)
+                || hasStringConstantContaining(loadClass(PDF_PARSE_SERVICE), GUHE_V2_PARSER_SCRIPT);
+        assertTrue(addressed,
+                "[guhe.l1.shellGuard] L1 层(ReportParserDispatchService / ReportFingerprintService / PdfParseService)"
+                        + "应寻址正确提取器(静态 String 常量值含 \"extract_guhe_v2\"),"
+                        + "在空壳(26 键)检测到时切换用正确提取器(T13『空壳→换正确提取器』)。"
+                        + "当前无 extract_guhe_v2 寻址,空壳无法触发换提取器。");
+    }
+
+    // ------------------------------------------------------------------
+    // 结构契约:空壳守卫挂载点(parseReport 管线已存在 → 说明性绿,GREEN 挂载点)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("结构契约-1:parseReport 管线入口应存在(空壳守卫挂载点)")
+    void dispatchService_hasParseReportPipeline() {
+        Class<?> clazz = loadClass(DISPATCH_SERVICE);
+        if (clazz == null) {
+            fail("[guhe.l1.shellGuard] ReportParserDispatchService 类不存在(L1 分派入口),"
+                    + "无法验证 parseReport 管线(GREEN 挂载点)。");
+        }
+        boolean found = false;
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().equals("parseReport")) {
+                found = true;
+                break;
+            }
+        }
+        assertTrue(found,
+                "[guhe.l1.shellGuard] ReportParserDispatchService 应提供 parseReport 管线入口"
+                        + "(T13 空壳守卫挂载点;GREEN 时在解析后调用空壳守卫即可)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 权限流(不适用):L1 内部解析/路由管道,无用户权限维度
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("权限流:本能力为 L1 接入归一化内部解析/路由管道,无用户权限维度,权限流不适用")
+    void permissionFlow_notApplicable() {
+        // 说明性用例:契约 AC 为「报告上传 → 解析 → 空壳检测 → 提取器切换」内部管道,无权限校验维度。
+        // 不产生断言失败;仅为三流覆盖标注「不适用」。
+        assertTrue(true, "权限流不适用:guhe.l1.shellGuard 为 L1 内部解析/路由管道,无用户权限维度。");
+    }
+
+    // ------------------------------------------------------------------
+    // 反射辅助
+    // ------------------------------------------------------------------
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    /** 是否存在静态 int 常量值等于 target(键数/空壳签名探针) */
+    private boolean hasIntConstant(Class<?> clazz, int target) {
+        if (clazz == null) return false;
+        for (Field f : clazz.getDeclaredFields()) {
+            if (f.getType() != int.class && f.getType() != Integer.class) continue;
+            if (!Modifier.isStatic(f.getModifiers()) || !Modifier.isFinal(f.getModifiers())) continue;
+            try {
+                f.setAccessible(true);
+                Object v = f.get(null);
+                if (v instanceof Integer && ((Integer) v) == target) return true;
+            } catch (Exception ignored) {
+                // 常量读取失败 → 跳过
+            }
+        }
+        return false;
+    }
+
+    /** 是否存在静态 String 常量值包含 target(正确提取器寻址探针) */
+    private boolean hasStringConstantContaining(Class<?> clazz, String target) {
+        if (clazz == null) return false;
+        for (Field f : clazz.getDeclaredFields()) {
+            if (f.getType() != String.class) continue;
+            if (!Modifier.isStatic(f.getModifiers()) || !Modifier.isFinal(f.getModifiers())) continue;
+            try {
+                f.setAccessible(true);
+                Object v = f.get(null);
+                if (v instanceof String && ((String) v).contains(target)) return true;
+            } catch (Exception ignored) {
+                // 常量读取失败 → 跳过
+            }
+        }
+        return false;
+    }
+
+    /**
+     * 是否存在静态「键集合」常量(List/Set/String[] 等,元素为 String)长度为 size 且
+     * 字段名(忽略大小写)含 KEY/KEYS/INCREMENTAL/增量 —— 增量键集合探针。
+     * 收紧理由:PdfParseService 存在多个无关的 KNOWN_* 静态列表(恰有 size=11),
+     * 仅按长度判定会误绿;键集合字段名需带键语义以锚定「增量 11 键」契约(T13)。
+     */
+    private boolean hasKeyCollectionOfSize(Class<?> clazz, int size) {
+        if (clazz == null) return false;
+        for (Field f : clazz.getDeclaredFields()) {
+            if (!Modifier.isStatic(f.getModifiers()) || !Modifier.isFinal(f.getModifiers())) continue;
+            Class<?> type = f.getType();
+            boolean isCollection = Collection.class.isAssignableFrom(type)
+                    || Set.class.isAssignableFrom(type)
+                    || List.class.isAssignableFrom(type)
+                    || type.isArray();
+            if (!isCollection) continue;
+            String name = f.getName().toLowerCase();
+            if (!name.contains("key") && !name.contains("incremental") && !name.contains("增量")) {
+                continue;
+            }
+            try {
+                f.setAccessible(true);
+                Object v = f.get(null);
+                if (v == null) continue;
+                int len = v instanceof Collection
+                        ? ((Collection<?>) v).size()
+                        : (v.getClass().isArray() ? java.lang.reflect.Array.getLength(v) : -1);
+                if (len != size) continue;
+                // 元素应为 String(键名集合语义)
+                if (v instanceof Collection) {
+                    boolean allString = true;
+                    for (Object o : (Collection<?>) v) {
+                        if (o != null && !(o instanceof String)) {
+                            allString = false;
+                            break;
+                        }
+                    }
+                    if (allString) return true;
+                } else if (v.getClass().getComponentType() == String.class) {
+                    return true;
+                }
+            } catch (Exception ignored) {
+                // 常量读取失败 → 跳过
+            }
+        }
+        return false;
+    }
+
+    /** 是否存在方法名(忽略大小写)包含任一片段 */
+    private boolean hasMethodNamedLike(Class<?> clazz, String[] fragments) {
+        if (clazz == null) return false;
+        for (Method m : clazz.getDeclaredMethods()) {
+            String name = m.getName().toLowerCase();
+            for (String frag : fragments) {
+                if (name.contains(frag)) return true;
+            }
+        }
+        return false;
+    }
+}