@kernel-sig/console 0.1.0

package/backend/app/services/classification_service.py

@@ -0,0 +1,658 @@
+"""分类服务。
+
+职责：把 domain.classification 的纯规则结果落库，并维护"人工覆盖优先"的契约。
+
+三档优先级的处理是这套机制的核心：
+1. 规则命中 → 直接写入，置信度由规则给出
+2. 规则未命中 → 记为 unknown，由 AI 任务补判（见 ai_service）
+3. 人工覆盖 → ``is_override`` 置位，此后任何自动任务都不再改写
+
+第 3 条不是可选优化。维护者手动纠正过一次分类，下次同步又被改回去，
+这套分类就没人会再信任。
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Sequence
+from datetime import UTC, datetime
+
+import structlog
+from sqlalchemy import Select, func, or_, select
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.domain import classification as domain
+from app.models.ai import AIAnalysis, AITask, AnalysisStatus
+from app.models.classification import (
+    Classification,
+    ClassificationSource,
+    PRKind,
+    SubjectType,
+)
+from app.models.issue import Issue
+from app.models.pull_request import PRCommit, PRFile, PullRequest
+from app.models.repository import Repository
+
+logger = structlog.get_logger(__name__)
+
+# 分类结果与 PR 快照一起批量写入；一次同步可能带来上千条
+BATCH_SIZE = 500
+
+
+# ---------------------------------------------------------------------------
+# 结果构造（纯函数，便于单测）
+# ---------------------------------------------------------------------------
+
+
+def build_result(
+    *,
+    title: str,
+    body: str | None,
+    filenames: Sequence[str] = (),
+    commit_messages: Sequence[str] = (),
+) -> domain.ClassifyResult:
+    """综合标题、正文、提交信息与变更文件得到分类结果。
+
+    提交信息是这里最可靠的信号：openEuler 的补丁在提交信息末尾带
+    ``category:`` 与 ``<X> inclusion`` 自声明标注（实测覆盖率 97.7%），
+    比从标题猜关键词准确得多。但它只在详情同步完成后才有，
+    因此标题规则仍是必需的降级路径。
+
+    子系统归属优先取变更文件 —— 文件路径是客观事实，标题前缀是作者的自由表述。
+    """
+    result = domain.classify_by_rules(title, body or "", commit_messages)
+
+    primary, related = domain.derive_subsystem(list(filenames))
+    if primary is None:
+        primary = domain.normalize_subsystem(result.title_subsystem)
+    # 标题声明的子系统也补进相关列表：文件列表缺失时它是唯一线索，
+    # 文件列表存在时它代表作者意图，两者都值得保留
+    declared = domain.normalize_subsystem(result.title_subsystem)
+    if declared and declared != primary and declared not in related:
+        related = [declared, *related][:3]
+
+    result.subsystem = primary
+    result.related_subsystems = related
+    return result
+
+
+def _row(
+    repository_id: uuid.UUID,
+    subject_type: SubjectType,
+    subject_id: uuid.UUID,
+    result: domain.ClassifyResult,
+    *,
+    source: ClassificationSource = ClassificationSource.RULE,
+    rule_name: str | None = None,
+) -> dict:
+    return {
+        "id": uuid.uuid4(),
+        "repository_id": repository_id,
+        "subject_type": subject_type.value,
+        "subject_id": subject_id,
+        "kind": PRKind(result.kind.value).value,
+        "subsystem": result.subsystem,
+        "related_subsystems": result.related_subsystems or None,
+        "cve_ids": result.cve_ids or None,
+        "linked_issues": result.linked_issues or None,
+        "confidence": result.confidence,
+        "source": source.value,
+        "rule_name": rule_name if rule_name is not None else result.rule_name,
+        "reason": result.reason,
+        "is_override": False,
+    }
+
+
+# 冲突时允许改写的列。刻意不含 is_override / overridden_by ——
+# 自动任务不得自行解除人工覆盖标记。
+_UPSERT_COLUMNS = (
+    "kind",
+    "subsystem",
+    "related_subsystems",
+    "cve_ids",
+    "linked_issues",
+    "confidence",
+    "source",
+    "rule_name",
+    "reason",
+)
+
+
+async def _upsert(session: AsyncSession, rows: list[dict], *, preserve_ai: bool = False) -> int:
+    """批量写入分类结果。
+
+    两类记录不被改写：
+    - 人工覆盖（``is_override``）
+    - AI 判定，且本轮规则也没判出来（``preserve_ai=True`` 时）
+
+    第二条是必须的。规则每 10 分钟重算一次；若允许它把 AI 判出的结果
+    覆盖回 ``unknown``，那条记录下一轮又会被判定为"需要 AI 补判"，
+    于是模型被反复调用同一个对象 —— 一个持续烧钱且永不收敛的循环。
+
+    ``updated_at`` 只在语义列真的变了才推进。规则每 10 分钟全量重算一次，
+    无条件推进会让全部记录恒久处于"刚刚更新"，而分类列表正按这一列排序 ——
+    那样排序就退化成了随机序。
+    """
+    if not rows:
+        return 0
+
+    written = 0
+    for start in range(0, len(rows), BATCH_SIZE):
+        chunk = rows[start : start + BATCH_SIZE]
+        stmt = pg_insert(Classification).values(chunk)
+        condition = Classification.is_override.is_(False)
+        if preserve_ai:
+            condition = condition & (Classification.source != ClassificationSource.AI)
+        changed = or_(
+            *(
+                getattr(Classification, col).is_distinct_from(getattr(stmt.excluded, col))
+                for col in _UPSERT_COLUMNS
+            )
+        )
+        stmt = stmt.on_conflict_do_update(
+            constraint="uq_ksp_classification_subject",
+            set_={
+                **{col: getattr(stmt.excluded, col) for col in _UPSERT_COLUMNS},
+                "updated_at": func.now(),
+            },
+            where=condition & changed,
+        )
+        await session.execute(stmt)
+        written += len(chunk)
+    return written
+
+
+# ---------------------------------------------------------------------------
+# 分类执行
+# ---------------------------------------------------------------------------
+
+
+async def files_for_pulls(
+    session: AsyncSession, pull_ids: Sequence[uuid.UUID]
+) -> dict[uuid.UUID, list[str]]:
+    """批量取变更文件名，避免按 PR 逐条查询。"""
+    if not pull_ids:
+        return {}
+    stmt = select(PRFile.pull_request_id, PRFile.filename).where(
+        PRFile.pull_request_id.in_(list(pull_ids))
+    )
+    result: dict[uuid.UUID, list[str]] = {}
+    for pull_id, filename in (await session.execute(stmt)).all():
+        result.setdefault(pull_id, []).append(filename)
+    return result
+
+
+async def _write_split(session: AsyncSession, rows: list[dict]) -> int:
+    """按"规则是否判出来"分组写入。
+
+    规则命中时置信度是确定的（比如标题里有 CVE 编号），此时它可以推翻
+    一个先前由 AI 给出的判断；规则没命中时它只代表"我不知道"，
+    那就没有理由去覆盖 AI 已经给出的答案。
+    """
+    matched = [row for row in rows if row["kind"] != PRKind.UNKNOWN.value]
+    undecided = [row for row in rows if row["kind"] == PRKind.UNKNOWN.value]
+    written = await _upsert(session, matched)
+    written += await _upsert(session, undecided, preserve_ai=True)
+    return written
+
+
+async def commits_for_pulls(
+    session: AsyncSession, pull_ids: Sequence[uuid.UUID]
+) -> dict[uuid.UUID, list[str]]:
+    """批量取提交信息，供分类读取作者的自声明标注。"""
+    if not pull_ids:
+        return {}
+    stmt = select(PRCommit.pull_request_id, PRCommit.message).where(
+        PRCommit.pull_request_id.in_(list(pull_ids))
+    )
+    result: dict[uuid.UUID, list[str]] = {}
+    for pull_id, message in (await session.execute(stmt)).all():
+        result.setdefault(pull_id, []).append(message)
+    return result
+
+
+async def classify_pulls(
+    session: AsyncSession, repository: Repository, pulls: Sequence[PullRequest]
+) -> int:
+    """对一个仓库的一批 PR 执行规则分类，返回处理条数。
+
+    整体幂等：重复执行结果相同；人工覆盖与 AI 判定不会被打回。
+    """
+    if not pulls:
+        return 0
+
+    ids = [pull.id for pull in pulls]
+    files = await files_for_pulls(session, ids)
+    commits = await commits_for_pulls(session, ids)
+    rows = [
+        _row(
+            repository.id,
+            SubjectType.PULL_REQUEST,
+            pull.id,
+            build_result(
+                title=pull.title,
+                body=pull.body,
+                filenames=files.get(pull.id, ()),
+                commit_messages=commits.get(pull.id, ()),
+            ),
+        )
+        for pull in pulls
+    ]
+    written = await _write_split(session, rows)
+    logger.info(
+        "pulls_classified",
+        repository=repository.full_name,
+        count=written,
+    )
+    return written
+
+
+async def classify_issues(
+    session: AsyncSession, repository: Repository, issues: Sequence[Issue]
+) -> int:
+    """对 Issue 执行规则分类。
+
+    Issue 没有变更文件，子系统只能来自标题前缀或 Issue 类型。
+    """
+    if not issues:
+        return 0
+
+    rows = [
+        _row(
+            repository.id,
+            SubjectType.ISSUE,
+            issue.id,
+            build_result(title=issue.title, body=issue.body),
+        )
+        for issue in issues
+    ]
+    return await _write_split(session, rows)
+
+
+def normalize_ai_kind(kind: PRKind, reason: str | None) -> tuple[PRKind, str | None]:
+    """把模型给出的类型收敛到平台能够自证的取值。
+
+    只处理一种情况，但它是必然发生的：**模型判 cve 时给不出 CVE 编号**。
+    提示词把 cve 定义为"修复安全漏洞（出现 CVE 编号）"，而规则层只要在正文里
+    匹配到编号就直接判 cve —— 所以走到 AI 补判这一步的对象，正文里本来就没有
+    编号。实测到的两条正是如此：一条是给 ioctl 加权限检查的加固，一条是漏洞
+    影响评估，模型都凭"这是安全修复"判成了 cve。
+
+    两条路都不能走：留着这个 cve，版本汇总里对外报的「CVE 数」就混进了未编号
+    的安全加固，而那是要拿去汇报的数字；直接丢弃则会让它一直停在 unknown，
+    每轮补判都重新调用一次模型 —— AI 调用是本平台唯一按次计费的开销。
+    因此降为 bugfix（没有编号的安全修复，就是一次缺陷修复），并把这一步写进
+    理由里，让它可追溯而不是被悄悄改掉。
+    """
+    if kind is not PRKind.CVE:
+        return kind, reason
+    note = "模型判为安全修复但正文无 CVE 编号，按缺陷修复记录"
+    return PRKind.BUGFIX, f"{reason}（{note}）" if reason else note
+
+
+async def apply_ai_result(
+    session: AsyncSession,
+    *,
+    repository_id: uuid.UUID,
+    subject_type: SubjectType,
+    subject_id: uuid.UUID,
+    kind: str,
+    subsystem: str | None = None,
+    confidence: float = 0.0,
+    reason: str | None = None,
+) -> bool:
+    """写入 AI 判定结果。返回是否真的写入。
+
+    只有 AI 给出的类型合法时才写入 —— 模型偶尔会自造一个不在枚举里的取值，
+    直接入库会抛错，静默截断成 unknown 又会掩盖问题，因此显式拒绝并记录。
+    """
+    try:
+        resolved = PRKind(kind)
+    except ValueError:
+        logger.warning("ai_classification_invalid_kind", kind=kind, subject_id=str(subject_id))
+        return False
+
+    resolved, reason = normalize_ai_kind(resolved, reason)
+    normalized = domain.normalize_subsystem(subsystem)
+    row = {
+        "id": uuid.uuid4(),
+        "repository_id": repository_id,
+        "subject_type": subject_type.value,
+        "subject_id": subject_id,
+        "kind": resolved.value,
+        "subsystem": normalized,
+        "related_subsystems": None,
+        "cve_ids": None,
+        "linked_issues": None,
+        "confidence": confidence,
+        "source": ClassificationSource.AI.value,
+        "rule_name": "ai",
+        "reason": reason,
+        "is_override": False,
+    }
+    stmt = pg_insert(Classification).values(row)
+    stmt = stmt.on_conflict_do_update(
+        constraint="uq_ksp_classification_subject",
+        set_={col: getattr(stmt.excluded, col) for col in _UPSERT_COLUMNS},
+        where=Classification.is_override.is_(False),
+    )
+    await session.execute(stmt)
+    return True
+
+
+# ---------------------------------------------------------------------------
+# 人工覆盖
+# ---------------------------------------------------------------------------
+
+
+async def override(
+    session: AsyncSession,
+    classification: Classification,
+    *,
+    kind: PRKind,
+    subsystem: str | None,
+    user_id: uuid.UUID,
+) -> Classification:
+    """人工指定分类。此后自动任务不再改写这条记录。"""
+    classification.kind = kind
+    classification.subsystem = subsystem
+    classification.source = ClassificationSource.MANUAL
+    classification.confidence = 1.0
+    classification.rule_name = "manual"
+    classification.reason = "人工指定"
+    classification.is_override = True
+    classification.overridden_by = user_id
+    classification.overridden_at = datetime.now(UTC)
+    await session.flush()
+    return classification
+
+
+async def clear_override(session: AsyncSession, classification: Classification) -> Classification:
+    """撤销人工覆盖，立刻交还给自动分类。
+
+    只清标记是不够的：留下的还是人工设定的那个类型，而规则重算最长要等
+    10 分钟才跑下一轮 —— 使用者点了「撤销」却看到类型没变，
+    只会以为这个按钮没生效。因此这里就地重跑一次规则。
+    """
+    classification.is_override = False
+    classification.overridden_by = None
+    classification.overridden_at = None
+    await session.flush()
+    await reclassify(session, classification)
+    return classification
+
+
+async def reclassify(session: AsyncSession, classification: Classification) -> Classification:
+    """重算单条记录，得出"自动流程会给的答案"。已被人工覆盖的记录不动。
+
+    自动流程的结论按 **规则优先、AI 兜底** 得出，这里必须复现同一条链：
+    规则判得出来就用规则，判不出来时回落到该对象已有的 AI 判定，
+    而不是一律写成 ``unknown``。
+
+    否则「撤销人工指定」会连带丢掉模型此前的结论，那条记录重新落回
+    待补判池、再被送去调用一次模型 —— 撤销一个手工纠正不该产生账单。
+    """
+    if classification.is_override:
+        return classification
+
+    subject_type = SubjectType(classification.subject_type)
+    if subject_type is SubjectType.PULL_REQUEST:
+        pull = await session.get(PullRequest, classification.subject_id)
+        if pull is None:
+            return classification
+        files = (await files_for_pulls(session, [pull.id])).get(pull.id, ())
+        commits = (await commits_for_pulls(session, [pull.id])).get(pull.id, ())
+        result = build_result(
+            title=pull.title,
+            body=pull.body,
+            filenames=files,
+            commit_messages=commits,
+        )
+    else:
+        issue = await session.get(Issue, classification.subject_id)
+        if issue is None:
+            return classification
+        result = build_result(title=issue.title, body=issue.body)
+
+    if result.kind is domain.Kind.UNKNOWN:
+        fallback = await _latest_ai_result(session, classification)
+        if fallback is not None:
+            _apply_ai_row(classification, fallback)
+            # 会话未开启 autoflush，必须显式落盘 ——
+            # 否则紧随其后的查询（如"待补判列表"）读到的还是旧值
+            await session.flush()
+            return classification
+
+    classification.kind = PRKind(result.kind.value)
+    classification.subsystem = result.subsystem
+    classification.related_subsystems = result.related_subsystems or None
+    classification.cve_ids = result.cve_ids or None
+    classification.linked_issues = result.linked_issues or None
+    classification.confidence = result.confidence
+    classification.source = ClassificationSource.RULE
+    classification.rule_name = result.rule_name
+    classification.reason = result.reason
+    await session.flush()
+    return classification
+
+
+async def _latest_ai_result(
+    session: AsyncSession, classification: Classification
+) -> AIAnalysis | None:
+    """该对象最近一次成功的 AI 类型判定。"""
+    stmt = (
+        select(AIAnalysis)
+        .where(
+            AIAnalysis.subject_type == classification.subject_type,
+            AIAnalysis.subject_id == classification.subject_id,
+            AIAnalysis.task == AITask.CLASSIFY,
+            AIAnalysis.status == AnalysisStatus.SUCCEEDED,
+            AIAnalysis.result.is_not(None),
+        )
+        .order_by(AIAnalysis.finished_at.desc())
+        .limit(1)
+    )
+    return await session.scalar(stmt)
+
+
+def _apply_ai_row(classification: Classification, analysis: AIAnalysis) -> Classification:
+    """把一条 AI 分析结果写回分类记录。模型自造的类型一律不采纳。"""
+    result = analysis.result or {}
+    try:
+        kind = PRKind(str(result.get("kind", "")))
+    except ValueError:
+        return classification
+
+    kind, reason = normalize_ai_kind(kind, result.get("reason"))
+    classification.kind = kind
+    classification.subsystem = domain.normalize_subsystem(result.get("subsystem"))
+    classification.confidence = float(result.get("confidence") or 0.0)
+    classification.source = ClassificationSource.AI
+    classification.rule_name = "ai"
+    classification.reason = reason
+    return classification
+
+
+# ---------------------------------------------------------------------------
+# 查询
+# ---------------------------------------------------------------------------
+
+
+async def get_classification(
+    session: AsyncSession, subject_type: SubjectType, subject_id: uuid.UUID
+) -> Classification | None:
+    stmt = select(Classification).where(
+        Classification.subject_type == subject_type,
+        Classification.subject_id == subject_id,
+    )
+    return await session.scalar(stmt)
+
+
+async def classifications_for(
+    session: AsyncSession,
+    subject_type: SubjectType,
+    subject_ids: Sequence[uuid.UUID],
+) -> dict[uuid.UUID, Classification]:
+    """批量取分类结果，供列表页一次性渲染，避免 N+1。"""
+    if not subject_ids:
+        return {}
+    stmt = select(Classification).where(
+        Classification.subject_type == subject_type,
+        Classification.subject_id.in_(list(subject_ids)),
+    )
+    return {row.subject_id: row for row in (await session.scalars(stmt)).all()}
+
+
+def _filtered(
+    stmt: Select,
+    *,
+    repository_id: uuid.UUID | None,
+    subject_type: SubjectType | None,
+    kind: PRKind | None,
+    subsystem: str | None,
+    source: ClassificationSource | None,
+    include_override_only: bool,
+) -> Select:
+    stmt = stmt.where(Classification.repository_id == repository_id) if repository_id else stmt
+    if subject_type is not None:
+        stmt = stmt.where(Classification.subject_type == subject_type)
+    if kind is not None:
+        stmt = stmt.where(Classification.kind == kind)
+    if subsystem:
+        stmt = stmt.where(Classification.subsystem == subsystem)
+    if source is not None:
+        stmt = stmt.where(Classification.source == source)
+    if include_override_only:
+        stmt = stmt.where(Classification.is_override.is_(True))
+    return stmt
+
+
+async def list_classifications(
+    session: AsyncSession,
+    *,
+    repository_id: uuid.UUID | None = None,
+    subject_type: SubjectType | None = None,
+    kind: PRKind | None = None,
+    subsystem: str | None = None,
+    source: ClassificationSource | None = None,
+    override_only: bool = False,
+    limit: int = 50,
+    offset: int = 0,
+) -> tuple[list[Classification], int]:
+    base = _filtered(
+        select(Classification),
+        repository_id=repository_id,
+        subject_type=subject_type,
+        kind=kind,
+        subsystem=subsystem,
+        source=source,
+        include_override_only=override_only,
+    )
+
+    count_stmt = _filtered(
+        select(func.count(Classification.id)),
+        repository_id=repository_id,
+        subject_type=subject_type,
+        kind=kind,
+        subsystem=subsystem,
+        source=source,
+        include_override_only=override_only,
+    )
+
+    stmt = base.order_by(Classification.updated_at.desc()).limit(limit).offset(offset)
+    rows = list((await session.scalars(stmt)).all())
+    total = await session.scalar(count_stmt) or 0
+    return rows, total
+
+
+async def kind_distribution(
+    session: AsyncSession,
+    repository_id: uuid.UUID,
+    *,
+    subject_type: SubjectType = SubjectType.PULL_REQUEST,
+) -> list[dict]:
+    """按类型统计。供仪表盘与筛选栏直接展示，无需再算。"""
+    stmt = (
+        select(Classification.kind, func.count())
+        .where(
+            Classification.repository_id == repository_id,
+            Classification.subject_type == subject_type,
+        )
+        .group_by(Classification.kind)
+        .order_by(func.count().desc())
+    )
+    return [{"kind": row[0].value, "count": row[1]} for row in (await session.execute(stmt)).all()]
+
+
+async def subsystem_distribution(
+    session: AsyncSession, repository_id: uuid.UUID, *, limit: int = 15
+) -> list[dict]:
+    """按子系统统计。未归类的不单列 —— 那是缺失信息，不是一类子系统。"""
+    stmt = (
+        select(Classification.subsystem, func.count())
+        .where(
+            Classification.repository_id == repository_id,
+            Classification.subsystem.is_not(None),
+        )
+        .group_by(Classification.subsystem)
+        .order_by(func.count().desc())
+        .limit(limit)
+    )
+    return [
+        {"subsystem": row[0], "label": domain.subsystem_label(row[0]), "count": row[1]}
+        for row in (await session.execute(stmt)).all()
+    ]
+
+
+async def pulls_missing_classification(
+    session: AsyncSession, repository_id: uuid.UUID, *, limit: int
+) -> list[PullRequest]:
+    """挑出尚未分类、或规则判为 unknown 的活动 PR，供 AI 补判。
+
+    已合并/已关闭的不再补判 —— 对它们做分类不产生任何可执行动作。
+    """
+    classified = select(Classification.subject_id).where(
+        Classification.subject_type == SubjectType.PULL_REQUEST,
+        Classification.kind != PRKind.UNKNOWN,
+    )
+    stmt = (
+        select(PullRequest)
+        .where(
+            PullRequest.repository_id == repository_id,
+            PullRequest.state == "open",
+            PullRequest.id.not_in(classified),
+        )
+        .order_by(PullRequest.atomgit_updated_at.desc())
+        .limit(limit)
+    )
+    return list((await session.scalars(stmt)).all())
+
+
+async def issues_missing_classification(
+    session: AsyncSession, repository_id: uuid.UUID, *, limit: int
+) -> list[Issue]:
+    """挑出尚未分类、或规则判为 unknown 的活动 Issue，供 AI 补判。
+
+    与 PR 那条同理，但 Issue 的未判定比例高得多：Issue 没有变更文件，
+    子系统与类别只能从标题与正文推断，规则能命中的比例因此低很多
+    （实测 2039 条 Issue 里 945 条未判定，占 46%）。
+
+    Issue 数量大（2000+），因此调用方要限量、低频地跑 ——
+    一轮几十条，慢慢补，不需要也不应该一次性判定完。
+    """
+    classified = select(Classification.subject_id).where(
+        Classification.subject_type == SubjectType.ISSUE,
+        Classification.kind != PRKind.UNKNOWN,
+    )
+    stmt = (
+        select(Issue)
+        .where(
+            Issue.repository_id == repository_id,
+            Issue.state == "open",
+            Issue.id.not_in(classified),
+        )
+        .order_by(Issue.atomgit_updated_at.desc())
+        .limit(limit)
+    )
+    return list((await session.scalars(stmt)).all())