@kernel-sig/console 0.1.0

package/backend/app/middleware/request_context.py

@@ -0,0 +1,42 @@
+"""请求上下文：注入 request_id，绑定日志上下文，回写耗时头。"""
+
+import time
+import uuid
+
+import structlog
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+REQUEST_ID_HEADER = "X-Request-ID"
+
+
+class RequestContextMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        request_id = request.headers.get(REQUEST_ID_HEADER) or uuid.uuid4().hex
+        request.state.request_id = request_id
+
+        structlog.contextvars.clear_contextvars()
+        structlog.contextvars.bind_contextvars(
+            request_id=request_id,
+            method=request.method,
+            path=request.url.path,
+        )
+
+        started = time.perf_counter()
+        try:
+            response = await call_next(request)
+        finally:
+            structlog.contextvars.unbind_contextvars("method", "path")
+
+        duration_ms = (time.perf_counter() - started) * 1000
+        response.headers[REQUEST_ID_HEADER] = request_id
+        response.headers["X-Response-Time-MS"] = f"{duration_ms:.1f}"
+
+        structlog.get_logger(__name__).info(
+            "http_request",
+            status_code=response.status_code,
+            duration_ms=round(duration_ms, 1),
+        )
+        structlog.contextvars.clear_contextvars()
+        return response

package/backend/app/models/__init__.py

@@ -0,0 +1,112 @@
+"""ORM 模型集中导出。
+
+Alembic 的 autogenerate 依赖此模块导入全部模型，否则新表不会被检测到。
+"""
+
+from app.models.ai import (
+    AIAnalysis,
+    AIProviderKind,
+    AITask,
+    AnalysisStatus,
+    LLMProvider,
+    PromptTemplate,
+    TaskRouting,
+)
+from app.models.attention import AttentionItem, AttentionRule, AttentionSeverity
+from app.models.attention_settings import AttentionRuleSetting
+from app.models.audit import AuditLog, AuditResult
+from app.models.base import Base, TimestampMixin
+from app.models.classification import (
+    Classification,
+    ClassificationSource,
+    LabelSyncState,
+    PRKind,
+    SubjectType,
+)
+from app.models.credential import Credential, CredentialKind
+from app.models.issue import Issue, IssueLinkSource, IssueType, PRIssueLink
+from app.models.meeting import (
+    Meeting,
+    MeetingAgenda,
+    MeetingStatus,
+    ReleaseReport,
+    ReleaseReportPatch,
+)
+from app.models.pull_request import (
+    PRComment,
+    PRCommit,
+    PRFile,
+    PRState,
+    PullRequest,
+    ReviewEvent,
+    ReviewEventSource,
+    ReviewEventType,
+)
+from app.models.repository import (
+    DEFAULT_API_BASE_URL,
+    Repository,
+    SyncCursor,
+    SyncResource,
+    SyncRun,
+    SyncStatus,
+    SyncTrigger,
+    WebhookDelivery,
+)
+from app.models.sig import MemberRole, MemberSource, ReleaseBranch, SIGMember, SubsystemOwner
+from app.models.user import User
+
+__all__ = [
+    "DEFAULT_API_BASE_URL",
+    "AIAnalysis",
+    "AIProviderKind",
+    "AITask",
+    "AnalysisStatus",
+    "AttentionItem",
+    "AttentionRule",
+    "AttentionRuleSetting",
+    "AttentionSeverity",
+    "AuditLog",
+    "AuditResult",
+    "Base",
+    "Classification",
+    "ClassificationSource",
+    "Credential",
+    "CredentialKind",
+    "Issue",
+    "IssueLinkSource",
+    "IssueType",
+    "LLMProvider",
+    "LabelSyncState",
+    "Meeting",
+    "MeetingAgenda",
+    "MeetingStatus",
+    "MemberRole",
+    "MemberSource",
+    "PRComment",
+    "PRCommit",
+    "PRFile",
+    "PRIssueLink",
+    "PRKind",
+    "PRState",
+    "PromptTemplate",
+    "PullRequest",
+    "ReleaseBranch",
+    "ReleaseReport",
+    "ReleaseReportPatch",
+    "Repository",
+    "ReviewEvent",
+    "ReviewEventSource",
+    "ReviewEventType",
+    "SIGMember",
+    "SubjectType",
+    "SubsystemOwner",
+    "SyncCursor",
+    "SyncResource",
+    "SyncRun",
+    "SyncStatus",
+    "SyncTrigger",
+    "TaskRouting",
+    "TimestampMixin",
+    "User",
+    "WebhookDelivery",
+]

package/backend/app/models/ai.py

