@kernel-sig/console 0.1.0

package/backend/app/models/pull_request.py

@@ -0,0 +1,288 @@
+"""Pull Request 及其关联数据。"""
+
+import uuid
+from datetime import datetime
+from enum import StrEnum
+
+from sqlalchemy import (
+    BigInteger,
+    Boolean,
+    DateTime,
+    Enum,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+    func,
+    true,
+)
+from sqlalchemy.dialects.postgresql import ARRAY, JSONB, UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.domain.review import EventType as ReviewEventType
+from app.models.base import Base, TimestampMixin
+
+
+class PRState(StrEnum):
+    OPEN = "open"
+    CLOSED = "closed"
+    MERGED = "merged"
+
+
+class PullRequest(Base, TimestampMixin):
+    __tablename__ = "ksp_pull_request"
+    __table_args__ = (
+        UniqueConstraint("repository_id", "number", name="uq_ksp_pull_request_repo_number"),
+        Index("ix_ksp_pull_request_repo_state_updated", "repository_id", "state", "updated_at"),
+        Index("ix_ksp_pull_request_label_names", "label_names", postgresql_using="gin"),
+        Index("ix_ksp_pull_request_repo_synced", "repository_id", "detail_synced_at"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    repository_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("ksp_repository.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    number: Mapped[int] = mapped_column(Integer, nullable=False)
+
+    title: Mapped[str] = mapped_column(Text, nullable=False)
+    body: Mapped[str | None] = mapped_column(Text, nullable=True)
+    state: Mapped[PRState] = mapped_column(
+        Enum(PRState, name="pull_state", values_callable=lambda e: [m.value for m in e]),
+        nullable=False,
+        index=True,
+    )
+    draft: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+
+    author_login: Mapped[str | None] = mapped_column(String(128), nullable=True, index=True)
+    author_name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    author_avatar_url: Mapped[str | None] = mapped_column(String(512), nullable=True)
+
+    source_branch: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    target_branch: Mapped[str | None] = mapped_column(String(255), nullable=True, index=True)
+
+    # 原始标签快照 + 便于 GIN 索引查询的扁平数组
+    labels: Mapped[list | None] = mapped_column(JSONB, nullable=True)
+    label_names: Mapped[list[str] | None] = mapped_column(ARRAY(Text), nullable=True)
+
+    added_lines: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    removed_lines: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    changed_files: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    # AtomGit 的 notes 字段直接给出评论数，是变更检测的信号之一
+    comments_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+    mergeable: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    merge_conflict: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    merge_check_detail: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+
+    # 门禁阶段。由 label_names 推导后落库，属于刻意的反规范化：
+    # 列表页需要按"待评审/可合入"筛选并排序，1000+ 条记录不可能在应用层
+    # 逐条推导再分页。每次列表同步时重算，来源与推导逻辑唯一（domain.review）。
+    gate_stage: Mapped[str] = mapped_column(
+        String(32), nullable=False, default="cla_pending", server_default="cla_pending", index=True
+    )
+
+    atomgit_created_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    atomgit_updated_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    merged_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    closed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    html_url: Mapped[str | None] = mapped_column(String(512), nullable=True)
+
+    first_seen_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    last_synced_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    detail_synced_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    # 内容变化后置位，详情同步处理后清除。
+    # 不能用「last_synced_at > detail_synced_at」代替 —— 列表同步每次都更新
+    # last_synced_at，会让全部 PR 恒久处于"待拉详情"状态，每轮产生数千次请求。
+    needs_detail: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True, server_default=true()
+    )
+    # 内容指纹：只有变化才需要重新触发 AI 分析
+    content_hash: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
+
+    def __repr__(self) -> str:
+        return f"<PullRequest #{self.number} {self.state.value}>"
+
+
+class PRCommit(Base):
+    """PR 包含的提交。序号对应补丁在 PR 中的顺序（0001、0002…）。"""
+
+    __tablename__ = "ksp_pr_commit"
+    __table_args__ = (UniqueConstraint("pull_request_id", "sha", name="uq_ksp_pr_commit_pr_sha"),)
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+    pull_request_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("ksp_pull_request.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    sha: Mapped[str] = mapped_column(String(64), nullable=False)
+    sequence: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+    subject: Mapped[str] = mapped_column(Text, nullable=False, default="")
+    message: Mapped[str] = mapped_column(Text, nullable=False, default="")
+    author_name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    author_email: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    committed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    # 补丁格式审查的落点：openEuler 要求 Signed-off-by 链完整
+    signed_off_bys: Mapped[list[str] | None] = mapped_column(JSONB, nullable=True)
+
+
+class PRFile(Base):
+    """PR 变更文件。patch 原文保留，供后续逐补丁审查与 backport 对比。"""
+
+    __tablename__ = "ksp_pr_file"
+    __table_args__ = (
+        UniqueConstraint("pull_request_id", "filename", name="uq_ksp_pr_file_pr_filename"),
+    )
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+    pull_request_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("ksp_pull_request.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    filename: Mapped[str] = mapped_column(Text, nullable=False)
+    status: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    additions: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    deletions: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+    # 内核仓库禁止提交二进制文件，此标记直接支撑该规则的自动判定
+    is_binary: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    too_large: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    diff: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+
+class PRComment(Base):
+    """PR 评论原文。
+
+    评论此前只被解析成评审事件就丢弃，界面上无从看到讨论内容。
+    但评审意见、维护者的提问、以及 openEuler 机器人自动产生的变更摘要
+    与代码审查结论都只存在于评论里，因此原文必须留存并展示。
+
+    以 AtomGit 的评论 id 为唯一键，重复同步不会产生重复行。
+    """
+
+    __tablename__ = "ksp_pr_comment"
+    __table_args__ = (
+        UniqueConstraint("pull_request_id", "comment_id", name="uq_ksp_pr_comment_identity"),
+        # 评论按时间正序展示，因此按 (PR, 上游创建时间) 建索引
+        Index("ix_ksp_pr_comment_pr_created", "pull_request_id", "atomgit_created_at"),
+    )
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+    pull_request_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("ksp_pull_request.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    # AtomGit 侧的评论 id。以字符串存储：上游 id 类型不稳定（实测有整数，
+    # 也有形如 "note_123" 的字符串），转成整数会在遇到后者时直接崩
+    comment_id: Mapped[str] = mapped_column(String(64), nullable=False)
+    # 行内评论会带上被评论的文件；整体评论为空
+    comment_type: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    discussion_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+
+    author_login: Mapped[str] = mapped_column(String(128), nullable=False, default="")
+    author_avatar_url: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    body: Mapped[str] = mapped_column(Text, nullable=False, default="")
+
+    atomgit_created_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    atomgit_updated_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    last_synced_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    def __repr__(self) -> str:
+        return f"<PRComment {self.comment_id} by={self.author_login}>"
+
+
+class ReviewEventSource(StrEnum):
+    LABEL = "label"
+    COMMENT = "comment"
+    WEBHOOK = "webhook"
+
+
+class ReviewEvent(Base):
+    """结构化的评审事件。
+
+    这是评审子系统的基石 —— AtomGit 把评审状态承载在标签与评论里，
+    必须解析成结构化事件，才能计算评审 SLA、评审人工作量与等待时长。
+
+    唯一约束保证幂等：重复同步不会产生重复事件。
+    """
+
+    __tablename__ = "ksp_review_event"
+    __table_args__ = (
+        UniqueConstraint(
+            "pull_request_id",
+            "event_type",
+            "actor_login",
+            "occurred_at",
+            name="uq_ksp_review_event_identity",
+        ),
+        Index("ix_ksp_review_event_pr_occurred", "pull_request_id", "occurred_at"),
+        Index("ix_ksp_review_event_actor_occurred", "actor_login", "occurred_at"),
+    )
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+    pull_request_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("ksp_pull_request.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+
+    event_type: Mapped[ReviewEventType] = mapped_column(
+        Enum(
+            ReviewEventType,
+            name="review_event_type",
+            values_callable=lambda e: [m.value for m in e],
+        ),
+        nullable=False,
+        index=True,
+    )
+    actor_login: Mapped[str] = mapped_column(String(128), nullable=False, default="", index=True)
+    # 若能匹配到平台用户则关联，用于归属评审工作量
+    actor_user_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("ksp_user.id", ondelete="SET NULL"), nullable=True
+    )
+
+    source: Mapped[ReviewEventSource] = mapped_column(
+        Enum(
+            ReviewEventSource,
+            name="review_event_source",
+            values_callable=lambda e: [m.value for m in e],
+        ),
+        nullable=False,
+    )
+    # 原始证据（标签名或评论片段），解析规则演进时可回溯
+    raw_payload: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    occurred_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+
+    def __repr__(self) -> str:
+        return f"<ReviewEvent {self.event_type.value} by={self.actor_login}>"

package/backend/app/models/repository.py

@@ -0,0 +1,196 @@
+"""纳管仓库与同步游标。"""
+
+import uuid
+from datetime import datetime
+from enum import StrEnum
+
+from sqlalchemy import (
+    BigInteger,
+    Boolean,
+    DateTime,
+    Enum,
+    ForeignKey,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+    func,
+)
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base, TimestampMixin
+
+DEFAULT_API_BASE_URL = "https://api.atomgit.com/api/v5"
+
+
+class Repository(Base, TimestampMixin):
+    __tablename__ = "ksp_repository"
+    __table_args__ = (UniqueConstraint("owner", "name", name="uq_ksp_repository_owner_name"),)
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    owner: Mapped[str] = mapped_column(String(128), nullable=False)
+    name: Mapped[str] = mapped_column(String(128), nullable=False)
+    display_name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    # 可配置：AtomGit 与 GitCode 共用后端，两者 token 通用
+    api_base_url: Mapped[str] = mapped_column(
+        String(255), nullable=False, default=DEFAULT_API_BASE_URL
+    )
+    credential_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("ksp_credential.id", ondelete="SET NULL"), nullable=True
+    )
+
+    default_branch: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    # 关注的分支，如 ["OLK-6.6", "OLK-5.10", "master"]
+    tracked_branches: Mapped[list | None] = mapped_column(JSONB, nullable=True)
+
+    sync_enabled: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    sync_interval_seconds: Mapped[int] = mapped_column(Integer, nullable=False, default=300)
+    # 首次同步回填的历史窗口（天）。全量回填 1000+ PR 会耗时过长，
+    # 故默认只回填近半年，其余由对账任务渐进补齐。
+    backfill_days: Mapped[int] = mapped_column(Integer, nullable=False, default=180)
+
+    # webhook 无签名头，改用 URL 路径内嵌随机密钥 + IP 白名单
+    webhook_secret: Mapped[str | None] = mapped_column(String(64), nullable=True, unique=True)
+
+    last_sync_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    last_sync_error: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    @property
+    def full_name(self) -> str:
+        return f"{self.owner}/{self.name}"
+
+    def __repr__(self) -> str:
+        return f"<Repository {self.full_name}>"
+
+
+class SyncResource(StrEnum):
+    PULLS = "pulls"
+    ISSUES = "issues"
+    LABELS = "labels"
+
+
+class SyncCursor(Base):
+    """每仓库每资源的同步水位。
+
+    用于增量同步：只处理 updated_at 晚于水位的对象。
+    """
+
+    __tablename__ = "ksp_sync_cursor"
+    __table_args__ = (
+        UniqueConstraint("repository_id", "resource", name="uq_ksp_sync_cursor_repo_resource"),
+    )
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+    repository_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("ksp_repository.id", ondelete="CASCADE"), nullable=False
+    )
+    resource: Mapped[SyncResource] = mapped_column(
+        Enum(
+            SyncResource,
+            name="sync_resource",
+            values_callable=lambda e: [m.value for m in e],
+        ),
+        nullable=False,
+    )
+
+    last_synced_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    last_seen_updated_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    total_seen: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    # 触发限流后的退避截止时间
+    backoff_until: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+
+class SyncStatus(StrEnum):
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    PARTIAL = "partial"
+
+
+class SyncTrigger(StrEnum):
+    SCHEDULED = "scheduled"
+    MANUAL = "manual"
+    WEBHOOK = "webhook"
+
+
+class SyncRun(Base):
+    """单次同步执行记录，支撑"同步健康度"面板。"""
+
+    __tablename__ = "ksp_sync_run"
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+    repository_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("ksp_repository.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    resource: Mapped[SyncResource] = mapped_column(
+        Enum(
+            SyncResource,
+            name="sync_resource",
+            values_callable=lambda e: [m.value for m in e],
+        ),
+        nullable=False,
+    )
+    trigger: Mapped[SyncTrigger] = mapped_column(
+        Enum(
+            SyncTrigger,
+            name="sync_trigger",
+            values_callable=lambda e: [m.value for m in e],
+        ),
+        nullable=False,
+        default=SyncTrigger.SCHEDULED,
+    )
+    status: Mapped[SyncStatus] = mapped_column(
+        Enum(
+            SyncStatus,
+            name="sync_status",
+            values_callable=lambda e: [m.value for m in e],
+        ),
+        nullable=False,
+        default=SyncStatus.RUNNING,
+    )
+
+    started_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False, index=True
+    )
+    finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    api_calls: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    items_fetched: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    items_created: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    items_updated: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    items_failed: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    @property
+    def duration_seconds(self) -> float | None:
+        if self.finished_at is None:
+            return None
+        return (self.finished_at - self.started_at).total_seconds()
+
+
+class WebhookDelivery(Base):
+    """Webhook 投递记录，以 delivery_id 为主键天然实现幂等。
+
+    重复投递在 INSERT 冲突时即被识别丢弃。
+    """
+
+    __tablename__ = "ksp_webhook_delivery"
+
+    delivery_id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    repository_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("ksp_repository.id", ondelete="CASCADE"), nullable=True
+    )
+    event: Mapped[str] = mapped_column(String(64), nullable=False)
+    recognized: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    received_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False, index=True
+    )
+    processed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

