datasentry-core 0.1.0__py3-none-any.whl

datasentry_core/detectors/missingness.py

@@ -0,0 +1,424 @@
+"""缺失模式检测器（11.4 核心，Step 16）：sudden/conditional/group/correlated。
+
+四个检测器全部 SQL pushdown、列级统计证据（双列/分组/时间桶场景不取行级证据，
+ADR-017）：
+- sudden_missingness：时间桶缺失率突变（3× 整体或 ≥0.2，桶样本 ≥10）
+- group_missingness：按类别列分组的目标列缺失率异常组
+- conditional_missingness：定向级联缺失（A 缺失时 B 缺失率 ≥0.8）
+- correlated_missingness：双列缺失高共现（共现率 ≥0.5）
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from datasentry_core.detectors.base import DetectionContext
+from datasentry_core.detectors.common import (
+    DetectorBase,
+    datetime_columns,
+    make_candidate,
+    make_evidence,
+    quote_ident,
+    string_columns,
+)
+from datasentry_core.models.detector import DetectorCapabilities, IssueCandidate
+from datasentry_core.models.enums import EvidenceType, QualityDimension, Severity
+
+# 列对/列预算：防组合爆炸（性能预算见 ADR-017）
+_NULL_RATE_MIN = 0.02
+_PAIR_COL_CAP = 15
+_PAIR_CAP = 50
+_GROUP_COL_CAP = 10
+_TARGET_COL_CAP = 5
+
+# 时间桶粒度自适应：桶数不足则升级粒度
+_BUCKET_GRANULARITIES = (("%Y-%m-%d", "day"), ("%Y-%m", "month"), ("%Y", "year"))
+_BUCKET_MIN_COUNT = 5
+_BUCKET_MIN_ROWS = 10
+
+# 字符串时间列名特征（created_at / event_date 等）
+_TIME_STR_HINTS = ("_at", "_time", "date", "time")
+
+_ISO_DT_RE = r"^\d{4}-\d{2}-\d{2}([ T]\d{2}:\d{2}:\d{2})?$"
+
+# 阈值固定为规格默认值；可配置化经契约引擎（V1，ADR-004）接入
+# 异常判定 = 桶/组缺失率 ≥ max(0.2, 整体 + 0.2)：
+# 相对 3× 在整体缺失率 >1/3 时会超 1 永不触发，故用绝对差（ADR-017）
+_GROUP_MIN_RATIO = 0.2
+_GROUP_MIN_GAP = 0.2
+_CONDITIONAL_COVERAGE = 0.8
+_CORRELATED_COVERAGE = 0.5
+_MIN_COOCCURRENCE = 5
+
+
+def _row_count(context: DetectionContext) -> int:
+    table = context.handle.sql_aggregate("SELECT count(*) AS n FROM data").table
+    return int(table.column("n").to_pylist()[0])
+
+
+def _column_nulls(context: DetectionContext, column: str) -> tuple[int, int]:
+    q = quote_ident(column)
+    table = context.handle.sql_aggregate(
+        f"SELECT count(*) AS n, sum({q} IS NULL) AS nulls FROM data"
+    ).table
+    total = int(table.column("n").to_pylist()[0])
+    nulls = int(table.column("nulls").to_pylist()[0])
+    return total, nulls
+
+
+def _null_rates(context: DetectionContext) -> dict[str, float]:
+    """全列 null 率（总行数统一）。"""
+    total = _row_count(context)
+    if total <= 0:
+        return {}
+    rates: dict[str, float] = {}
+    for col in context.columns:
+        _, nulls = _column_nulls(context, col)
+        rates[col] = nulls / total
+    return rates
+
+
+def _sparse_columns(context: DetectionContext, rates: dict[str, float]) -> list[str]:
+    """缺失率 ≥ _NULL_RATE_MIN 的列（截断至 _PAIR_COL_CAP，按缺失率降序）。"""
+    ordered = [c for c in context.columns if rates.get(c, 0.0) >= _NULL_RATE_MIN]
+    ordered.sort(key=lambda c: rates[c], reverse=True)
+    return ordered[:_PAIR_COL_CAP]
+
+
+def _anomalous_threshold(overall: float) -> float:
+    """桶/组缺失率异常阈值（绝对差判定，见模块 docstring）。"""
+    return max(_GROUP_MIN_RATIO, overall + _GROUP_MIN_GAP)
+
+
+def _column_pairs(columns: list[str]) -> list[tuple[str, str]]:
+    """有序列对（按缺失率降序的列序），截断至 _PAIR_CAP。"""
+    pairs = [(a, b) for i, a in enumerate(columns) for b in columns[i + 1 :]]
+    return pairs[:_PAIR_CAP]
+
+
+class CorrelatedMissingnessDetector(DetectorBase):
+    """缺失共现（11.4）：两列同时缺失的行显著（对称，共现率 ≥0.5）。"""
+
+    detector_id = "correlated_missingness"
+    display_name = "Correlated Missingness"
+    description = "Reports column pairs that are missing together."
+    quality_dimension = QualityDimension.COMPLETENESS
+    capabilities: ClassVar[DetectorCapabilities] = DetectorCapabilities(supports_sql_pushdown=True)
+
+    def supports(self, context: DetectionContext) -> bool:
+        return len(context.columns) >= 2
+
+    def detect(self, context: DetectionContext) -> list[IssueCandidate]:
+        rates = _null_rates(context)
+        candidates: list[IssueCandidate] = []
+        for a, b in _column_pairs(_sparse_columns(context, rates)):
+            qa, qb = quote_ident(a), quote_ident(b)
+            table = context.handle.sql_aggregate(
+                f"SELECT count(*) AS n, "
+                f"sum({qa} IS NULL AND {qb} IS NULL) AS both_null, "
+                f"sum({qa} IS NULL) AS a_null, "
+                f"sum({qb} IS NULL) AS b_null "
+                f"FROM data"
+            ).table
+            both_null = int(table.column("both_null").to_pylist()[0])
+            a_null = int(table.column("a_null").to_pylist()[0])
+            b_null = int(table.column("b_null").to_pylist()[0])
+            if both_null < _MIN_COOCCURRENCE:
+                continue
+            denominator = min(a_null, b_null)
+            coverage = both_null / denominator if denominator else 0.0
+            if coverage >= _CORRELATED_COVERAGE:
+                candidates.append(
+                    make_candidate(
+                        detector_id=self.detector_id,
+                        detector_version=self.detector_version,
+                        context=context,
+                        issue_type="correlated_missingness",
+                        columns=[a, b],
+                        affected_count=both_null,
+                        evidence=[
+                            make_evidence(
+                                detector_id=self.detector_id,
+                                detector_version=self.detector_version,
+                                evidence_type=EvidenceType.STATISTICAL_MEASURE,
+                                description=(
+                                    f"{both_null} rows are missing in both {a} and {b} "
+                                    f"(coverage={coverage:.2f})"
+                                ),
+                                data={
+                                    "column_a": a,
+                                    "column_b": b,
+                                    "both_null": both_null,
+                                    "a_null": a_null,
+                                    "b_null": b_null,
+                                    "coverage": round(coverage, 6),
+                                },
+                            )
+                        ],
+                        raw_score=coverage,
+                        confidence=0.85,
+                        severity=Severity.LOW,
+                        fpr=0.15,
+                    )
+                )
+        return candidates
+
+
+class ConditionalMissingnessDetector(DetectorBase):
+    """条件性缺失（11.4）：A 缺失 ⟹ B 缺失 的级联（定向覆盖率 ≥0.8）。"""
+
+    detector_id = "conditional_missingness"
+    display_name = "Conditional Missingness"
+    description = "Reports columns whose values are missing whenever another is."
+    quality_dimension = QualityDimension.COMPLETENESS
+    capabilities: ClassVar[DetectorCapabilities] = DetectorCapabilities(supports_sql_pushdown=True)
+
+    def supports(self, context: DetectionContext) -> bool:
+        return len(context.columns) >= 2
+
+    def detect(self, context: DetectionContext) -> list[IssueCandidate]:
+        rates = _null_rates(context)
+        candidates: list[IssueCandidate] = []
+        for a, b in _column_pairs(_sparse_columns(context, rates)):
+            qa, qb = quote_ident(a), quote_ident(b)
+            table = context.handle.sql_aggregate(
+                f"SELECT count(*) AS n, "
+                f"sum({qa} IS NULL AND {qb} IS NULL) AS both_null, "
+                f"sum({qa} IS NULL) AS a_null "
+                f"FROM data"
+            ).table
+            both_null = int(table.column("both_null").to_pylist()[0])
+            a_null = int(table.column("a_null").to_pylist()[0])
+            if a_null < 10:
+                continue
+            coverage = both_null / a_null
+            if coverage >= _CONDITIONAL_COVERAGE:
+                candidates.append(
+                    make_candidate(
+                        detector_id=self.detector_id,
+                        detector_version=self.detector_version,
+                        context=context,
+                        issue_type="conditional_missingness",
+                        columns=[a, b],
+                        affected_count=both_null,
+                        evidence=[
+                            make_evidence(
+                                detector_id=self.detector_id,
+                                detector_version=self.detector_version,
+                                evidence_type=EvidenceType.STATISTICAL_MEASURE,
+                                description=(
+                                    f"{both_null} of {a_null} missing rows of {a} are also "
+                                    f"missing in {b} (coverage={coverage:.2f})"
+                                ),
+                                data={
+                                    "condition_column": a,
+                                    "target_column": b,
+                                    "both_null": both_null,
+                                    "condition_null": a_null,
+                                    "coverage": round(coverage, 6),
+                                },
+                            )
+                        ],
+                        raw_score=coverage,
+                        confidence=0.85,
+                        severity=Severity.MEDIUM,
+                        fpr=0.15,
+                    )
+                )
+        return candidates
+
+
+def _distinct_counts(context: DetectionContext, columns: list[str]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for col in columns:
+        q = quote_ident(col)
+        table = context.handle.sql_aggregate(
+            f"SELECT count(DISTINCT {q}) AS n FROM data WHERE {q} IS NOT NULL"
+        ).table
+        counts[col] = int(table.column("n").to_pylist()[0])
+    return counts
+
+
+def _group_columns(context: DetectionContext) -> list[str]:
+    """类别分组列候选：字符串列中 distinct ∈ [2, 50]（截断 _GROUP_COL_CAP）。"""
+    cols = [c for c in string_columns(context) if len(c) <= 64]
+    if len(cols) > _GROUP_COL_CAP:
+        cols = cols[:_GROUP_COL_CAP]
+    counts = _distinct_counts(context, cols)
+    return [c for c in cols if 2 <= counts[c] <= 50]
+
+
+class GroupMissingnessDetector(DetectorBase):
+    """分组缺失（11.4）：按类别列分组后目标列缺失率异常组（≥max(0.2, 3×整体)）。"""
+
+    detector_id = "group_missingness"
+    display_name = "Grouped Missingness"
+    description = "Reports groups whose values are missing much more than usual."
+    quality_dimension = QualityDimension.COMPLETENESS
+    capabilities: ClassVar[DetectorCapabilities] = DetectorCapabilities(supports_sql_pushdown=True)
+
+    def supports(self, context: DetectionContext) -> bool:
+        return len(context.columns) >= 2
+
+    def detect(self, context: DetectionContext) -> list[IssueCandidate]:
+        rates = _null_rates(context)
+        targets = [c for c in context.columns if rates.get(c, 0.0) > 0.0]
+        group_cols = [c for c in _group_columns(context) if c not in targets]
+        candidates: list[IssueCandidate] = []
+        for group_col in group_cols:
+            for target in targets:
+                if len(candidates) >= _TARGET_COL_CAP * len(group_cols):
+                    break
+                qg, qt = quote_ident(group_col), quote_ident(target)
+                overall = rates.get(target, 0.0)
+                table = context.handle.sql_aggregate(
+                    f"SELECT {qg} AS gv, count(*) AS n, sum({qt} IS NULL) AS nulls "
+                    f"FROM data GROUP BY 1"
+                ).table
+                for row in table.to_pylist():
+                    n = int(row["n"])
+                    nulls = int(row["nulls"])
+                    ratio = nulls / n if n else 0.0
+                    if n < _BUCKET_MIN_ROWS or ratio < _anomalous_threshold(overall):
+                        continue
+                    candidates.append(
+                        make_candidate(
+                            detector_id=self.detector_id,
+                            detector_version=self.detector_version,
+                            context=context,
+                            issue_type="group_missingness",
+                            columns=[target],
+                            affected_count=nulls,
+                            evidence=[
+                                make_evidence(
+                                    detector_id=self.detector_id,
+                                    detector_version=self.detector_version,
+                                    evidence_type=EvidenceType.STATISTICAL_MEASURE,
+                                    description=(
+                                        f"{target} missing in {nulls}/{n} rows where "
+                                        f"{group_col}={row['gv']!r} (overall {overall:.4f})"
+                                    ),
+                                    data={
+                                        "group_column": group_col,
+                                        "group_value": str(row["gv"]),
+                                        "target_column": target,
+                                        "nulls": nulls,
+                                        "group_size": n,
+                                        "null_ratio": round(ratio, 6),
+                                        "overall_ratio": round(overall, 6),
+                                    },
+                                )
+                            ],
+                            raw_score=ratio,
+                            confidence=0.85,
+                            severity=Severity.MEDIUM,
+                            fpr=0.15,
+                        )
+                    )
+        return candidates
+
+
+def _time_string_columns(context: DetectionContext) -> list[str]:
+    """字符串时间列候选（列名含 _at/_time/date 特征）。"""
+    return [
+        col for col in string_columns(context) if any(h in col.lower() for h in _TIME_STR_HINTS)
+    ]
+
+
+def _bucket_sql(column: str, granularity: str) -> str:
+    q = quote_ident(column)
+    return f"strftime({q}, '{granularity}') AS bucket"
+
+
+def _time_bucket_counts(
+    context: DetectionContext, column: str, target: str, granularity: str
+) -> tuple[list[dict[str, int | str]], int]:
+    """按桶统计（target 缺失行数），返回 (桶列表, 有效桶数)。"""
+    qt = quote_ident(target)
+    bucket_expr = _bucket_sql(column, granularity)
+    table = context.handle.sql_aggregate(
+        f"SELECT {bucket_expr}, count(*) AS n, sum({qt} IS NULL) AS nulls FROM data GROUP BY 1"
+    ).table
+    buckets: list[dict[str, int | str]] = []
+    for row in table.to_pylist():
+        if row["bucket"] is None:
+            continue
+        buckets.append(
+            {"bucket": str(row["bucket"]), "n": int(row["n"]), "nulls": int(row["nulls"])}
+        )
+    return buckets, len(buckets)
+
+
+class SuddenMissingnessDetector(DetectorBase):
+    """突变缺失（11.4）：时间桶缺失率骤增（≥max(0.2, 3×整体)，桶样本 ≥10）。"""
+
+    detector_id = "sudden_missingness"
+    display_name = "Sudden Missingness"
+    description = "Reports time buckets where missingness spikes abruptly."
+    quality_dimension = QualityDimension.COMPLETENESS
+    capabilities: ClassVar[DetectorCapabilities] = DetectorCapabilities(supports_sql_pushdown=True)
+
+    def supports(self, context: DetectionContext) -> bool:
+        return bool(datetime_columns(context) or _time_string_columns(context))
+
+    def detect(self, context: DetectionContext) -> list[IssueCandidate]:
+        rates = _null_rates(context)
+        targets = [c for c in context.columns if rates.get(c, 0.0) >= 0.01]
+        targets = targets[:_TARGET_COL_CAP] if targets else []
+        time_cols = datetime_columns(context) + _time_string_columns(context)
+        if not time_cols or not targets:
+            return []
+        candidates: list[IssueCandidate] = []
+        for time_col in time_cols:
+            for target in targets:
+                overall = rates.get(target, 0.0)
+                granularity = _BUCKET_GRANULARITIES[0][0]
+                buckets, count = _time_bucket_counts(context, time_col, target, granularity)
+                if count < _BUCKET_MIN_COUNT:
+                    granularity = _BUCKET_GRANULARITIES[1][0]
+                    buckets, count = _time_bucket_counts(context, time_col, target, granularity)
+                if count < _BUCKET_MIN_COUNT:
+                    granularity = _BUCKET_GRANULARITIES[2][0]
+                    buckets, count = _time_bucket_counts(context, time_col, target, granularity)
+                threshold = _anomalous_threshold(overall)
+                for b in buckets:
+                    n, nulls = int(b["n"]), int(b["nulls"])
+                    ratio = nulls / n if n else 0.0
+                    if n < _BUCKET_MIN_ROWS or ratio < threshold:
+                        continue
+                    candidates.append(
+                        make_candidate(
+                            detector_id=self.detector_id,
+                            detector_version=self.detector_version,
+                            context=context,
+                            issue_type="sudden_missingness",
+                            columns=[target],
+                            affected_count=nulls,
+                            evidence=[
+                                make_evidence(
+                                    detector_id=self.detector_id,
+                                    detector_version=self.detector_version,
+                                    evidence_type=EvidenceType.STATISTICAL_MEASURE,
+                                    description=(
+                                        f"{target} missing in {nulls}/{n} rows in "
+                                        f"bucket {b['bucket']} (overall {overall:.4f})"
+                                    ),
+                                    data={
+                                        "time_column": time_col,
+                                        "bucket": str(b["bucket"]),
+                                        "granularity": granularity,
+                                        "target_column": target,
+                                        "nulls": nulls,
+                                        "bucket_size": n,
+                                        "null_ratio": round(ratio, 6),
+                                        "overall_ratio": round(overall, 6),
+                                    },
+                                )
+                            ],
+                            raw_score=ratio,
+                            confidence=0.9,
+                            severity=Severity.MEDIUM,
+                            fpr=0.15,
+                        )
+                    )
+        return candidates

datasentry_core/detectors/runner.py

@@ -0,0 +1,228 @@
+"""扫描调度（Step 7 配套）：跑检测器 → DetectorRun 记录 → 融合 → 评分 → ScanRun 组装。
+
+Step 35：ScanConfig.custom_rules（契约 rules）接入扫描主流程——逐规则
+run_preflight，违规行生成 IssueCandidate 参与融合（issue_type=rule.id）。
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from collections import Counter
+from datetime import UTC, datetime
+from typing import Literal
+
+from datasentry_core import __version__
+from datasentry_core.detectors.base import (
+    DetectionContext,
+    Detector,
+    DetectorRegistry,
+    filter_by_config,
+)
+from datasentry_core.detectors.common import make_candidate, make_evidence
+from datasentry_core.engine.fusion import EvidenceFusionEngine
+from datasentry_core.models.detector import IssueCandidate
+from datasentry_core.models.enums import EvidenceType, Severity
+from datasentry_core.models.issue import Issue
+from datasentry_core.models.rules import Rule
+from datasentry_core.models.scan import DetectorRun, ReproducibilityInfo, ScanConfig, ScanRun
+from datasentry_core.rules.engine import run_preflight
+from datasentry_core.scoring import ScoringEngine
+from datasentry_core.scoring.quality import QualityScoreEngine
+
+
+def _count_by_severity(issues: list[Issue]) -> dict[Severity, int]:
+    """各严重度 Issue 计数（ScanRun.issues_count，18.2）。"""
+    counts = Counter(issue.severity for issue in issues)
+    return {severity: counts.get(severity, 0) for severity in Severity}
+
+
+class ScanRunner:
+    """单数据集扫描器：支持过滤 → detect → DetectorRun → 融合 → 评分。"""
+
+    def __init__(self, registry: DetectorRegistry) -> None:
+        self._registry = registry
+        self._fusion = EvidenceFusionEngine()
+        self._scoring = ScoringEngine()
+        self._quality = QualityScoreEngine()
+
+    def run(
+        self,
+        context: DetectionContext,
+        config: ScanConfig,
+        scan_run_id: str,
+    ) -> tuple[list[DetectorRun], list[Issue]]:
+        detectors = filter_by_config(self._registry.list_active(), config.detectors)
+        runs: list[DetectorRun] = []
+        candidates: list[IssueCandidate] = []
+        for detector in detectors:
+            run = self._run_detector(detector, context, scan_run_id)
+            runs.append(run)
+            if run.status == "completed":
+                candidates.extend(detector.detect(context))
+        if config.custom_rules:
+            runs.append(
+                self._run_contract_rules(context, config.custom_rules, candidates, scan_run_id)
+            )
+        fused = self._fusion.fuse(candidates, scan_run_id, row_count=context.handle.count_rows())
+        issues = [self._scoring.apply(issue) for issue in fused]
+        return runs, issues
+
+    def _run_contract_rules(
+        self,
+        context: DetectionContext,
+        rules: list[Rule],
+        candidates: list[IssueCandidate],
+        scan_run_id: str,
+    ) -> DetectorRun:
+        """契约规则执行（Step 35）：逐规则 run_preflight，违规进融合。
+
+        schema/表达式无效的规则记为该 DetectorRun 失败（scan 随之 failed）。
+        """
+        started = time.monotonic()
+        issues_candidates = len(rules)
+        failed_rules: list[str] = []
+        for rule in rules:
+            report = run_preflight(rule, context.handle)
+            if not report.valid:
+                reason = "missing columns" if not report.schema_valid else "invalid expression"
+                failed_rules.append(f"{rule.id}: {reason}")
+                continue
+            sample = report.sample_run
+            if sample is None or sample.failures <= 0:
+                continue
+            evidence = [
+                make_evidence(
+                    detector_id="contract_rule",
+                    detector_version=str(rule.version),
+                    evidence_type=EvidenceType.RULE_VIOLATION,
+                    description=(
+                        f"rule {rule.id}: {sample.failures} of {sample.rows_tested} rows "
+                        f"violate ({sample.failure_ratio:.4f})"
+                    ),
+                    data={
+                        "rule_id": rule.id,
+                        "rule_version": rule.version,
+                        "failures": sample.failures,
+                        "rows_tested": sample.rows_tested,
+                        "examples": sample.example_rows[:5],
+                    },
+                )
+            ]
+            candidates.append(
+                make_candidate(
+                    detector_id="contract_rule",
+                    detector_version=str(rule.version),
+                    context=context,
+                    issue_type=f"rule:{rule.id}",
+                    columns=[rule.when.column] if rule.when else list(rule.columns),
+                    affected_count=sample.failures,
+                    affected_rows=None,
+                    evidence=evidence,
+                    raw_score=sample.failure_ratio,
+                    confidence=0.95,
+                    severity=rule.severity,
+                )
+            )
+        status: Literal["completed", "failed"] = "failed" if failed_rules else "completed"
+        error = "; ".join(failed_rules) if failed_rules else None
+        return DetectorRun(
+            id=f"det_{uuid.uuid4().hex[:12]}",
+            scan_run_id=scan_run_id,
+            detector_id="contract_rule",
+            detector_version="1.0",
+            status=status,
+            rows_scanned=context.handle.count_rows(),
+            duration_ms=int((time.monotonic() - started) * 1000),
+            issues_candidates=issues_candidates,
+            error=error,
+        )
+
+    def run_scan(
+        self,
+        context: DetectionContext,
+        config: ScanConfig | None = None,
+    ) -> tuple[ScanRun, list[DetectorRun], list[Issue]]:
+        """完整扫描入口：跑检测器 → 融合 → 评分 → 组装 ScanRun（18.2）。
+
+        返回 (scan_run, detector_runs, issues)，便于调用方持久化与展示。
+        """
+        config = config or ScanConfig()
+        scan_run_id = f"scan_{uuid.uuid4().hex[:12]}"
+        started_at = datetime.now(UTC)
+        runs, issues = self.run(context, config, scan_run_id)
+        failed = [r for r in runs if r.status == "failed"]
+        status: Literal["completed", "failed"] = "failed" if failed else "completed"
+        error = "; ".join(f"{r.detector_id}: {r.error}" for r in failed) if failed else None
+        ran_dimensions = set()
+        for run in runs:
+            if run.status != "completed":
+                continue
+            try:
+                detector = self._registry.get(run.detector_id)
+            except KeyError:
+                continue  # 契约规则 run（非注册检测器）不参与维度统计
+            ran_dimensions.add(detector.quality_dimension)
+        try:
+            quality_score = self._quality.score(issues, ran_dimensions=ran_dimensions)
+        except ValueError:  # 无任何检测器运行（空白名单）→ 未评分
+            quality_score = None
+        scan_run = ScanRun(
+            id=scan_run_id,
+            dataset_id=context.dataset_id,
+            status=status,
+            config=config,
+            fingerprint=context.handle.fingerprint(),
+            issues_count=_count_by_severity(issues),
+            started_at=started_at,
+            finished_at=datetime.now(UTC),
+            error=error,
+            quality_score=quality_score,
+            reproducibility=ReproducibilityInfo(
+                datasentry_version=__version__,
+                detector_versions={r.detector_id: r.detector_version for r in runs},
+                seed=config.seed,
+                scanned_at=datetime.now(UTC),
+            ),
+        )
+        return scan_run, runs, issues
+
+    def _run_detector(
+        self, detector: Detector, context: DetectionContext, scan_run_id: str
+    ) -> DetectorRun:
+        started = time.perf_counter()
+        try:
+            if not detector.supports(context):
+                return DetectorRun(
+                    id=f"dr_{uuid.uuid4().hex[:12]}",
+                    scan_run_id=scan_run_id,
+                    detector_id=detector.detector_id,
+                    detector_version=detector.detector_version,
+                    status="skipped",
+                    rows_scanned=0,
+                    duration_ms=0,
+                    issues_candidates=0,
+                )
+            candidates = detector.detect(context)
+            return DetectorRun(
+                id=f"dr_{uuid.uuid4().hex[:12]}",
+                scan_run_id=scan_run_id,
+                detector_id=detector.detector_id,
+                detector_version=detector.detector_version,
+                status="completed",
+                rows_scanned=context.handle.count_rows(),
+                duration_ms=int((time.perf_counter() - started) * 1000),
+                issues_candidates=len(candidates),
+            )
+        except Exception as exc:  # 单检测器失败不中断整次扫描
+            return DetectorRun(
+                id=f"dr_{uuid.uuid4().hex[:12]}",
+                scan_run_id=scan_run_id,
+                detector_id=detector.detector_id,
+                detector_version=detector.detector_version,
+                status="failed",
+                rows_scanned=0,
+                duration_ms=int((time.perf_counter() - started) * 1000),
+                issues_candidates=0,
+                error=str(exc),
+            )