Browse Source

feat(health.ops.parseMonitor): 解析监控看板落地(S-cfc-429)

- ParseMonitorService: P0 命中率(collect_validation pass 占比)/ P1 Top 5 五类健康问题索引锚点 / 解析耗时聚合与 next_retry_at 待重试健康度 / bun-report-parser 上游同步锚点 / getMonitorOverview 看板入口
- ParseMonitorController: /api/admin/parse-monitor/* 4 端点(overview/p0-hit-rate/p1-top5/duration),admin 角色门控(@RequestAttribute role)
- 契约测试 ParseMonitorContractTest 13/13 转绿(原 12 红 1 绿);mvn compile 通过
- docs: API_REFERENCE.md 4.66 + PROJECT-OVERVIEW 变更登记
E2E Test Bot 1 day ago
parent
commit
c39d0cbb9b

+ 61 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/admin/ParseMonitorController.java

@@ -0,0 +1,61 @@
+package com.etotem.cfc.controller.admin;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.service.ParseMonitorService;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestAttribute;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import javax.annotation.Resource;
+import java.util.Map;
+
+/**
+ * 管理端-健康报告解析监控看板(能力键 {@code health.ops.parseMonitor},SC-A-02 报告解析中台)。
+ *
+ * <p>契约来源:《浠艾福程序-谷禾新版解析与五维归因升级方案 v1.0》§三 P2 运营与监控。看板为管理端能力,
+ * 所有端点均做 admin 角色校验({@code @RequestAttribute("role")} + {@code "admin"} 检查)。
+ */
+@RestController
+@RequestMapping("/api/admin/parse-monitor")
+public class ParseMonitorController {
+
+    @Resource
+    private ParseMonitorService parseMonitorService;
+
+    /** 解析监控总览(P0 命中率 + P1 Top 5 + 解析耗时 + 上游同步锚点) */
+    @PostMapping("/overview")
+    public Result<Map<String, Object>> getParseMonitorOverview(@RequestAttribute("role") String role) {
+        if (!"admin".equals(role)) {
+            return Result.error("无权限");
+        }
+        return Result.success(parseMonitorService.getMonitorOverview());
+    }
+
+    /** P0 命中率(_解析自检 P0 告警数=0 的草稿占比) */
+    @PostMapping("/p0-hit-rate")
+    public Result<Map<String, Object>> monitorP0HitRate(@RequestAttribute("role") String role) {
+        if (!"admin".equals(role)) {
+            return Result.error("无权限");
+        }
+        return Result.success(parseMonitorService.getP0HitRate());
+    }
+
+    /** P1 Top 5(健康问题索引五类高频问题排行) */
+    @PostMapping("/p1-top5")
+    public Result<Map<String, Object>> monitorP1Top5(@RequestAttribute("role") String role) {
+        if (!"admin".equals(role)) {
+            return Result.error("无权限");
+        }
+        return Result.success(parseMonitorService.getP1Top5());
+    }
+
+    /** 解析耗时监控(含 next_retry_at 待重试队列健康度) */
+    @PostMapping("/duration")
+    public Result<Map<String, Object>> monitorDuration(@RequestAttribute("role") String role) {
+        if (!"admin".equals(role)) {
+            return Result.error("无权限");
+        }
+        return Result.success(parseMonitorService.getParseDurationStats());
+    }
+}

+ 274 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/ParseMonitorService.java