package/backend/app/models/sig.py

@@ -0,0 +1,194 @@
+"""SIG 成员与模块归属。
+
+三个来源，职责不同，都保留：
+
+- **成员名单**来自 ``sig/Kernel/sig-info.yaml`` —— openEuler 的机器可读 SIG
+  元数据文件，字段完整（姓名、邮箱、组织、两个平台账号），133 人。
+  它才是权威名单：谁有权评审、谁能合入、谁负责哪个分支，以它为准。
+- ``sig/Kernel/README.md`` 与 ``committers.md`` 是给人看的文档，
+  README 只列了 4 位维护者的展示名，committers.md 是模块分工表。
+  两者只在 yaml 取不到时兜底，不作为主来源。
+- **模块归属**仍来自 ``committers.md`` 的"模块 / 文件 / Committer"表 ——
+  yaml 里没有内核路径信息。它把路径映射到具体的 Committer，
+  是"这个 PR 该找谁看"的依据。
+
+成员表刻意只存名单，不存贡献统计。贡献统计按需从 PR / 评审事件里现算 ——
+存下来就要考虑失效，而名单是低频变化的，两者寿命不同，混在一张表里
+会让一个每天变的数字和一份权威名单互相拖累。
+"""
+
+import uuid
+from datetime import datetime
+from enum import StrEnum
+
+from sqlalchemy import (
+    Boolean,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.dialects.postgresql import ARRAY, UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base, TimestampMixin
+
+
+class MemberRole(StrEnum):
+    MAINTAINER = "maintainer"
+    COMMITTER = "committer"
+    CONTRIBUTOR = "contributor"
+
+
+class MemberSource(StrEnum):
+    """名单来源。
+
+    ``SIG_INFO`` 是权威来源（openEuler 的机器可读 SIG 元数据文件），
+    其余两个是给人看的文档，只在 yaml 取不到时兜底。
+    """
+
+    SIG_INFO = "sig_info_yaml"
+    README = "sig_readme"
+    COMMITTERS = "committers_md"
+    MANUAL = "manual"
+
+
+class SIGMember(Base, TimestampMixin):
+    __tablename__ = "ksp_sig_member"
+    __table_args__ = (
+        Index("ix_ksp_sig_member_role", "role"),
+        Index("ix_ksp_sig_member_atomgit", "atomgit_id"),
+        Index("ix_ksp_sig_member_email", "email"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+
+    name: Mapped[str] = mapped_column(String(128), nullable=False)
+
+    # 三个平台的登录名。同一人往往只在一部分平台上留名，实测 atomgit_id
+    # 覆盖率 86%、gitee_id 88%、github_id 0%，因此都不能设为必填。
+    atomgit_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    gitee_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    github_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    email: Mapped[str | None] = mapped_column(String(255), nullable=True)
+
+    role: Mapped[str] = mapped_column(
+        String(16), nullable=False, default=MemberRole.COMMITTER.value
+    )
+    """最高角色。一个人可以同时是维护者与某仓库的 committer。"""
+
+    roles: Mapped[list[str] | None] = mapped_column(ARRAY(Text), nullable=True)
+    """全部角色。只存最高角色会丢掉"他还是某仓库的 committer"这一信息。"""
+
+    org: Mapped[str | None] = mapped_column(String(128), nullable=True)
+
+    repositories: Mapped[list[str] | None] = mapped_column(ARRAY(Text), nullable=True)
+    """参与的仓库。"""
+
+    admin_repositories: Mapped[list[str] | None] = mapped_column(ARRAY(Text), nullable=True)
+    """担任 repo_admin 的仓库。"""
+
+    kept_branches: Mapped[list[str] | None] = mapped_column(ARRAY(Text), nullable=True)
+    """作为 keeper 负责的分支。分支页据此显示"该分支谁负责"。"""
+
+    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    source: Mapped[str] = mapped_column(
+        String(24), nullable=False, default=MemberSource.COMMITTERS.value
+    )
+    source_url: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    last_synced_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    def __repr__(self) -> str:
+        return f"<SIGMember {self.name} {self.role}>"
+
+
+class SubsystemOwner(Base, TimestampMixin):
+    """模块 → Committer 的映射，来自 ``committers.md``。
+
+    ``paths`` 是内核路径前缀。上游用 ``mm/``、``net/bpf/`` 这类前缀，
+    也用过 ``kernel/*``、``include/linux/kvm*`` 这类通配写法，
+    因此按前缀匹配、不做 glob 展开 —— 展开需要完整文件树，
+    而这里只需要回答"改了这个文件该找谁"。
+
+    唯一键是 **(章节, 模块)** 而不是模块名：模块名只在章节内唯一，
+    实测 ``smmu`` 在架构与驱动两个章节下各有一行，指的是两批人。
+    用模块名做键会让第二行撞约束，整份名单一起同步失败。
+    """
+
+    __tablename__ = "ksp_subsystem_owner"
+    __table_args__ = (
+        UniqueConstraint("section", "module", name="uq_ksp_subsystem_owner_section_module"),
+        Index("ix_ksp_subsystem_owner_paths", "paths", postgresql_using="gin"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+
+    module: Mapped[str] = mapped_column(String(64), nullable=False)
+    section: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    """committers.md 里的二级标题，如 ``kernel core``、``drivers``。"""
+
+    paths: Mapped[list[str] | None] = mapped_column(ARRAY(Text), nullable=True)
+    committer_logins: Mapped[list[str] | None] = mapped_column(ARRAY(Text), nullable=True)
+    """上游写的评审人 handle（人写的展示名）。与 ``SIGMember.atomgit_id`` 未必字面相同。"""
+
+    sequence: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    source_url: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    last_synced_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    def __repr__(self) -> str:
+        return f"<SubsystemOwner {self.section}/{self.module}>"
+
+
+class ReleaseBranch(Base, TimestampMixin):
+    """分支/版本登记表。
+
+    能从分支名推出来的（产品线、系列、SP 序号）由 ``domain.release`` 算，
+    这张表只存**推不出来的事实**：上游基线、生命周期、维护策略说明。
+    猜这些字段会造出一个看起来权威实际是编的值，所以留给人填。
+
+    **一个分支属于一个仓库**，这条是 sig-info.yaml 明写的
+    （``repo_branch`` 段里每条都带 ``repo``），只是早先写入时被丢掉了 ——
+    结果这张表成了全局表，纳管第二个仓库时，OLK-6.6 会出现在
+    src-openeuler/kernel 的分支页上。同名分支在两边都存在
+    （master、openEuler-24.03-LTS-SP4 都是），所以这一列不是可有可无的。
+    """
+
+    __tablename__ = "ksp_release_branch"
+    __table_args__ = (
+        UniqueConstraint("repository_id", "name", name="uq_ksp_release_branch_repo_name"),
+        Index("ix_ksp_release_branch_keepers", "keepers", postgresql_using="gin"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+
+    repository_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("ksp_repository.id", ondelete="CASCADE"), nullable=True
+    )
+    """所属仓库。为空表示上游还没说明它属于哪个仓库（或那个仓库尚未纳管）。"""
+
+    name: Mapped[str] = mapped_column(String(64), nullable=False)
+    """规范化后的分支名，与 ``domain.release.normalize_branch_name`` 一致。"""
+
+    aliases: Mapped[list[str] | None] = mapped_column(ARRAY(Text), nullable=True)
+    """上游出现过的其他写法（如 ``openEuler-24.03-LTS_SP1``）。
+    库里的 ``target_branch`` 存的是原始名，靠这个列表才能把两边对上。"""
+
+    kind: Mapped[str] = mapped_column(String(16), nullable=False, default="other")
+    series: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    sp: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    upstream_base: Mapped[str | None] = mapped_column(String(16), nullable=True)
+
+    state: Mapped[str] = mapped_column(String(16), nullable=False, default="active")
+    """active / maintenance / eol。"""
+
+    note: Mapped[str | None] = mapped_column(Text, nullable=True)
+    """维护策略说明。来自 sig/Kernel/README.md 的人工摘要。"""
+
+    keepers: Mapped[list[str] | None] = mapped_column(ARRAY(Text), nullable=True)
+    """分支负责人账号，来自 sig-info.yaml 的 branches 段。"""
+
+    def __repr__(self) -> str:
+        return f"<ReleaseBranch {self.name} {self.state}>"