@@ -0,0 +1,214 @@
+"""AI 相关模型：模型配置、任务路由、Prompt 模板、分析结果。"""
+
+import uuid
+from datetime import datetime
+from enum import StrEnum
+
+from sqlalchemy import (
+    Boolean,
+    DateTime,
+    Enum,
+    Float,
+    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
+
+
+class AIProviderKind(StrEnum):
+    """目前统一走 OpenAI 兼容协议，保留字段以便后续接入其他协议。"""
+
+    OPENAI_COMPATIBLE = "openai_compatible"
+
+
+class AITask(StrEnum):
+    """分析任务类型。取值同时用于任务路由配置的键。"""
+
+    CLASSIFY = "classify"
+    SUMMARIZE = "summarize"
+    RISK_REVIEW = "risk_review"
+    BACKPORT_VERIFY = "backport_verify"
+
+
+class AnalysisStatus(StrEnum):
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+
+
+class LLMProvider(Base, TimestampMixin):
+    """一个可用的模型端点。
+
+    按任务配置不同档位是刻意的：分类这类轻任务用便宜模型，
+    代码风险审查才用强模型。全部走大模型会让成本失控。
+    """
+
+    __tablename__ = "ksp_llm_provider"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    name: Mapped[str] = mapped_column(String(64), nullable=False, unique=True)
+    kind: Mapped[AIProviderKind] = mapped_column(
+        Enum(
+            AIProviderKind,
+            name="ai_provider_kind",
+            values_callable=lambda e: [m.value for m in e],
+        ),
+        nullable=False,
+        default=AIProviderKind.OPENAI_COMPATIBLE,
+    )
+
+    base_url: Mapped[str] = mapped_column(String(255), nullable=False)
+    # 指向凭据表，明文只在调用时解密
+    credential_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("ksp_credential.id", ondelete="SET NULL"), nullable=True
+    )
+    model: Mapped[str] = mapped_column(String(128), nullable=False)
+
+    temperature: Mapped[float] = mapped_column(Float, nullable=False, default=0.1)
+    max_tokens: Mapped[int] = mapped_column(Integer, nullable=False, default=4096)
+    timeout_seconds: Mapped[int] = mapped_column(Integer, nullable=False, default=180)
+
+    enabled: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    is_default: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+
+    last_used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    last_error: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    def __repr__(self) -> str:
+        return f"<LLMProvider {self.name} model={self.model}>"
+
+
+class TaskRouting(Base, TimestampMixin):
+    """任务 → 模型的路由。
+
+    没有为某任务配置时回落到 is_default 的 provider，
+    保证"刚部署还没配路由"时系统仍能工作。
+    """
+
+    __tablename__ = "ksp_task_routing"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    task: Mapped[AITask] = mapped_column(
+        Enum(AITask, name="ai_task", values_callable=lambda e: [m.value for m in e]),
+        nullable=False,
+        unique=True,
+    )
+    provider_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("ksp_llm_provider.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    fallback_provider_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("ksp_llm_provider.id", ondelete="SET NULL"), nullable=True
+    )
+    system_prompt: Mapped[str | None] = mapped_column(Text, nullable=True)
+    enabled: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+
+
+class AIAnalysis(Base):
+    """一次分析的结果。
+
+    input_hash 用于幂等：内容没变就不重复调用模型 ——
+    AI 调用是这套系统里唯一按次计费的部分。
+    """
+
+    __tablename__ = "ksp_ai_analysis"
+    __table_args__ = (
+        UniqueConstraint(
+            "subject_type", "subject_id", "task", name="uq_ksp_ai_analysis_subject_task"
+        ),
+    )
+
+    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,
+    )
+    subject_type: Mapped[str] = mapped_column(String(32), nullable=False)
+    subject_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), nullable=False, index=True)
+
+    task: Mapped[AITask] = mapped_column(
+        Enum(AITask, name="ai_task", values_callable=lambda e: [m.value for m in e]),
+        nullable=False,
+        index=True,
+    )
+    status: Mapped[AnalysisStatus] = mapped_column(
+        Enum(
+            AnalysisStatus,
+            name="ai_analysis_status",
+            values_callable=lambda e: [m.value for m in e],
+        ),
+        nullable=False,
+        default=AnalysisStatus.PENDING,
+        index=True,
+    )
+
+    provider_name: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    model: Mapped[str | None] = mapped_column(String(128), nullable=True)
+
+    # 输入指纹：内容未变则跳过重复分析
+    input_hash: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
+    prompt_tokens: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    completion_tokens: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+    result: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    # 原始响应保留供审计与调试，排查"模型到底说了什么"时是唯一依据
+    raw_response: Mapped[str | None] = mapped_column(Text, nullable=True)
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    triggered_by: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("ksp_user.id", ondelete="SET NULL"), nullable=True
+    )
+    started_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False, index=True
+    )
+
+    @property
+    def duration_seconds(self) -> float | None:
+        if self.started_at is None or self.finished_at is None:
+            return None
+        return (self.finished_at - self.started_at).total_seconds()
+
+    @property
+    def total_tokens(self) -> int:
+        return self.prompt_tokens + self.completion_tokens
+
+
+class PromptTemplate(Base, TimestampMixin):
+    """领域 Prompt 模板。
+
+    版本化以支持"同一分析用不同 Prompt 重跑对比"。
+    内置模板从代码加载，此处保存的是人工调整后的覆盖版本。
+    """
+
+    __tablename__ = "ksp_prompt_template"
+    __table_args__ = (UniqueConstraint("task", "version", name="uq_ksp_prompt_task_version"),)
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    task: Mapped[AITask] = mapped_column(
+        Enum(AITask, name="ai_task", values_callable=lambda e: [m.value for m in e]),
+        nullable=False,
+        index=True,
+    )
+    name: Mapped[str] = mapped_column(String(128), nullable=False)
+    version: Mapped[int] = mapped_column(Integer, nullable=False, default=1)
+
+    system_prompt: Mapped[str] = mapped_column(Text, nullable=False)
+    user_template: Mapped[str] = mapped_column(Text, nullable=False)
+
+    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    created_by: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("ksp_user.id", ondelete="SET NULL"), nullable=True
+    )