@@ -0,0 +1,274 @@
+package com.etotem.cfc.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.etotem.cfc.entity.HealthReportDraft;
+import com.etotem.cfc.mapper.HealthReportDraftMapper;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.stereotype.Service;
+
+import javax.annotation.Resource;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.Date;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 解析监控服务(能力键 {@code health.ops.parseMonitor},报告解析运营与监控看板)。
+ *
+ * <p>契约来源:《浠艾福程序-谷禾新版解析与五维归因升级方案 v1.0》§三 P2 运营与监控、§八 8.5 上游同步:
+ * <ul>
+ *   <li><b>P0 命中率</b>:{@code _解析自检}(落库于 {@code health_report_drafts.collect_validation})P0 告警数=0
+ *       的草稿占比,用于后续版本迭代;</li>
+ *   <li><b>P1 Top 5</b>:健康问题索引五类高频问题({@link #CATEGORY_DIET_SNIPPET_CUT 摘录切头} /
+ *       {@link #CATEGORY_PAGEBREAK_RESIDUE PAGEBREAK 残留} / {@link #CATEGORY_ND_SEMANTICS ND 语义未区分} /
+ *       {@link #CATEGORY_STATUS_WORD_MISSING 状态词缺失} / {@link #CATEGORY_INDEX_SNIPPET_CUT 索引切头})排行;</li>
+ *   <li><b>解析耗时监控</b>:{@code parseStartedAt → parseFinishedAt} 耗时聚合;异步队列超时与重试复用既有
+ *       {@code health_report_drafts.next_retry_at}(指数退避,勿重复建);</li>
+ *   <li><b>上游同步</b>:{@link #UPSTREAM_BUN_REPORT_PARSER bun-report-parser} 每次 minor/major 升级
+ *       (v1.3.2 / v1.4 / v1.5 …)需评估同步到 langgraph 子包,建立 changelog 订阅/submodule。</li>
+ * </ul>
+ */
+@Service
+public class ParseMonitorService {
+
+    private static final Logger log = LoggerFactory.getLogger(ParseMonitorService.class);
+
+    /** P0 命中率指标锚点(§三 P2:_解析自检.P0 告警数=0 的占比) */
+    public static final String P0_HIT_RATE = "P0_HIT_RATE";
+
+    /** P1 Top 5 指标锚点(§三 P2:健康问题索引五类问题排行) */
+    public static final String P1_TOP5 = "P1_TOP5";
+
+    /** 上游同步锚点(§八 8.5):bun-report-parser changelog 订阅 / submodule */
+    public static final String UPSTREAM_BUN_REPORT_PARSER = "bun-report-parser";
+
+    /** P1 Top 5 类别-1:健康问题索引 摘录切头 */
+    public static final String CATEGORY_DIET_SNIPPET_CUT = "摘录切头";
+
+    /** P1 Top 5 类别-2:PAGEBREAK 残留 */
+    public static final String CATEGORY_PAGEBREAK_RESIDUE = "PAGEBREAK";
+
+    /** P1 Top 5 类别-3:ND 语义未区分 */
+    public static final String CATEGORY_ND_SEMANTICS = "ND语义未区分";
+
+    /** P1 Top 5 类别-4:状态词缺失 */
+    public static final String CATEGORY_STATUS_WORD_MISSING = "状态词缺失";
+
+    /** P1 Top 5 类别-5:索引切头 */
+    public static final String CATEGORY_INDEX_SNIPPET_CUT = "索引切头";
+
+    /** 看板聚合时最多扫描的草稿条数(ops 看板,控制内存与耗时) */
+    private static final int SCAN_LIMIT = 500;
+
+    @Resource
+    private HealthReportDraftMapper healthReportDraftMapper;
+
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    /** 看板入口:解析监控总览(P0 命中率 + P1 Top 5 + 解析耗时 + 上游同步锚点) */
+    public Map<String, Object> getMonitorOverview() {
+        Map<String, Object> overview = new LinkedHashMap<>();
+        overview.put("p0HitRate", getP0HitRate());
+        overview.put("p1Top5", getP1Top5());
+        overview.put("parseDuration", getParseDurationStats());
+        overview.put("upstreamSync", getUpstreamSyncAnchor());
+        overview.put("generatedAt", new Date());
+        return overview;
+    }
+
+    /**
+     * P0 命中率(§三 P2):{@code collect_validation.pass=true}(_解析自检 P0 告警数=0)的草稿占比。
+     *
+     * @return {@code {metric, total, hit, rate}},rate 为 0-100 两位小数;无自检数据时 rate=0 并置 empty=true
+     */
+    public Map<String, Object> getP0HitRate() {
+        List<HealthReportDraft> drafts = scanDrafts();
+        long total = 0;
+        long hit = 0;
+        for (HealthReportDraft d : drafts) {
+            if (d.getCollectValidation() == null || d.getCollectValidation().trim().isEmpty()) {
+                continue;
+            }
+            total++;
+            if (isCollectValidationPass(d.getCollectValidation())) {
+                hit++;
+            }
+        }
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("metric", P0_HIT_RATE);
+        result.put("label", "P0 命中率(_解析自检 P0 告警数=0 占比)");
+        result.put("total", total);
+        result.put("hit", hit);
+        result.put("rate", total == 0 ? 0d : Math.round(hit * 10000.0 / total) / 100.0);
+        result.put("empty", total == 0);
+        return result;
+    }
+
+    /**
+     * P1 Top 5(§三 P2):健康问题索引五类高频问题排行(五类类别常量为固定锚点,排名按采集校验文本命中数)。
+     *
+     * @return {@code {metric, categories:[{category, count}]}},按命中数降序、常量定义顺序稳定排序
+     */
+    public Map<String, Object> getP1Top5() {
+        String[] categories = {
+                CATEGORY_DIET_SNIPPET_CUT,
+                CATEGORY_PAGEBREAK_RESIDUE,
+                CATEGORY_ND_SEMANTICS,
+                CATEGORY_STATUS_WORD_MISSING,
+                CATEGORY_INDEX_SNIPPET_CUT
+        };
+        long[] counts = new long[categories.length];
+        for (HealthReportDraft d : scanDrafts()) {
+            StringBuilder text = new StringBuilder();
+            if (d.getCollectValidation() != null) {
+                text.append(d.getCollectValidation());
+            }
+            if (d.getParseError() != null) {
+                text.append(d.getParseError());
+            }
+            if (text.length() == 0) {
+                continue;
+            }
+            String haystack = text.toString();
+            for (int i = 0; i < categories.length; i++) {
+                if (categories[i].equals(CATEGORY_PAGEBREAK_RESIDUE)) {
+                    counts[i] += countIgnoreCase(haystack, categories[i]);
+                } else {
+                    counts[i] += countOccurrences(haystack, categories[i]);
+                }
+            }
+        }
+        List<Map<String, Object>> entries = new ArrayList<>();
+        for (int i = 0; i < categories.length; i++) {
+            Map<String, Object> entry = new LinkedHashMap<>();
+            entry.put("category", categories[i]);
+            entry.put("count", counts[i]);
+            entries.add(entry);
+        }
+        entries.sort(Comparator
+                .<Map<String, Object>>comparingLong(e -> ((Number) e.get("count")).longValue()).reversed()
+                .thenComparingInt(e -> indexOf(categories, String.valueOf(e.get("category")))));
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("metric", P1_TOP5);
+        result.put("label", "P1 Top 5(健康问题索引高频问题)");
+        result.put("categories", entries);
+        return result;
+    }
+
+    /**
+     * 解析耗时监控(§三 P2):{@code parseStartedAt → parseFinishedAt} 聚合耗时;后台指数退避重试
+     * 复用既有 {@code health_report_drafts.next_retry_at},此处透传待重试草稿数作为队列健康度指标。
+     */
+    public Map<String, Object> getParseDurationStats() {
+        List<HealthReportDraft> drafts = scanDrafts();
+        long sumMs = 0;
+        long minMs = Long.MAX_VALUE;
+        long maxMs = 0;
+        int counted = 0;
+        int pendingRetry = 0;
+        for (HealthReportDraft d : drafts) {
+            if (d.getParseStartedAt() != null && d.getParseFinishedAt() != null) {
+                long ms = d.getParseFinishedAt().getTime() - d.getParseStartedAt().getTime();
+                if (ms >= 0) {
+                    sumMs += ms;
+                    minMs = Math.min(minMs, ms);
+                    maxMs = Math.max(maxMs, ms);
+                    counted++;
+                }
+            }
+            if (d.getNextRetryAt() != null) {
+                pendingRetry++;
+            }
+        }
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("metric", "PARSE_DURATION");
+        result.put("label", "解析耗时监控(completed 草稿 parseStartedAt→parseFinishedAt)");
+        result.put("count", counted);
+        result.put("avgMs", counted == 0 ? 0 : sumMs / counted);
+        result.put("minMs", counted == 0 ? 0 : minMs);
+        result.put("maxMs", maxMs);
+        result.put("pendingRetry", pendingRetry);
+        return result;
+    }
+
+    /** 上游同步锚点(§八 8.5):bun-report-parser changelog 订阅 / submodule 评估 */
+    public Map<String, Object> getUpstreamSyncAnchor() {
+        Map<String, Object> anchor = new LinkedHashMap<>();
+        anchor.put("upstream", UPSTREAM_BUN_REPORT_PARSER);
+        anchor.put("mechanism", "changelog 订阅 / submodule");
+        anchor.put("rule", "bun-report-parser 每次 minor/major 升级(v1.3.2 / v1.4 / v1.5 …)需评估同步到 langgraph 子包");
+        return anchor;
+    }
+
+    // ------------------------------------------------------------------
+    // 内部辅助
+    // ------------------------------------------------------------------
+
+    private List<HealthReportDraft> scanDrafts() {
+        try {
+            return healthReportDraftMapper.selectList(
+                    new LambdaQueryWrapper<HealthReportDraft>()
+                            .orderByDesc(HealthReportDraft::getId)
+                            .last("LIMIT " + SCAN_LIMIT));
+        } catch (Exception e) {
+            log.warn("解析监控读取 health_report_drafts 失败: {}", e.getMessage());
+            return new ArrayList<>();
+        }
+    }
+
+    /** 解析 collect_validation JSON(typeId/expected/matched/pass/missing),pass=true 视为 P0 告警数=0 */
+    private boolean isCollectValidationPass(String json) {
+        try {
+            JsonNode node = objectMapper.readTree(json);
+            if (node != null && node.isObject() && node.has("pass")) {
+                JsonNode pass = node.get("pass");
+                return pass.isBoolean() && pass.asBoolean();
+            }
+        } catch (Exception e) {
+            log.debug("collect_validation 解析失败,按未命中处理: {}", e.getMessage());
+        }
+        return false;
+    }
+
+    private long countOccurrences(String haystack, String needle) {
+        if (needle == null || needle.isEmpty()) {
+            return 0;
+        }
+        long count = 0;
+        int idx = 0;
+        while ((idx = haystack.indexOf(needle, idx)) >= 0) {
+            count++;
+            idx += needle.length();
+        }
+        return count;
+    }
+
+    private long countIgnoreCase(String haystack, String needle) {
+        if (needle == null || needle.isEmpty()) {
+            return 0;
+        }
+        String lowerText = haystack.toLowerCase();
+        String lowerNeedle = needle.toLowerCase();
+        long count = 0;
+        int idx = 0;
+        while ((idx = lowerText.indexOf(lowerNeedle, idx)) >= 0) {
+            count++;
+            idx += lowerNeedle.length();
+        }
+        return count;
+    }
+
+    private int indexOf(String[] arr, String value) {
+        for (int i = 0; i < arr.length; i++) {
+            if (arr[i].equals(value)) {
+                return i;
+            }
+        }
+        return arr.length;
+    }
+}

File diff suppressed because it is too large
+ 0 - 0
docs/superpowers/PROJECT-OVERVIEW.md


+ 12 - 0
docs/superpowers/api/API_REFERENCE.md

@@ -797,6 +797,7 @@ find cfc-backend/src/main/java -name "*XxxService.java" -o -name "*XxxController
 | `/api/admin/ppoint-config/*` | P点配置(品类级比例+商品级固定值) |
 | `/api/admin/product/*` | 商品管理 |
 | `/api/admin/report-parser/*` | 报告解析配置 |
+| `/api/admin/parse-monitor/*` | 健康报告解析运营与监控看板(P0 命中率 / P1 Top 5 / 解析耗时 / 上游同步,SC-A-02) |
 | `/api/admin/report-template/*` | 报告展示模板管理 |
 | `/api/admin/supply-*` | 供应链相关 |
 | `/api/admin/system/*` | 系统配置 |
@@ -1036,6 +1037,17 @@ find cfc-backend/src/main/java -name "*XxxService.java" -o -name "*XxxController
 | `POST /api/admin/report-parser/unknown-uploads` | 聚类上传记录 |
 | `POST /api/admin/report-parser/generate-type` | 自学习生成报告类型 |
 
+### 4.66 管理端-健康报告解析监控看板(`/api/admin/parse-monitor/*`)
+
+> 能力键 `health.ops.parseMonitor`(S-cfc-429,SC-A-02 报告解析中台);契约来源《浠艾福程序-谷禾新版解析与五维归因升级方案 v1.0》§三 P2 运营与监控、§八 8.5 上游同步。所有端点均为管理端能力,需 admin 角色校验(`@RequestAttribute("role")`)。
+
+| 路径 | 说明 |
+|------|------|
+| `POST /api/admin/parse-monitor/overview` | 解析监控总览(聚合 P0 命中率 + P1 Top 5 + 解析耗时 + 上游同步锚点) |
+| `POST /api/admin/parse-monitor/p0-hit-rate` | P0 命中率(`_解析自检` P0 告警数=0 的草稿占比,基于 `health_report_drafts.collect_validation`) |
+| `POST /api/admin/parse-monitor/p1-top5` | P1 Top 5(健康问题索引五类高频问题:摘录切头 / PAGEBREAK 残留 / ND 语义未区分 / 状态词缺失 / 索引切头) |
+| `POST /api/admin/parse-monitor/duration` | 解析耗时监控(`parseStartedAt→parseFinishedAt` 聚合 + `next_retry_at` 待重试队列健康度) |
+
 ---
 
 ## 五、新增接口流程

Some files were not shown because too many files changed in this diff