Преглед изворни кода

feat(guhe.l1.shellGuard): S-cfc-89 T13 空壳率防错 实现+契约测试7绿

新增空壳守卫常量(11/32/26/extract_guhe_v2)与 guardShell/ShellGuardDecision 入口方法,非破坏性审计挂入专用解析器分支;
实现从并发 rebase 丢弃的 WIP 悬挂提交 60f5746ec 原样恢复;未动 PdfParseService(T12)/FiveDimAttributionEngine(T14) 工作区增量。
E2E Test Bot пре 1 недеља
родитељ
комит
0ad69b882

+ 153 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/ReportParserDispatchService.java

@@ -49,6 +49,32 @@ public class ReportParserDispatchService {
 
     private static final int AUTO_LEARN_THRESHOLD = 3;
 
+    // ======================== T13 空壳率防错(L1-4,能力键 guhe.l1.shellGuard) ========================
+
+    /**
+     * T13/L1-4:guhe_v2 增量键数(计划 §2.1:谷禾 2026-11 新版标准报告 = 旧 21 键打底 + 11 增量键 = 32 键)。
+     * guhe_v2 解析后校验增量 11 键齐全的基准。
+     */
+    public static final int GUHE_V2_INCREMENTAL_KEYS = 11;
+
+    /**
+     * T13/L1-4:guhe_v2 总键数 32(21 旧键 + 11 增量键)。
+     * 区分完整 guhe_v2 报告(32 键)与空壳(不足 32 键)。
+     */
+    public static final int GUHE_V2_TOTAL_KEYS = 32;
+
+    /**
+     * T13/L1-4:空壳签名 26 键(曾误用艾德范思提取器仅产 26 键的空壳假 JSON)。
+     * 判为空壳 → 换用正确提取器 {@link #GUHE_V2_EXTRACTOR_SCRIPT}。
+     */
+    public static final int EMPTY_SHELL_KEYS = 26;
+
+    /**
+     * T13/L1-4:正确提取器脚本名(空壳时切换目标,「换正确提取器」)。
+     * 对应采集器 {@code extract_guhe_v2.py}(计划 §2.1)。
+     */
+    public static final String GUHE_V2_EXTRACTOR_SCRIPT = "extract_guhe_v2";
+
     /**
      * 解析报告:指纹检测 → 专用解析器 或 LLM 兜底
      */
@@ -68,6 +94,20 @@ public class ReportParserDispatchService {
             result.put("typeId", typeId);
             result.put("parsedData", parsed);
             result.put("parseMethod", "dedicated_parser");
+
+            // T13/L1-4 空壳守卫(非破坏性审计):解析后校验增量 11 键齐全,
+            // 空壳签名(26 键,误用艾德范思提取器产物)→ 记录告警并提示换用 extract_guhe_v2。
+            // 仅审计不自动重解析:T7 指纹路由 / T8 新旧分流落地前,旧 21 键标准报告
+            // 键数 < 32 属正常,不得误伤;切换动作由调用方按 getSwitchToExtractor() 决定。
+            ShellGuardDecision guard = guardShell(typeId, parsed);
+            result.put("shellGuard", guard);
+            if (guard.getSwitchToExtractor() != null) {
+                log.warn("T13 空壳守卫: typeId={}, keyCount={}, message={}",
+                        typeId, guard.getKeyCount(), guard.getMessage());
+            } else {
+                log.debug("T13 空壳守卫: typeId={}, keyCount={}, 增量键齐全={}",
+                        typeId, guard.getKeyCount(), guard.isIncrementalComplete());
+            }
             return Result.success(result);
         }
 
@@ -91,6 +131,119 @@ public class ReportParserDispatchService {
         }
     }
 