package/backend/app/models/attention.py

@@ -0,0 +1,131 @@
+"""关注项。
+
+跟踪子系统的输出：把散落在各个 PR/Issue 上的问题收敛成一份可认领的待办。
+维护者不需要逐条翻 PR 才能发现"这个已经两周没人看了"。
+"""
+
+import uuid
+from datetime import datetime
+from enum import StrEnum
+
+from sqlalchemy import (
+    BigInteger,
+    DateTime,
+    Enum,
+    ForeignKey,
+    Index,
+    String,
+    Text,
+    UniqueConstraint,
+    func,
+)
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base
+
+
+class AttentionSeverity(StrEnum):
+    BLOCKER = "blocker"  # 必须处理才能推进
+    CRITICAL = "critical"
+    WARNING = "warning"
+    INFO = "info"
+
+
+class AttentionRule(StrEnum):
+    """内置规则。
+
+    注意：规则的权威定义在领域层（``app.domain.attention.Rule``），
+    此处保持一致 —— 同一概念两处各写一份必然漂移，
+    表现为"规则算出的值写不进数据库"。
+    """
+
+    STALE = "stale"
+    REVIEW_SLA_BREACH = "review_sla_breach"
+    CI_FAILED = "ci_failed"
+    MERGE_CONFLICT = "merge_conflict"
+    NEEDS_ISSUE = "needs_issue"
+    CLA_DENIED = "cla_denied"
+    CLA_PENDING_LONG = "cla_pending_long"
+    REJECTED = "rejected"
+    BINARY_FILE = "binary_file"
+    MISSING_SIGNED_OFF = "missing_signed_off"
+    CVE_AGING = "cve_aging"
+    ISSUE_UNASSIGNED = "issue_unassigned"
+    ISSUE_STALE = "issue_stale"
+
+
+class AttentionItem(Base):
+    """一条待处理事项。
+
+    生命周期：每次 compute_attention 重新求值 ——
+    未解决的保留 first_detected_at 并刷新 detail；
+    已解决的置 resolved_at；已认领的不再重复提示。
+    """
+
+    __tablename__ = "ksp_attention_item"
+    __table_args__ = (
+        UniqueConstraint(
+            "subject_type", "subject_id", "rule", name="uq_ksp_attention_subject_rule"
+        ),
+        Index("ix_ksp_attention_open", "resolved_at", "severity"),
+    )
+
+    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,
+    )
+
+    subject_type: Mapped[str] = mapped_column(String(32), nullable=False)
+    subject_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), nullable=False, index=True)
+    # 冗余一份编号与标题，让关注队列无需联表即可渲染
+    subject_number: Mapped[int] = mapped_column(BigInteger, nullable=False)
+    subject_title: Mapped[str] = mapped_column(Text, nullable=False, default="")
+    subject_url: Mapped[str | None] = mapped_column(String(512), nullable=True)
+
+    rule: Mapped[AttentionRule] = mapped_column(
+        Enum(
+            AttentionRule,
+            name="attention_rule",
+            values_callable=lambda e: [m.value for m in e],
+        ),
+        nullable=False,
+        index=True,
+    )
+    severity: Mapped[AttentionSeverity] = mapped_column(
+        Enum(
+            AttentionSeverity,
+            name="attention_severity",
+            values_callable=lambda e: [m.value for m in e],
+        ),
+        nullable=False,
+        index=True,
+    )
+
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    detail: Mapped[str | None] = mapped_column(Text, nullable=True)
+    # 规则求值时的原始数据，便于解释"为什么判定为超期"
+    evidence: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+
+    first_detected_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    last_evaluated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    resolved_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    acknowledged_by: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("ksp_user.id", ondelete="SET NULL"), nullable=True
+    )
+    acknowledged_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    @property
+    def is_open(self) -> bool:
+        return self.resolved_at is None
+
+    def __repr__(self) -> str:
+        return f"<AttentionItem {self.rule.value} #{self.subject_number}>"

