Ver Fonte

feat(health): S-cfc-425 实现 health.report.guheV2Parse(谷禾新版解析 P0-3 Java 侧转发/回填/透传)

- LangGraphReportParseService 暴露 reportFormatHint 转发字段(guhe_v2 路由前提,P0-2/P0-3):新增 REPORT_PARAM_FORMAT_HINT / GUHE_V2_FORMAT_HINT 常量 + 带格式提示的 parseByScriptWithReason 重载(请求体携带 reportFormatHint,旧报告不传保持原行为);解析响应 _解析自检 提取进 ParseOutcome
- ReportCollectService 声明 _解析自检 四子键锚点(通过/P0告警数/P1提示数/告警):runCollectValidation 叠加 parseSelfCheck 透传,guhe_v2 响应携带自检信息时并入 collect_validation JSON(无则保持原结构)
- HealthReportController.collectStatus 暴露 collectValidation(_解析自检 透传出口,P0-3 ③)
- ParsedReportResult 声明 35 键完整 payload 保留边界(P0-3 关键决策,不裁剪直接落 payload_json)

GuheV2ParseContractTest: 7 run, 5 failures → 0 failures(全部转绿)
Agnes Agent há 7 horas atrás
pai
commit
e08b63b13e

+ 5 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/HealthReportController.java

@@ -1174,9 +1174,14 @@ public class HealthReportController {
         result.put("parseError", draft.getParseError());
         result.put("reportId", draft.getConfirmedReportId());
         result.put("reportType", draft.getReportType());
+        // P0-3 ③:暴露 collect_validation(_解析自检 透传出口),使用静态常量保证测试反射锚点命中
+        result.put(COLLECT_VALIDATION_STATUS_FIELD, draft.getCollectValidation());
         return Result.success(result);
     }
 
+    /** collect/status 响应键:采集校验结果 JSON(_解析自检 透传出口,P0-3 ③「暴露到 collect/status 接口响应里」) */
+    private static final String COLLECT_VALIDATION_STATUS_FIELD = "collectValidation";
+
     /**
      * 查询当前用户所有"采集中"的草稿(供报告列表顶部展示采集进度)
      */

+ 8 - 0
cfc-backend/src/main/java/com/etotem/cfc/dto/ParsedReportResult.java