+    /**
+     * T13/L1-4 空壳守卫入口(guhe_v2 解析后校验增量 11 键齐全)。
+     *
+     * <p>契约(计划 2026-11-08-浠艾福平台程序修改计划.md §三-T13 / §一-L1-4 / §2.1):
+     * 空壳(曾误用艾德范思提取器产 <b>26 键</b>)→ 判为空壳 → 换用正确提取器
+     * {@link #GUHE_V2_EXTRACTOR_SCRIPT}({@code extract_guhe_v2})。</p>
+     *
+     * <p><b>口径</b>:本守卫按键数签名判定(§2.1 定义的 32/26/11 三常量):
+     * <ul>
+     *   <li>解析产物键数 == {@link #EMPTY_SHELL_KEYS}(26)→ 空壳命中,{@link ShellGuardDecision#getSwitchToExtractor()}
+     *       返回 {@link #GUHE_V2_EXTRACTOR_SCRIPT}(换正确提取器);</li>
+     *   <li>解析产物键数 &lt; {@link #GUHE_V2_TOTAL_KEYS}(32)且非空壳签名 → 增量 11 键不齐(不完整),
+     *       同样提示换用正确提取器重跑;</li>
+     *   <li>解析产物键数 == {@link #GUHE_V2_TOTAL_KEYS}(32)→ 增量 11 键齐全,判定通过(不换提取器)。</li>
+     * </ul>
+     * 增量键名级校验依赖「谷禾2026新版扩展知识」扩展块(+guhe2026.2,11 子键),该扩展资产位于
+     * 工作区《浠艾福-报告归因方案-总体设计修改方案-v1.1.md》配套库,尚未随本 checkout 入库;
+     * 故本守卫以键数签名(32/26/11)作为可验证基准,键名集合待扩展块入库后由 T9/KB 版本感知补齐。</p>
+     *
+     * <p><b>非破坏性</b>:本守卫只判定不执行重解析;调用方(parseReport 管线 / 后续 T7 路由)按
+     * {@link ShellGuardDecision#getSwitchToExtractor()} 非空时决定是否切换提取器重跑。避免在
+     * T7 指纹路由 / T8 新旧分流落地前误伤旧 21 键标准报告。</p>
+     *
+     * @param typeId     指纹检测类型(可为空;用于审计日志)
+     * @param parsedData 解析产物(顶层键 Map;guhe 系列报告经专用解析器产出)
+     * @return 空壳守卫判定(含是否空壳 / 增量键是否齐全 / 是否需切换提取器)
+     */
+    public ShellGuardDecision guardShell(String typeId, Map<String, Object> parsedData) {
+        if (parsedData == null) {
+            return ShellGuardDecision.incomplete(typeId, 0,
+                    "解析产物为空(键数 0),增量 11 键不齐 → 换用正确提取器", GUHE_V2_EXTRACTOR_SCRIPT);
+        }
+        int keyCount = parsedData.size();
+        if (keyCount == EMPTY_SHELL_KEYS) {
+            return ShellGuardDecision.shell(typeId, keyCount,
+                    "空壳签名 26 键(曾误用艾德范思提取器产物)→ 换用正确提取器 " + GUHE_V2_EXTRACTOR_SCRIPT,
+                    GUHE_V2_EXTRACTOR_SCRIPT);
+        }
+        if (keyCount < GUHE_V2_TOTAL_KEYS) {
+            return ShellGuardDecision.incomplete(typeId, keyCount,
+                    "键数 " + keyCount + " < " + GUHE_V2_TOTAL_KEYS
+                            + "(旧 21 键 + 增量 11 键),增量键不齐 → 换用正确提取器 " + GUHE_V2_EXTRACTOR_SCRIPT,
+                    GUHE_V2_EXTRACTOR_SCRIPT);
+        }
+        return ShellGuardDecision.complete(typeId, keyCount,
+                "guhe_v2 解析后增量 " + GUHE_V2_INCREMENTAL_KEYS + " 键齐全(总键数 " + GUHE_V2_TOTAL_KEYS + ")");
+    }
+
+    /**
+     * T13/L1-4 空壳守卫判定结果。
+     *
+     * <p>携带空壳命中 / 增量键齐全状态与「切换提取器」目标({@link ReportParserDispatchService#GUHE_V2_EXTRACTOR_SCRIPT}
+     * 或 {@code null} 表示无需切换)。</p>
+     */
+    public static final class ShellGuardDecision {
+
+        private final boolean emptyShell;
+        private final boolean incrementalComplete;
+        private final String typeId;
+        private final int keyCount;
+        private final String message;
+        private final String switchToExtractor;
+
+        private ShellGuardDecision(boolean emptyShell, boolean incrementalComplete,
+                                   String typeId, int keyCount, String message, String switchToExtractor) {
+            this.emptyShell = emptyShell;
+            this.incrementalComplete = incrementalComplete;
+            this.typeId = typeId;
+            this.keyCount = keyCount;
+            this.message = message;
+            this.switchToExtractor = switchToExtractor;
+        }
+
+        static ShellGuardDecision shell(String typeId, int keyCount, String message, String switchToExtractor) {
+            return new ShellGuardDecision(true, false, typeId, keyCount, message, switchToExtractor);
+        }
+
+        static ShellGuardDecision incomplete(String typeId, int keyCount, String message, String switchToExtractor) {
+            return new ShellGuardDecision(false, false, typeId, keyCount, message, switchToExtractor);
+        }
+
+        static ShellGuardDecision complete(String typeId, int keyCount, String message) {
+            return new ShellGuardDecision(false, true, typeId, keyCount, message, null);
+        }
+
+        /** 是否命中空壳签名(26 键,误用艾德范思提取器产物) */
+        public boolean isEmptyShell() {
+            return emptyShell;
+        }
+
+        /** 增量 11 键是否齐全(guhe_v2 总键数 32) */
+        public boolean isIncrementalComplete() {
+            return incrementalComplete;
+        }
+
+        public String getTypeId() {
+            return typeId;
+        }
+
+        public int getKeyCount() {
+            return keyCount;
+        }
+
+        public String getMessage() {
+            return message;
+        }
+
+        /** 切换提取器目标(非空表示需换用 {@code extract_guhe_v2} 重跑),{@code null} 表示无需切换 */
+        public String getSwitchToExtractor() {
+            return switchToExtractor;
+        }
+    }
+
     /**
      * 调用 cfc-langgraph 的 LLM 解析端点
      */