package/backend/app/models/attention_settings.py

@@ -0,0 +1,61 @@
+"""关注项的订阅设置。
+
+背景：规则引擎对**每个命中对象**产出一条关注项。548 个未推进的 CVE PR 就是
+463 条 cve_aging，3000 个陈旧 Issue 就是 3000 条 issue_stale —— 加起来四千多
+条。那不是"需要关注"，那是"全部清单"。使用者翻两页就会放弃这个功能。
+
+两件事分开解决：
+
+1. **订阅**（本表）：哪些规则要提醒、阈值多少、只看 PR 还是只看 Issue。
+   团队节奏不同，阈值不该写死在代码里 —— 写死的结果是没人用，
+   因为第一条不符合自己节奏的提醒就会让人关掉整个队列。
+
+2. **收敛**（见 attention_service）：同一规则下的条目按主题聚合成分组，
+   队列显示分组，展开才是条目。分组是把"463 条"变成"3 类问题"的地方。
+
+设置是全局的而非按用户：这是 SIG 的公共队列，不是个人待办。
+按用户存会让"这个 PR 到底有没有人管"变得无法回答。
+"""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import (
+    Boolean,
+    DateTime,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base, TimestampMixin
+
+
+class AttentionRuleSetting(Base, TimestampMixin):
+    """单条规则的订阅设置。规则取值的权威定义在 ``domain.attention.Rule``。"""
+
+    __tablename__ = "ksp_attention_rule_setting"
+    __table_args__ = (UniqueConstraint("rule", name="uq_ksp_attention_rule_setting_rule"),)
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+
+    rule: Mapped[str] = mapped_column(String(32), nullable=False)
+    enabled: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+
+    days: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    """阈值天数。为空表示沿用领域层的默认值。"""
+
+    subject_scope: Mapped[str] = mapped_column(String(16), nullable=False, default="all")
+    """``all`` / ``pull_request`` / ``issue``。有些团队只关心 PR。"""
+
+    note: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    updated_by: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), nullable=True)
+    effective_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    """上次生效时间。界面据此说明"设置从下次重算开始生效"。"""
+
+    def __repr__(self) -> str:
+        return f"<AttentionRuleSetting {self.rule} enabled={self.enabled}>"

package/backend/app/models/audit.py

@@ -0,0 +1,53 @@
+"""审计日志。仅追加，不修改不删除。"""
+
+import uuid
+from datetime import datetime
+from enum import StrEnum
+
+from sqlalchemy import BigInteger, DateTime, Enum, ForeignKey, String, Text, func
+from sqlalchemy.dialects.postgresql import INET, JSONB, UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base
+
+
+class AuditResult(StrEnum):
+    SUCCESS = "success"
+    FAILURE = "failure"
+
+
+class AuditLog(Base):
+    __tablename__ = "ksp_audit_log"
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
+
+    actor_user_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("ksp_user.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
+    actor_username: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    actor_ip: Mapped[str | None] = mapped_column(INET, nullable=True)
+
+    action: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    target_type: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
+    target_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+
+    before: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    after: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+
+    result: Mapped[AuditResult] = mapped_column(
+        Enum(AuditResult, name="audit_result", values_callable=lambda e: [m.value for m in e]),
+        nullable=False,
+        default=AuditResult.SUCCESS,
+    )
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    request_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False, index=True
+    )
+
+    def __repr__(self) -> str:
+        return f"<AuditLog {self.action} by={self.actor_username} result={self.result.value}>"

package/backend/app/models/base.py

@@ -0,0 +1,35 @@
+"""SQLAlchemy 声明式基类与混入。"""
+
+from datetime import UTC, datetime
+
+from sqlalchemy import DateTime, MetaData, func
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+# 统一约束命名，保证 Alembic 生成的迁移可读且可回滚
+NAMING_CONVENTION = {
+    "ix": "ix_%(column_0_label)s",
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s",
+}
+
+
+class Base(DeclarativeBase):
+    metadata = MetaData(naming_convention=NAMING_CONVENTION)
+
+
+class TimestampMixin:
+    """创建/更新时间戳。"""
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=lambda: datetime.now(UTC),
+        nullable=False,
+    )