@kernel-sig/console 0.1.0

package/backend/app/services/attention_queue.py

@@ -0,0 +1,451 @@
+"""关注队列的订阅设置与分组收敛。
+
+队列此前是**逐条**罗列：每个命中对象一行。实测 4780 条里，
+issue_stale 1755 + issue_unassigned 1259 占了 63%，CVE 相关 1004 条。
+那不是"需要关注"，那是"全部清单"—— 翻两页就会放弃的功能等于没做。
+
+收敛分两步，都在这里：
+
+1. **订阅**：规则可关、阈值可调、范围可限定（只看 PR / 只看 Issue）。
+   阈值写死在代码里的结果是没人用 —— 第一条不符合自己节奏的提醒
+   就会让人关掉整个队列。
+2. **分组**：一条规则聚合成一行，给出条数、最久未处理的、最要紧的几条样本，
+   以及可以点进去的筛选链接。463 条 cve_aging 变成一行"CVE 未推进 · 463 个"，
+   使用者据此判断要不要展开，而不是被迫逐条翻。
+
+按主题（子系统）细分只对高量规则做：十几条的规则再分组，
+只会把一屏能看完的东西摊成三屏。
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from sqlalchemy import Select, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.domain.attention import RULE_INFO, RULE_INFO_BY_KEY, Thresholds
+from app.models.attention import AttentionItem, AttentionSeverity
+from app.models.attention_settings import AttentionRuleSetting
+from app.models.classification import SubjectType
+from app.models.issue import Issue
+from app.models.pull_request import PullRequest
+
+# 高量规则按主题细分时，一个主题至少要有这么多条才单列，
+# 否则零散主题会把分组列表撑成原来那个样子
+THEME_MIN_COUNT = 5
+
+# 每组给出多少条样本
+SAMPLE_SIZE = 5
+
+# 严重程度排序。blocker 最前。
+SEVERITY_RANK = {
+    AttentionSeverity.BLOCKER.value: 0,
+    AttentionSeverity.CRITICAL.value: 1,
+    AttentionSeverity.WARNING.value: 2,
+    AttentionSeverity.INFO.value: 3,
+}
+
+
+@dataclass
+class RuleSettingView:
+    """一条规则的当前设置。界面据此渲染，不用自己拼默认值。"""
+
+    rule: str
+    label: str
+    meaning: str
+    action: str
+    subject: str
+    enabled: bool
+    days: int
+    default_days: int
+    subject_scope: str
+    high_volume: bool
+    open_count: int = 0
+    """当前未解决的条数。关掉一条规则前应该先看到它拦下了多少东西。"""
+
+
+async def load_settings(session: AsyncSession) -> list[RuleSettingView]:
+    """规则设置。DB 里没有记录的规则用领域层默认值。
+
+    不给每条规则预插一行默认记录：那样领域层改默认值时要写数据迁移，
+    而默认值本来就该由代码定义。
+    """
+    overrides = {
+        row.rule: row for row in (await session.scalars(select(AttentionRuleSetting))).all()
+    }
+
+    counts_rows = (
+        await session.execute(
+            select(AttentionItem.rule, func.count())
+            .where(AttentionItem.resolved_at.is_(None))
+            .group_by(AttentionItem.rule)
+        )
+    ).all()
+    counts = {
+        str(row[0].value if hasattr(row[0], "value") else row[0]): row[1] for row in counts_rows
+    }
+
+    defaults = Thresholds()
+    views: list[RuleSettingView] = []
+    for info in RULE_INFO:
+        override = overrides.get(info.rule.value)
+        default_days = int(getattr(defaults, info.threshold_field, info.default_days))
+        views.append(
+            RuleSettingView(
+                rule=info.rule.value,
+                label=info.label,
+                meaning=info.meaning,
+                action=info.action,
+                subject=info.subject,
+                enabled=override.enabled if override else True,
+                days=override.days if override and override.days is not None else default_days,
+                default_days=default_days,
+                subject_scope=override.subject_scope if override else "all",
+                high_volume=info.high_volume,
+                open_count=counts.get(info.rule.value, 0),
+            )
+        )
+    return views
+
+
+async def save_setting(
+    session: AsyncSession,
+    *,
+    rule: str,
+    enabled: bool | None = None,
+    days: int | None = None,
+    subject_scope: str | None = None,
+    user_id: uuid.UUID | None = None,
+) -> AttentionRuleSetting:
+    """写入或更新一条规则的订阅设置。"""
+    row = await session.scalar(
+        select(AttentionRuleSetting).where(AttentionRuleSetting.rule == rule)
+    )
+    if row is None:
+        row = AttentionRuleSetting(rule=rule)
+        session.add(row)
+
+    if enabled is not None:
+        row.enabled = enabled
+    if days is not None:
+        row.days = max(0, days)
+    if subject_scope is not None:
+        row.subject_scope = subject_scope
+
+    row.updated_by = user_id
+    # 设置只影响下一次重算：已生成的条目带着上一轮的阈值，
+    # 当场按新阈值过滤会让"条数"与"列表"对不上，看起来像 bug
+    row.effective_at = datetime.now(UTC)
+    await session.flush()
+    return row
+
+
+@dataclass
+class QueueSample:
+    number: int
+    title: str
+    subject_type: str
+    subject_id: str
+    url: str | None
+    severity: str
+    detail: str | None
+    age_days: int | None
+    """对象等待了多久。None 表示该规则不带时间信息。"""
+
+    item_id: str
+    """关注项自身的 id。认领作用于它，而不是作用于对象。"""
+
+    acknowledged_by: str | None
+    """认领人的 user id。null 表示无人认领。"""
+
+
+@dataclass
+class QueueTheme:
+    """主题细分。只对高量规则生成。"""
+
+    name: str
+    count: int
+    samples: list[QueueSample] = field(default_factory=list)
+
+
+@dataclass
+class QueueGroup:
+    """一条规则的聚合结果。队列按它渲染一行。"""
+
+    rule: str
+    label: str
+    meaning: str
+    action: str
+    subject: str
+    count: int
+    severity: str
+    oldest_days: int | None
+    samples: list[QueueSample] = field(default_factory=list)
+    themes: list[QueueTheme] = field(default_factory=list)
+    high_volume: bool = False
+
+    acknowledged_count: int = 0
+    """本组已被认领的条数。认领是逐条的动作，而分组是会收敛的视图 ——
+    被认领的那条未必落在样例里，所以数字单独统计，不能从样例里数。"""
+
+
+@dataclass
+class QueueOverview:
+    """队列的全貌。
+
+    分组与计数必须出自同一次查询、同一份订阅设置：分别算的话，
+    关掉一条规则后首页与队列页会显示两个不同的数字，
+    而这种不一致没法从任一页面上看出来。
+    """
+
+    groups: list[QueueGroup]
+    by_severity: dict[str, int]
+    total: int
+
+
+def _base_query(repository_id: uuid.UUID, enabled_rules: list[str]) -> Select:
+    return select(
+        AttentionItem.id,
+        AttentionItem.rule,
+        AttentionItem.severity,
+        AttentionItem.subject_type,
+        AttentionItem.subject_id,
+        AttentionItem.subject_number,
+        AttentionItem.subject_title,
+        AttentionItem.subject_url,
+        AttentionItem.detail,
+        AttentionItem.evidence,
+        AttentionItem.acknowledged_by,
+        AttentionItem.first_detected_at,
+    ).where(
+        AttentionItem.repository_id == repository_id,
+        AttentionItem.resolved_at.is_(None),
+        AttentionItem.rule.in_(enabled_rules),
+    )
+
+
+async def build_queue(
+    session: AsyncSession,
+    repository_id: uuid.UUID,
+    *,
+    scope: str | None = None,
+) -> list[QueueGroup]:
+    """按订阅设置生成分组队列。"""
+    return (await build_overview(session, repository_id, scope=scope)).groups
+
+
+async def build_overview(
+    session: AsyncSession,
+    repository_id: uuid.UUID,
+    *,
+    scope: str | None = None,
+) -> QueueOverview:
+    """分组队列 + 与它同源的严重程度分布。
+
+    只查启用的规则 —— 关掉的规则不该出现在队列里，也不该出现在计数里。
+    否则"关掉"就只是视觉上的隐藏，使用者仍会被那个数字干扰。
+
+    分布按**条目**统计而不是按分组的严重程度累加：同一条规则会因时长
+    落到不同的档（CI 失败 3 天内是警告、之后是严重），拿分组里最严重的那档
+    代表全组，会把警告档的条目算进严重档。
+    """
+    settings = await load_settings(session)
+    by_rule = {item.rule: item for item in settings}
+    enabled = [
+        item.rule
+        for item in settings
+        if item.enabled and (scope is None or item.subject == scope or item.subject_scope == "all")
+    ]
+    if not enabled:
+        return QueueOverview(groups=[], by_severity={}, total=0)
+
+    stmt = _base_query(repository_id, enabled)
+    if scope == "pull_request":
+        stmt = stmt.where(AttentionItem.subject_type == SubjectType.PULL_REQUEST.value)
+    elif scope == "issue":
+        stmt = stmt.where(AttentionItem.subject_type == SubjectType.ISSUE.value)
+
+    rows = (await session.execute(stmt)).all()
+
+    # 主题名要额外查一次：PR 用目标分支，Issue 用类型。
+    # 不用子系统 —— 实测只有 20% 的 PR 和 2.6% 的 Issue 有子系统归属
+    # （内核路径大多不在映射表内），按它分组会得到一大片"未归类"，
+    # 等于没分组。分支是恒有且维护者本来就按它组织工作的维度。
+    themes = await _theme_names(session, [row.subject_id for row in rows])
+
+    grouped: dict[str, list] = defaultdict(list)
+    for row in rows:
+        grouped[str(row.rule.value if hasattr(row.rule, "value") else row.rule)].append(row)
+
+    groups: list[QueueGroup] = []
+    for rule, items in grouped.items():
+        info = RULE_INFO_BY_KEY.get(rule)
+        if info is None:
+            continue
+
+        samples = [
+            QueueSample(
+                number=row.subject_number,
+                title=row.subject_title,
+                subject_type=row.subject_type,
+                subject_id=str(row.subject_id),
+                url=row.subject_url,
+                severity=str(
+                    row.severity.value if hasattr(row.severity, "value") else row.severity
+                ),
+                detail=row.detail,
+                # 用规则自己算出的等待天数，而不是关注项的存在时长。
+                # 关注项是每轮重算时重新求值的，用它算年龄永远是 0 天 ——
+                # 使用者要问的是"这个 PR 等了多久"，不是"这条提醒存在了多久"。
+                age_days=age_days(row.evidence),
+                item_id=str(row.id),
+                acknowledged_by=str(row.acknowledged_by) if row.acknowledged_by else None,
+            )
+            for row in items
+        ]
+        samples.sort(key=lambda item: (SEVERITY_RANK.get(item.severity, 9), -(item.age_days or 0)))
+
+        severity = min(
+            (item.severity for item in samples),
+            key=lambda value: SEVERITY_RANK.get(value, 9),
+            default=AttentionSeverity.INFO.value,
+        )
+        ages = [item.age_days for item in samples if item.age_days is not None]
+        group = QueueGroup(
+            rule=rule,
+            label=info.label,
+            meaning=info.meaning,
+            action=info.action,
+            subject=info.subject,
+            count=len(items),
+            severity=severity,
+            oldest_days=max(ages) if ages else None,
+            samples=samples[:SAMPLE_SIZE],
+            high_volume=by_rule.get(rule).high_volume if by_rule.get(rule) else info.high_volume,
+            acknowledged_count=sum(1 for item in items if item.acknowledged_by is not None),
+        )
+        if group.high_volume:
+            group.themes = _themes(samples, themes)
+        groups.append(group)
+
+    # 分组排序：先看有没有必须处理的，再看是不是压着一堆
+    groups.sort(key=lambda item: (SEVERITY_RANK.get(item.severity, 9), -item.count))
+
+    by_severity: dict[str, int] = defaultdict(int)
+    for row in rows:
+        by_severity[
+            str(row.severity.value if hasattr(row.severity, "value") else row.severity)
+        ] += 1
+
+    return QueueOverview(groups=groups, by_severity=dict(by_severity), total=len(rows))
+
+
+# 各规则写进 evidence 的时间键不同，实测取值如下：
+#   review_sla_breach → waiting_days      issue_unassigned → days_open
+#   stale / ci_failed / merge_conflict / issue_stale → days_since_update
+#   cla_pending_long → days               cve_aging → hours（注意是小时）
+# 这张表是照着真实数据列的，不是照着一厢情愿的命名约定写的。
+_AGE_KEYS: tuple[tuple[str, int], ...] = (
+    ("waiting_days", 1),
+    ("days_open", 1),
+    ("days_since_update", 1),
+    ("days", 1),
+    ("hours", 24),
+)
+
+
+def age_days(evidence: object) -> int | None:
+    """条目对应的对象等了多久。
+
+    返回 None 表示这条规则**本来就不带时间信息**（如"缺关联 Issue"、
+    "已被 NACK"）—— 这时候显示"0 天"是错的，那会被读成"刚发生"。
+    界面据此显示"——"。
+
+    不用关注项的创建时间兜底：关注项是每轮重算时重新生成的，
+    用它算年龄永远接近 0，而使用者问的是"这个 PR 等了多久"。
+    """
+    if not isinstance(evidence, dict):
+        return None
+    for key, divisor in _AGE_KEYS:
+        value = evidence.get(key)
+        if isinstance(value, int | float):
+            return int(value / divisor)
+    return None
+
+
+def _themes(samples: list[QueueSample], names: dict[str, str]) -> list[QueueTheme]:
+    """把样本分主题。
+
+    只按**样本**分主题，不重查全量：用途是让使用者看出"这几百条集中在
+    哪几块"，而不是给出精确统计 —— 那件事在分面里有。
+    """
+    buckets: dict[str, list[QueueSample]] = defaultdict(list)
+    for sample in samples:
+        buckets[names.get(sample.subject_id) or "其他"].append(sample)
+
+    themes = [
+        QueueTheme(name=name, count=len(items), samples=items)
+        for name, items in buckets.items()
+        if len(items) >= THEME_MIN_COUNT or name != "其他"
+    ]
+    themes.sort(key=lambda item: -item.count)
+    return themes
+
+
+async def _theme_names(session: AsyncSession, subject_ids: list[uuid.UUID]) -> dict[str, str]:
+    """批量取主题名：PR 用目标分支，Issue 用类型。
+
+    两条查询而不是一条 union：两者的取值来源不同，混在一个 SQL 里
+    要靠 CASE 分支拼，可读性换不来任何好处。
+    """
+    if not subject_ids:
+        return {}
+
+    names: dict[str, str] = {}
+    branches = await session.execute(
+        select(PullRequest.id, PullRequest.target_branch).where(
+            PullRequest.id.in_(subject_ids), PullRequest.target_branch.is_not(None)
+        )
+    )
+    for row in branches.all():
+        names[str(row[0])] = row[1]
+
+    types = await session.execute(
+        select(Issue.id, Issue.issue_type).where(
+            Issue.id.in_(subject_ids), Issue.issue_type.is_not(None)
+        )
+    )
+    for row in types.all():
+        names.setdefault(str(row[0]), row[1])
+
+    return names
+
+
+@dataclass
+class QueueSummary:
+    """首页摘要用的口径。与队列同源，避免两处数字对不上。"""
+
+    total: int
+    group_count: int
+    by_severity: dict[str, int]
+    blocking: int
+    """必须动手的组数（blocker 档）。"""
+    top: list[QueueGroup]
+
+
+async def queue_summary(session: AsyncSession, repository_id: uuid.UUID) -> QueueSummary:
+    overview = await build_overview(session, repository_id)
+    return QueueSummary(
+        total=overview.total,
+        group_count=len(overview.groups),
+        by_severity=overview.by_severity,
+        blocking=sum(
+            1 for group in overview.groups if group.severity == AttentionSeverity.BLOCKER.value
+        ),
+        # 首页只放最要紧的三组：它是"瞥一眼"，不是清单
+        top=overview.groups[:3],
+    )