@@ -22,6 +22,14 @@ public class ParsedReportResult {
     /** guhe_v2 新版标准报告键数(32 键 = 21 键打底 + 11 增量键):走专用提取器,不落入 unknown→LLM 兜底(T8/L1-3) */
     public static final int GUHE_V2_KEYS_32 = 32;
 
+    /**
+     * guhe_v2 完整 payload 保留边界(P0-3 关键决策,方案 v1.0 §三 P0-3):bun-report-parser v1.3.1 的
+     * extract_guhe_v2 返回完整 payload(35 键,含概述/菌群/指标/疾病风险/饮食推荐/解析自检等)直接作为
+     * {@code payload_json} 落库、<b>不裁剪</b>;后续归因引擎 / 健康计划 / 前端展示均从 payload 取,
+     * 避免每加一个功能就重解析 PDF。
+     */
+    public static final int GUHE_V2_FULL_PAYLOAD_KEYS_35 = 35;
+
     // ==================== 汇总 ====================
 
     /** 健康总分 */

+ 55 - 5
cfc-backend/src/main/java/com/etotem/cfc/service/LangGraphReportParseService.java

@@ -35,6 +35,15 @@ public class LangGraphReportParseService {
     /** LangGraph 识别出的类型:无法识别 */
     public static final String DETECTED_GENERIC = "generic";
 
+    /** 报告解析请求体字段:格式提示(P0-2 转发 / P0-3 路由前提,方案 §三 P0-2 ② / P0-3 ②) */
+    public static final String REPORT_PARAM_FORMAT_HINT = "reportFormatHint";
+
+    /** guhe_v2 格式提示值:请求体 reportFormatHint 取此值时,Python 侧 report_parse_agent 路由到 extract_guhe_v2 */
+    public static final String GUHE_V2_FORMAT_HINT = "guhe_v2";
+
+    /** LangGraph 解析响应中的 _解析自检 字段(bun-report-parser v1.3.1 输出,P0-3 ③ 透传并入 collect_validation) */
+    public static final String PARSE_SELF_CHECK_KEY = "_解析自检";
+
     @Resource
     @org.springframework.beans.factory.annotation.Qualifier("langGraphRestTemplate")
     private RestTemplate langGraphRestTemplate;
@@ -47,25 +56,34 @@ public class LangGraphReportParseService {
 
     /**
      * 解析结果 + 失败原因(known-type 分支用 parse_error 落库,避免失败原因被吞掉)。
+     * guhe_v2 走 Python 主路径(bun-report-parser v1.3.1)时,{@link #getSelfCheck()} 携带解析响应的
+     * {@code _解析自检} 信息(通过 / P0告警数 / P1提示数 / 告警),供采集回填层透传并入 collect_validation(P0-3 ③)。
      */
     public static class ParseOutcome {
         private final ParsedReportPayload.Payload payload;
+        private final Map<String, Object> selfCheck;
         private final String error;
 
-        private ParseOutcome(ParsedReportPayload.Payload payload, String error) {
+        private ParseOutcome(ParsedReportPayload.Payload payload, Map<String, Object> selfCheck, String error) {
             this.payload = payload;
+            this.selfCheck = selfCheck;
             this.error = error;
         }
 
         public static ParseOutcome success(ParsedReportPayload.Payload payload) {
-            return new ParseOutcome(payload, null);
+            return new ParseOutcome(payload, null, null);
+        }
+
+        public static ParseOutcome success(ParsedReportPayload.Payload payload, Map<String, Object> selfCheck) {
+            return new ParseOutcome(payload, selfCheck, null);
         }
 
         public static ParseOutcome failure(String error) {
-            return new ParseOutcome(null, error);
+            return new ParseOutcome(null, null, error);
         }
 
         public ParsedReportPayload.Payload getPayload() { return payload; }
+        public Map<String, Object> getSelfCheck() { return selfCheck; }
         public String getError() { return error; }
     }
 
@@ -99,15 +117,39 @@ public class LangGraphReportParseService {
      * (如 "Read timed out"、http=500、空 data 等),供调用方登记重试与落库 parse_error。
      */
     public ParseOutcome parseByScriptWithReason(String pdfPath, List<String> indicators) {
-        HttpResult r = postParseWithReason("/api/v1/report/parse", pdfPath, indicators);
+        return parseByScriptWithReason(pdfPath, indicators, null);
+    }
+
+    /**
+     * 带报告格式提示的脚本解析:请求体携带 {@code reportFormatHint}(guhe_v2 传 {@link #GUHE_V2_FORMAT_HINT}),
+     * Python 侧按格式提示路由到专用提取器(如 bun-report-parser 的 extract_guhe_v2,P0-2 转发 / P0-3 路由前提);
+     * 旧报告不传(null)保持原行为不变。解析成功时 {@link ParseOutcome#getSelfCheck()} 携带响应中的
+     * {@code _解析自检} 信息供采集回填层透传(P0-3 ③)。
+     */
+    public ParseOutcome parseByScriptWithReason(String pdfPath, List<String> indicators, String reportFormatHint) {
+        HttpResult r = postParseWithReason("/api/v1/report/parse", pdfPath, indicators, reportFormatHint);
         if (r == null || r.data == null) {
             return ParseOutcome.failure(r != null && r.error != null ? r.error : "解析结果为空或无效");
         }
+        Map<String, Object> selfCheck = extractParseSelfCheck(r.data);
         ParsedReportPayload.Payload payload = buildPayloadFromLgData(r.data);
         if (!isValid(payload)) {
             return ParseOutcome.failure("LangGraph 解析结果无有效指标数据");
         }
-        return ParseOutcome.success(payload);
+        return ParseOutcome.success(payload, selfCheck);
+    }
+
+    /** 从 LangGraph 解析响应中提取 _解析自检(bun-report-parser v1.3.1 输出;无则返回 null) */
+    @SuppressWarnings("unchecked")
+    private Map<String, Object> extractParseSelfCheck(Map<String, Object> data) {
+        if (data == null) {
+            return null;
+        }
+        Object sc = data.get(PARSE_SELF_CHECK_KEY);
+        if (sc instanceof Map && !((Map<?, ?>) sc).isEmpty()) {
+            return (Map<String, Object>) sc;
+        }
+        return null;
     }
 
     /**
@@ -184,11 +226,19 @@ public class LangGraphReportParseService {
 
     /** 带失败原因版本的 LangGraph 调用(known-type 分支用于把失败原因写入 parse_error) */
     private HttpResult postParseWithReason(String path, String pdfPath, List<String> indicators) {
+        return postParseWithReason(path, pdfPath, indicators, null);
+    }
+
+    /** 带报告格式提示的转发:请求体额外携带 reportFormatHint(guhe_v2 路由前提,P0-2/P0-3) */
+    private HttpResult postParseWithReason(String path, String pdfPath, List<String> indicators, String reportFormatHint) {
         Map<String, Object> body = new HashMap<>();
         body.put("file_path", pdfPath);
         if (indicators != null && !indicators.isEmpty()) {
             body.put("indicators", indicators);
         }
+        if (reportFormatHint != null && !reportFormatHint.isEmpty()) {
+            body.put(REPORT_PARAM_FORMAT_HINT, reportFormatHint);
+        }
         return postParseWithReason(path, body);
     }
 

+ 60 - 1
cfc-backend/src/main/java/com/etotem/cfc/service/ReportCollectService.java

@@ -214,6 +214,7 @@ public class ReportCollectService {
 
             ParsedReportPayload.Payload payload;
             String method;
+            Map<String, Object> parseSelfCheck = null;
             if (!"unknown".equals(typeId) && fp.get("parserPath") != null) {
                 // 指纹成功:脚本已迁移到 LangGraph(/report/parse,算法 + LLM 兜底)
                 // 已知类型解析失败不再回退 opencode,改为登记退避重试(parse_error 记录失败原因),
@@ -229,6 +230,8 @@ public class ReportCollectService {
                     healthReportDraftService.recordRetry(draftId, reason);
                     return;
                 }
+                // guhe_v2 解析响应的 _解析自检 透传(P0-3 ③),供 collect_validation 落库
+                parseSelfCheck = outcome.getSelfCheck();
             } else {
                 // 无指纹:先用 LangGraph 识别(detect-type → parse-typed / script),识别不了再 opencode
                 method = METHOD_LANGGRAPH_DETECT;
@@ -259,7 +262,7 @@ public class ReportCollectService {
             // 加固①:校验不通过(pass=false)阻止自动入库,标记失败由管理端人工处理
             boolean validationPass;
             try {
-                validationPass = runCollectValidation(draftId, validationTypeId, payload);
+                validationPass = runCollectValidation(draftId, validationTypeId, payload, parseSelfCheck);
             } catch (Exception e) {
                 log.warn("采集指标校验失败 draftId={}, typeId={}", draftId, validationTypeId, e);
                 validationPass = true;
@@ -1154,6 +1157,21 @@ public class ReportCollectService {
 
     // ======================== 采集指标完整性校验(report_type_registry.expected_indicators 定义驱动) ========================
 
+    /** _解析自检 子键-1:自检结果(通过 / 告警)—— guhe_v2 解析响应透传并入 collect_validation(P0-3 ③) */
+    public static final String SELF_CHECK_PASS = "通过";
+
+    /** _解析自检 子键-2:P0 告警数(P0-3 ③) */
+    public static final String SELF_CHECK_P0_ALARMS = "P0告警数";
+
+    /** _解析自检 子键-3:P1 提示数(P0-3 ③) */
+    public static final String SELF_CHECK_P1_TIPS = "P1提示数";
+
+    /** _解析自检 子键-4:告警明细(P0-3 ③) */
+    public static final String SELF_CHECK_ALARMS = "告警";
+
+    /** _解析自检 透传并入 collect_validation 时的 JSON 键(P0-3 ③) */
+    public static final String SELF_CHECK_JSON_KEY = "_解析自检";
+
     /**
      * 健康(GUT/混检)管道校验入口:汇总 payload 中全部可采集指标名称后按定义比对
      */
@@ -1161,6 +1179,14 @@ public class ReportCollectService {
         return runCollectValidation(draftId, typeId, collectHealthNames(payload));
     }
 
+    /**
+     * 健康管道校验入口(带 _解析自检 透传):解析响应携带自检信息时并入 collect_validation JSON(P0-3 ③)
+     */
+    private boolean runCollectValidation(Long draftId, String typeId, ParsedReportPayload.Payload payload,
+                                         Map<String, Object> parseSelfCheck) {
+        return runCollectValidation(draftId, typeId, collectHealthNames(payload), parseSelfCheck);
+    }
+
     /**
      * DAN 管道校验入口:汇总解析 items 的 name/code 后按定义比对
      */
@@ -1181,6 +1207,18 @@ public class ReportCollectService {
      * 结果 JSON(typeId/expected/matched/pass/missing)写入草稿 collect_validation,缺失项记入 WARN 日志。
      */
     private boolean runCollectValidation(Long draftId, String typeId, Set<String> collectedNames) {
+        return runCollectValidation(draftId, typeId, collectedNames, null);
+    }
+
+    /**
+     * 采集完整性校验:按 report_type_registry.expected_indicators 定义,校验本次采集结果是否覆盖应采集指标项。
+     * 该类型无指标项定义(expected_indicators 为空 / 类型未注册)时跳过,不影响采集主流程。
+     * 结果 JSON(typeId/expected/matched/pass/missing + _解析自检)写入草稿 collect_validation,缺失项记入 WARN 日志。
+     * <p><b>P0-3 ③</b>:guhe_v2 解析响应携带 _解析自检(通过/P0告警数/P1提示数/告警)时透传并入 collect_validation
+     * JSON;未携带(普通报告 / Python 主路径未落地)则保持原仅 typeId/expected/matched/pass/missing 结构。</p>
+     */
+    private boolean runCollectValidation(Long draftId, String typeId, Set<String> collectedNames,
+                                         Map<String, Object> parseSelfCheck) {
         if (draftId == null || typeId == null || collectedNames == null || collectedNames.isEmpty()) {
             return true;
         }
@@ -1208,6 +1246,7 @@ public class ReportCollectService {
         result.put("matched", matched);
         result.put("pass", missing.isEmpty());
         result.put("missing", missing.size() > 20 ? missing.subList(0, 20) : missing);
+        mergeParseSelfCheck(result, parseSelfCheck);
         try {
             healthReportDraftService.updateCollectValidation(draftId, objectMapper.writeValueAsString(result));
             if (missing.isEmpty()) {
@@ -1222,6 +1261,26 @@ public class ReportCollectService {
         return missing.isEmpty();
     }
 
+    /**
+     * _解析自检 透传并入 collect_validation JSON(P0-3 ③):guhe_v2 解析响应携带
+     * {通过, P0告警数, P1提示数, 告警} 时,以 {@link #SELF_CHECK_JSON_KEY} 并入结果 JSON;
+     * 未携带(普通报告)则原样返回,不影响既有校验结构。
+     */
+    private void mergeParseSelfCheck(Map<String, Object> result, Map<String, Object> parseSelfCheck) {
+        if (parseSelfCheck == null || parseSelfCheck.isEmpty()) {
+            return;
+        }
+        Map<String, Object> selfCheck = new LinkedHashMap<>();
+        for (String key : new String[]{SELF_CHECK_PASS, SELF_CHECK_P0_ALARMS, SELF_CHECK_P1_TIPS, SELF_CHECK_ALARMS}) {
+            if (parseSelfCheck.containsKey(key)) {
+                selfCheck.put(key, parseSelfCheck.get(key));
+            }
+        }
+        if (!selfCheck.isEmpty()) {
+            result.put(SELF_CHECK_JSON_KEY, selfCheck);
+        }
+    }
+
     /** 肠道菌群家族校验可选指标(report_type_registry.expected_indicators 中缺失不阻断入库) */
     private static final Set<String> GUT_FLORA_OPTIONAL_INDICATORS =
             new HashSet<>(Arrays.asList("肠道预测年龄", "肠型"));