+ 69 - 0
docs/tdd/impl-2026-11-09-S-cfc-89-guhe-l1-shellGuard.md

@@ -0,0 +1,69 @@
+# T13 空壳率防错(L1-4)实现报告 — S-cfc-89
+
+- **任务**:T13 空壳率防错(guhe.l1.shellGuard),计划 `docs/superpowers/plans/2026-11-08-浠艾福平台程序修改计划.md` §三-T13 / §一-L1 接入归一化 ④ / §2.1
+- **契约测试**:`cfc-backend/src/test/java/com/etotem/cfc/unit/GuheShellGuardContractTest.java`(反射结构契约,7/7 绿)
+- **合入**:`ReportParserDispatchService`(L1 接入归一化层入口,补丁式修改,非重写)
+- **日期**:2026-11-09
+
+## 一、问题背景
+
+guhe_v2 新版标准报告(谷禾 2026-11 新版)= 旧 21 键打底 + 11 增量键 = **32 键**(计划 §2.1)。
+曾出现「误用艾德范思提取器」只产出 **26 键** 空壳假 JSON 的情况,被当作正常解析结果入库,
+导致空壳率偏高、归因质量受损。T13 要求在 guhe_v2 解析后校验增量 11 键齐全,空壳(26 键)→
+换用正确提取器。
+
+## 二、探测结论(C 档 4 项)
+
+| # | 探测项 | 结论 | 依据 |
+|---|--------|------|------|
+| C1 | Adapter(L1 接入归一化入口形态) | `ReportParserDispatchService#parseReport` 为入口(指纹检测 → 专用解析器 / LLM 兜底);采用**补丁修改**,不重写 | `src/main/java/com/etotem/cfc/service/ReportParserDispatchService.java` |
+| C2 | KB(知识库层) | `UnifiedKnowledgeBaseService`(service 层),不参与 L1 空壳守卫;本次不动 | `service/UnifiedKnowledgeBaseService.java` |
+| C3 | L4 引擎 | 已存在 `FiveDimAttributionEngine`(五维归因引擎),与 L1 守卫无耦合 | `service/attribution/FiveDimAttributionEngine.java` |
+| C4 | 合规门禁 | `AttributionComplianceGate#enforceLowSide()` 已实现(G-1 低侧扣分口径拦截),本次不重复造 | `service/attribution/AttributionComplianceGate.java` |
+
+## 三、键数签名口径(非键名级)
+
+本地知识库 `统一知识库.json` 仍为 v3.0,**无 Guhe2026 新版段**;「谷禾2026新版扩展知识」扩展块
+(+guhe2026.2,11 子键)位于工作区《浠艾福-报告归因方案-总体设计修改方案-v1.1.md》配套库,
+尚未随本 checkout 入库。因此 T13 采用**键数签名**(32/26/11 三常量)作为可验证基准;
+增量键名集合待扩展块入库后由 T9/KB 版本感知补齐(设计注,非本次缺口)。
+
+## 四、实现内容(ReportParserDispatchService)
+
+1. **常量**(§2.1 基准):
+   - `GUHE_V2_INCREMENTAL_KEYS = 11`(增量键数)
+   - `GUHE_V2_TOTAL_KEYS = 32`(guhe_v2 总键数 = 21 旧键 + 11 增量键)
+   - `EMPTY_SHELL_KEYS = 26`(空壳签名:误用艾德范思提取器产物)
+   - `GUHE_V2_EXTRACTOR_SCRIPT = "extract_guhe_v2"`(正确提取器寻址)
+2. **入口方法** `guardShell(String typeId, Map<String,Object> parsedData)`:
+   - `parsedData == null` → `incomplete`(键数 0,提示换提取器)
+   - 键数 26 → `shell`(空壳命中 → `getSwitchToExtractor() = extract_guhe_v2`)
+   - 键数 < 32 → `incomplete`(增量 11 键不齐 → 提示换提取器)
+   - 键数 == 32 → `complete`(增量键齐全,不换提取器)
+3. **判定结果** `ShellGuardDecision`(public static final class):
+   - 暴露 `isEmptyShell()` / `isIncrementalComplete()` / `getKeyCount()` / `getMessage()` / `getSwitchToExtractor()`
+4. **挂载**:`parseReport` 专用解析器分支(2a)解析后调用 `guardShell`,结果写入返回 JSON 的
+   `shellGuard` 字段;命中空壳/不完整时 `log.warn`,否则 `log.debug`。
+
+## 五、非破坏性决策(不自动重解析)
+
+T7 指纹路由(guhe_v2 路由)与 T8 新旧分流(32 键新报告 / 21 键旧报告)落地前,
+旧 21 键标准报告的键数天然 < 32,若自动换提取器重跑会误伤旧报告。故本守卫**只判定不重解析**:
+`ShellGuardDecision#getSwitchToExtractor()` 非空时由调用方决定是否切换(当前仅审计 + 入结果 JSON),
+切换动作待 T7/T8 落地后接上。
+
+## 六、验证
+
+- `mvn -q -DskipTests compile`:通过
+- `mvn -q -Dtest=GuheShellGuardContractTest test`:**7/7 绿**
+- cfc-web `npm run build`:`DONE Build complete`(dist/index.html 产出)
+
+## 七、变更文件
+
+- `cfc-backend/src/main/java/com/etotem/cfc/service/ReportParserDispatchService.java`(+153:T13 常量 + guardShell + ShellGuardDecision + parseReport 挂载)
+- `docs/superpowers/plans/2026-11-08-浠艾福平台程序修改计划.md`(T13 勾选)
+- `docs/tdd/impl-2026-11-09-S-cfc-89-guhe-l1-shellGuard.md`(本报告)
+- 未动:`PdfParseService.java`(T12)、`FiveDimAttributionEngine.java`(T14)工作区增量
+
+> 注:实现曾因并发 agent 的 rebase 暂存清理(WIP `60f5746ec` 悬挂提交)而短暂脱离 HEAD,
+> 已从该提交按 blob 原样恢复并复核,非重写。