Bladeren bron

test(health.report.guheV2AsyncRoute): S-cfc-414 契约级RED单测 谷禾guhe_v2异步路由

能力键 health.report.guheV2AsyncRoute(方案 v1.0 §三 P0-2 + §六 6.1)。
纯反射结构契约,无 Spring/DB/外部服务。预期红:8 失败 / 3 通过 / 0 错误。
契约锚点:reportFormat / parseMethod=langgraph / reportFormatHint / guhe_v2 路由标记 /
「暂不支持在线解析」回退红线 / parseSelfCheck。GREEN 指引见类注释。
Administrator 9 uur geleden
bovenliggende
commit
7717e4fec4
1 gewijzigde bestanden met toevoegingen van 368 en 0 verwijderingen
  1. 368 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/GuheV2AsyncRouteContractTest.java

+ 368 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/GuheV2AsyncRouteContractTest.java

@@ -0,0 +1,368 @@
+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 static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * 契约级单测:谷禾新版 guhe_v2 异步路由(能力键 {@code health.report.guheV2AsyncRoute})。
+ *
+ * <p><b>契约来源</b>(谷禾新版解析与五维归因升级方案 v1.0,提交 {@code ef8eb62be} 已合入 origin/cfclub;
+ * 溯源 SC-P-20 健康报告 PDF 上传解析 / SC-P-21 报告类型识别,{@code tests/user-scenarios/应用场景总览.md}):
+ * <blockquote>
+ *   §三 P0-2 解析主路径切到 Python(Java 转发):
+ *   <ol>
+ *     <li>{@code HealthReportController.uploadReport()}:识别到 {@code guhe_v2} 时,
+ *         <b>自动切换为 upload-only + submitAsyncCollect()</b>(复用现有异步链路),
+ *         响应返回 {@code draftId} + {@code parseMethod="langgraph"},前端跳「解析中」等待页;</li>
+ *     <li>{@code LangGraphReportParseService.postParseWithReason()}:新增请求字段
+ *         {@code reportFormatHint="guhe_v2"},Python 侧按此路由到 guhe_v2 专用提取器;</li>
+ *     <li>异步采集失败的回退策略:<b>不</b>做 Java 本地兜底(Java 无 guhe_v2 能力),
+ *         而是标记 {@code parse_error} + 通知用户「该报告格式暂不支持在线解析,可稍后重试或联系服务号」。</li>
+ *   </ol>
+ *   §六 6.1 上传接口:
+ *   <ul>
+ *     <li>{@code POST /api/health/report/upload} 响应新增字段:{@code reportFormat}
+ *         (guhe / guhe_v2 / beijing / aidefansi)、{@code parseMethod}(local / langgraph)、
+ *         {@code draftId}(异步时返回);</li>
+ *     <li>{@code GET /api/health/report/collect/status?draftId=…} 响应新增:
+ *         {@code parseSelfCheck}(JSON,_解析自检)。</li>
+ *   </ul>
+ * </blockquote></p>
+ *
+ * <p><b>平台现状(origin/cfclub src/main 探测)</b>:
+ * {@code detectGuheV2Route()} 判定链(前身任务 guhe.l1.guheV2Route,S-cfc-90/S-cfc-120 已合入,
+ * {@code GuheV2RouteContractTest} 8/8 绿)后,P0-2 尚未落地:
+ * <ul>
+ *   <li>{@code HealthReportController.uploadReport()} 结果体无 {@code parseMethod}/{@code reportFormat}
+ *       键(§6.1),controller 全文件无 {@code guhe_v2} 字符串(grep 0 命中);</li>
+ *   <li>{@code reportFormatHint} 全仓 0 命中(P0-2 请求字段未实现);</li>
+ *   <li>{@code parseSelfCheck} 全仓 0 命中(§6.1 collect/status 新字段未实现);</li>
+ *   <li>「该报告格式暂不支持在线解析」失败提示全仓 0 命中(P0-2 回退红线未实现)。</li>
+ * </ul>
+ * 因此本测试以「反射结构契约」探测上述契约锚点缺失:能编译、能运行、断言失败(红)。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者按 P0-2 落地后,本测试自动转绿——
+ * <ol>
+ *   <li>在 {@code HealthReportController} 注册 guhe_v2 上传路由标记
+ *       (静态 String 常量值含 {@code "guhe_v2"},或方法名含 {@code guheV2} 的识别/路由方法)——
+ *       GREEN 时 {@code uploadReport()} 识别到 guhe_v2 自动切换 upload-only + submitAsyncCollect;</li>
+ *   <li>在 {@code HealthReportController} 注册 §6.1 上传响应键常量
+ *       (静态 String 常量值含 {@code "reportFormat"} / {@code "parseMethod"}),
+ *       guhe_v2 分支返回 {@code parseMethod="langgraph"}(常量值含 {@code "langgraph"});</li>
+ *   <li>在 {@code LangGraphReportParseService} 注册请求字段键 {@code reportFormatHint}
+ *       (静态 String 常量值含 {@code "reportFormatHint"})与 hint 值 {@code "guhe_v2"};</li>
+ *   <li>在异步采集链(He/ReportCollectService)注册失败提示常量
+ *       (值含「暂不支持在线解析」),guhe_v2 失败标记 {@code parse_error} 且<b>不</b>回退 Java 本地解析;</li>
+ *   <li>在 {@code collectStatus} 响应注册 {@code parseSelfCheck} 键(静态 String 常量值含之)。</li>
+ * </ol>
+ * 届时可将结构探测升级为行为级验证(§7.1 单测点:{@code test_upload_guheV2_routes_to_langgraph()} /
+ * {@code test_upload_guheV2_async_parse_self_check()},mock LangGraph 断言 guhe_v2 上传→langgraph 异步)。
+ * 结构探测的类名以当前 src/main 落点为准(实现仅在 feature 分支,不得假定包路径)。</p>
+ *
+ * <p><b>权限流说明</b>:本能力为上传→异步采集的内部路由管道,无新增用户权限维度;
+ * 草稿归属校验({@code draft.userId == 当前 userId})已在 {@code collectStatus} 既有实现中,
+ * 权限流不适用,以说明性用例标注。</p>
+ */
+class GuheV2AsyncRouteContractTest {
+
+    // ------------------------------------------------------------------
+    // 契约锚点(方案 v1.0 §三 P0-2 + §六 6.1)
+    // ------------------------------------------------------------------
+
+    /** §6.1 上传响应新增键:reportFormat(guhe/guhe_v2/beijing/aidefansi) */
+    private static final String RESPONSE_KEY_REPORT_FORMAT = "reportFormat";
+
+    /** §6.1 上传响应新增键:parseMethod(local/langgraph) */
+    private static final String RESPONSE_KEY_PARSE_METHOD = "parseMethod";
+
+    /** §6.1 / P0-2:guhe_v2 异步解析方式值 parseMethod="langgraph" */
+    private static final String PARSE_METHOD_LANGGRAPH = "langgraph";
+
+    /** §六 6.1 collect/status 响应新增键:parseSelfCheck(JSON,_解析自检) */
+    private static final String RESPONSE_KEY_PARSE_SELF_CHECK = "parseSelfCheck";
+
+    /** P0-2:LangGraph 请求字段 reportFormatHint */
+    private static final String REQUEST_KEY_REPORT_FORMAT_HINT = "reportFormatHint";
+
+    /** P0-2 / §6.1:guhe_v2 格式标记(reportFormat 值之一) */
+    private static final String FORMAT_GUHE_V2 = "guhe_v2";
+
+    /** P0-2 回退红线:不做 Java 本地兜底,通知用户提示(应可寻址) */
+    private static final String FAILBACK_USER_NOTICE = "暂不支持在线解析";
+
+    /** 上传入口(P0-2 落点①:uploadReport 自动切 upload-only + submitAsyncCollect) */
+    private static final String UPLOAD_CONTROLLER = "com.etotem.cfc.controller.HealthReportController";
+
+    /** 解析转发服务(P0-2 落点②:postParseWithReason 新增 reportFormatHint) */
+    private static final String LANGGRAPH_PARSE_SERVICE = "com.etotem.cfc.service.LangGraphReportParseService";
+
+    /** 异步采集服务(P0-2 落点③:失败标记 parse_error + 通知用户) */
+    private static final String COLLECT_SERVICE = "com.etotem.cfc.service.ReportCollectService";
+
+    /** P0-2 挂载类(GREEN 时在其上落地契约锚点;P0-1 前置 detectGuheV2Route 所在类) */
+    private static final String[] MOUNT_CLASSES = {
+            UPLOAD_CONTROLLER,
+            LANGGRAPH_PARSE_SERVICE,
+            COLLECT_SERVICE,
+            "com.etotem.cfc.entity.HealthReportDraft"
+    };
+
+    /** P0-1 前置(已落地,S-cfc-90/S-cfc-120,GuheV2RouteContractTest 8/8 绿):guhe_v2 指纹判定 */
+    private static final String P0_1_PREREQUISITE = "com.etotem.cfc.service.PdfParseService";
+
+    // ------------------------------------------------------------------
+    // 正常流:§6.1 上传响应新增键(reportFormat / parseMethod)应可寻址
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-1:上传响应应注册 reportFormat 键(§6.1)")
+    void uploadResponse_declaresReportFormatKey() {
+        Class<?> clazz = loadClass(UPLOAD_CONTROLLER);
+        if (clazz == null) {
+            fail("[health.report.guheV2AsyncRoute] 上传入口不存在:" + UPLOAD_CONTROLLER);
+        }
+        assertTrue(hasStringConstantContaining(clazz, RESPONSE_KEY_REPORT_FORMAT),
+                "[health.report.guheV2AsyncRoute] §6.1 要求 POST /api/health/report/upload 响应新增 "
+                        + "reportFormat(guhe/guhe_v2/beijing/aidefansi)字段。HealthReportController 应"
+                        + "注册静态 String 常量值含 \"reportFormat\"(上传响应键),GREEN 时 uploadReport()"
+                        + "在返回体中输出 reportFormat。当前 src/main 未注册,guhe_v2 格式无法透传前端。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:上传响应应注册 parseMethod 键且 guhe_v2 走 langgraph(§6.1 / P0-2)")
+    void uploadResponse_declaresParseMethodLanggraph() {
+        Class<?> clazz = loadClass(UPLOAD_CONTROLLER);
+        if (clazz == null) {
+            fail("[health.report.guheV2AsyncRoute] 上传入口不存在:" + UPLOAD_CONTROLLER);
+        }
+        assertTrue(hasStringConstantContaining(clazz, RESPONSE_KEY_PARSE_METHOD)
+                        && hasStringConstantContaining(clazz, PARSE_METHOD_LANGGRAPH),
+                "[health.report.guheV2AsyncRoute] §6.1 要求上传响应新增 parseMethod(local/langgraph),"
+                        + "P0-2 要求 guhe_v2 分支返回 parseMethod=\"langgraph\"。HealthReportController"
+                        + "应注册静态 String 常量值含 \"parseMethod\" 与 \"langgraph\"(guhe_v2 异步解析方式),"
+                        + "GREEN 时 guhe_v2 上传自动切 upload-only + submitAsyncCollect() 并返回该值。"
+                        + "当前 src/main 未注册,前端无法获知 guhe_v2 报告走异步 langgraph。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流:uploadReport 应具备 guhe_v2 识别分支(P0-2 落点①)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-3:上传入口应注册 guhe_v2 路由标记(P0-2 自动切换分支)")
+    void uploadReport_registersGuheV2RouteStage() {
+        Class<?> clazz = loadClass(UPLOAD_CONTROLLER);
+        if (clazz == null) {
+            fail("[health.report.guheV2AsyncRoute] 上传入口不存在:" + UPLOAD_CONTROLLER);
+        }
+        boolean registered = hasStringConstantContaining(clazz, FORMAT_GUHE_V2)
+                || hasMethodNamedLike(clazz, "guheV2");
+        assertTrue(registered,
+                "[health.report.guheV2AsyncRoute] §三 P0-2:HealthReportController.uploadReport() 识别到"
+                        + " guhe_v2 时应自动切换 upload-only + submitAsyncCollect()(复用现有异步链路)。"
+                        + "应注册 guhe_v2 路由标记(静态 String 常量值含 \"guhe_v2\",或方法名含 guheV2 的"
+                        + "识别/路由方法)。当前 src/main 无 guhe_v2 分支,32 键新版报告仍走 Java 本地解析。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流:LangGraphReportParseService 请求字段 reportFormatHint(P0-2 落点②)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-4:LangGraph 解析服务应注册 reportFormatHint 请求字段(P0-2)")
+    void langGraphService_declaresReportFormatHint() {
+        Class<?> clazz = loadClass(LANGGRAPH_PARSE_SERVICE);
+        if (clazz == null) {
+            fail("[health.report.guheV2AsyncRoute] LangGraph 解析服务不存在:" + LANGGRAPH_PARSE_SERVICE);
+        }
+        boolean declared = hasStringConstantContaining(clazz, REQUEST_KEY_REPORT_FORMAT_HINT)
+                || hasMethodNamedLike(clazz, "guheV2")
+                || hasMethodNamedLike(clazz, "formatHint");
+        assertTrue(declared,
+                "[health.report.guheV2AsyncRoute] §三 P0-2:LangGraphReportParseService.postParseWithReason()"
+                        + " 应新增请求字段 reportFormatHint=\"guhe_v2\"(Python 侧按此路由到 guhe_v2 专用"
+                        + "提取器)。应注册静态 String 常量值含 \"reportFormatHint\",或方法名含 guheV2/formatHint"
+                        + " 的私有构建方法。当前 src/main 无 reportFormatHint(全仓 0 命中),guhe_v2 报告"
+                        + "在 langgraph 侧无法路由到 extract_guhe_v2。");
+    }
+
+    @Test
+    @DisplayName("正常流-5:reportFormatHint 应携带 guhe_v2 值(P0-2)")
+    void langGraphService_declaresGuheV2HintValue() {
+        Class<?> clazz = loadClass(LANGGRAPH_PARSE_SERVICE);
+        if (clazz == null) {
+            fail("[health.report.guheV2AsyncRoute] LangGraph 解析服务不存在:" + LANGGRAPH_PARSE_SERVICE);
+        }
+        boolean declared = hasStringConstantContaining(clazz, FORMAT_GUHE_V2)
+                || hasMethodNamedLike(clazz, "guheV2");
+        assertTrue(declared,
+                "[health.report.guheV2AsyncRoute] §三 P0-2:reportFormatHint=\"guhe_v2\" 的 hint 值应可寻址"
+                        + "(静态 String 常量值含 \"guhe_v2\",或方法名含 guheV2 的请求体构建方法)。"
+                        + "当前 src/main 无 guhe_v2 锚点,Python 侧无法据此选择 extract_guhe_v2 提取器。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流:异步采集失败回退红线(P0-2 落点③:不 Java 本地兜底 → parse_error + 通知用户)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-1:guhe_v2 失败应可寻址「暂不支持在线解析」用户提示(P0-2 回退红线)")
+    void guheV2Failure_exposesNoLocalFallbackNotice() {
+        boolean addressable = false;
+        for (String clazzName : new String[]{UPLOAD_CONTROLLER, COLLECT_SERVICE, LANGGRAPH_PARSE_SERVICE}) {
+            Class<?> clazz = loadClass(clazzName);
+            if (clazz != null && hasStringConstantContaining(clazz, FAILBACK_USER_NOTICE)) {
+                addressable = true;
+                break;
+            }
+        }
+        assertTrue(addressable,
+                "[health.report.guheV2AsyncRoute] §三 P0-2(落点③):guhe_v2 异步采集失败<b>不</b>做 Java"
+                        + " 本地兜底(Java 无 guhe_v2 能力),而应标记 parse_error 并通知用户"
+                        + "「该报告格式暂不支持在线解析,可稍后重试或联系服务号」。HealthReportController /"
+                        + " ReportCollectService / LangGraphReportParseService 应注册静态 String 常量"
+                        + "(值含「暂不支持在线解析」)。当前 src/main 无此提示,guhe_v2 失败可能静默回退"
+                        + "本地解析,违反 P0-2 红线。");
+    }
+
+    @Test
+    @DisplayName("边界流-2:异步采集链应具备 guhe_v2 显式路由意识(禁静默走 v5/LLM 兜底)")
+    void asyncChain_declaresGuheV2Awareness() {
+        boolean aware = false;
+        for (String clazzName : new String[]{COLLECT_SERVICE, LANGGRAPH_PARSE_SERVICE}) {
+            Class<?> clazz = loadClass(clazzName);
+            if (clazz == null) {
+                continue;
+            }
+            if (hasStringConstantContaining(clazz, FORMAT_GUHE_V2)
+                    || hasMethodNamedLike(clazz, "guheV2")
+                    || hasMethodNamedLike(clazz, "formatHint")) {
+                aware = true;
+                break;
+            }
+        }
+        assertTrue(aware,
+                "[health.report.guheV2AsyncRoute] §三 P0-2:guhe_v2 报告一律走 langgraph 异步解析,Java 不再"
+                        + "尝试本地解析——异步采集链(ReportCollectService / LangGraphReportParseService)应具备"
+                        + " guhe_v2 显式路由意识(静态 String 常量值含 \"guhe_v2\",或方法名含 guheV2/formatHint)。"
+                        + "当前采集链无 guhe_v2 分支,32 键新版报告可能被 v5/LLM 兜底错误解析。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流:§6.1 collect/status 响应新增 parseSelfCheck
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-3:collect/status 响应应注册 parseSelfCheck 键(§6.1)")
+    void collectStatus_declaresParseSelfCheckKey() {
+        Class<?> clazz = loadClass(UPLOAD_CONTROLLER);
+        if (clazz == null) {
+            fail("[health.report.guheV2AsyncRoute] 上传入口不存在:" + UPLOAD_CONTROLLER);
+        }
+        boolean declared = hasStringConstantContaining(clazz, RESPONSE_KEY_PARSE_SELF_CHECK)
+                || hasMethodNamedLike(clazz, "parseSelfCheck");
+        assertTrue(declared,
+                "[health.report.guheV2AsyncRoute] §六 6.1:GET /api/health/report/collect/status 响应应新增"
+                        + " parseSelfCheck(JSON,_解析自检)。HealthReportController 应注册静态 String 常量"
+                        + "值含 \"parseSelfCheck\"(响应键)或方法名含 parseSelfCheck(自检解析方法)。"
+                        + "当前 src/main 无 parseSelfCheck(全仓 0 命中),前端无法展示 _解析自检 诊断。");
+    }
+
+    // ------------------------------------------------------------------
+    // 结构契约:P0-2 挂载类 + P0-1 前置(GREEN 指引锚点,当前应存在)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("结构契约-1:P0-2 挂载类应存在(GREEN 时在其上落地契约锚点)")
+    void mountClasses_exist() {
+        for (String clazzName : MOUNT_CLASSES) {
+            assertNotNull(loadClass(clazzName),
+                    "[health.report.guheV2AsyncRoute] P0-2 挂载类不存在:" + clazzName
+                            + "(若平台已重构相关层,请按当前实现更新本挂载探测)。");
+        }
+    }
+
+    @Test
+    @DisplayName("结构契约-2:P0-1 前置 detectGuheV2Route 应已落地(guhe_v2 指纹判定)")
+    void p0OnePrerequisite_detectGuheV2RouteExists() {
+        Class<?> clazz = loadClass(P0_1_PREREQUISITE);
+        assertNotNull(clazz,
+                "[health.report.guheV2AsyncRoute] 前置类不存在:" + P0_1_PREREQUISITE);
+        assertTrue(hasMethodNamedLike(clazz, "guheV2"),
+                "[health.report.guheV2AsyncRoute] P0-1 前置 detectGuheV2Route 未落地"
+                        + "(方法名应含 guheV2,先合入 guhe.l1.guheV2Route 再验收本键)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 权限流(不适用):上传→异步采集为内部路由管道,无新增用户权限维度
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("权限流:本能力为上传→异步采集内部路由管道,权限流不适用")
+    void permissionFlow_notApplicable() {
+        // 说明性用例:P0-2 为「uploadReport 识别 guhe_v2 → 自动切 upload-only + submitAsyncCollect →
+        // langgraph 异步解析」内部路由;草稿归属校验(draft.userId==当前 userId)已在 collectStatus
+        // 既有实现中,本能力不新增权限维度。不产生断言失败;仅为三流覆盖标注「不适用」。
+        assertTrue(true, "权限流不适用:health.report.guheV2AsyncRoute 为上传→异步采集内部路由管道,"
+                + "无新增用户权限维度(归属校验沿用 collectStatus 既有实现)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 反射辅助
+    // ------------------------------------------------------------------
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    /** 是否存在静态 String 常量值包含 target(响应键 / 格式标记 / hint 锚点探针) */
+    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;
+    }
+
+    /** 是否存在方法名(忽略大小写)包含片段(guheV2 / formatHint / parseSelfCheck 分支探针) */
+    private boolean hasMethodNamedLike(Class<?> clazz, String fragment) {
+        if (clazz == null) {
+            return false;
+        }
+        String needle = fragment.toLowerCase();
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().toLowerCase().contains(needle)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}