hunjing/backend/app/models.py

"""首批领域模型：身份、会话、服务账号、审计与 Outbox（WP-01）。

- 主键为带前缀的 UUIDv7 文本（ADR-015）；Session ID 为 CSPRNG opaque（秘密不用 UUID）。
- 命名约定见 app/db/base.py（pk_/uq_/ix_/fk_，AGENTS.md 8.6）。
- AuditEvent 与 OutboxEvent 不可变：无 updated_at，修正写新记录（契约第 4.4 节）。
"""

from datetime import datetime
from typing import Any

from sqlalchemy import CheckConstraint, DateTime, ForeignKey, Index, String, func
from sqlalchemy.dialects.postgresql import JSONB
from sqlalchemy.orm import Mapped, mapped_column

from app.core.ids import new_id
from app.db.base import Base


class User(Base):
    __tablename__ = "user"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("user_"))
    email: Mapped[str] = mapped_column(String, nullable=False, unique=True)
    display_name: Mapped[str] = mapped_column(String, nullable=False)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
    )


class PersonalDomain(Base):
    __tablename__ = "personal_domain"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("domain_")
    )
    user_id: Mapped[str] = mapped_column(
        ForeignKey("user.id", ondelete="restrict"), nullable=False, index=True
    )
    name: Mapped[str] = mapped_column(String, nullable=False)
    # 区域驻留（ADR-024 之前的数据驻留决策）：默认区域，迁移走正式协议
    data_region: Mapped[str] = mapped_column(String, nullable=False, default="default")
    # 保全态（ADR-021）：欠费/封禁只读保全，不删除数据
    billing_status: Mapped[str] = mapped_column(String, nullable=False, default="ok")
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )


class Session(Base):
    """Web 会话：ID 为 CSPRNG opaque value，数据库只存校验值（ADR-015）。"""

    __tablename__ = "session"

    id: Mapped[str] = mapped_column(String, primary_key=True)
    user_id: Mapped[str] = mapped_column(
        ForeignKey("user.id", ondelete="cascade"), nullable=False, index=True
    )
    token_hash: Mapped[str] = mapped_column(String, nullable=False, unique=True)
    csrf_token_hash: Mapped[str] = mapped_column(String, nullable=False)
    expires_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, index=True
    )
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)


class ServiceAccount(Base):
    """自动化账号：API key 明文只显示一次，只保存哈希、前缀、scope 与撤销状态。"""

    __tablename__ = "service_account"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("service_account_")
    )
    domain_id: Mapped[str] = mapped_column(
        ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False
    )
    name: Mapped[str] = mapped_column(String, nullable=False)
    key_prefix: Mapped[str] = mapped_column(String, nullable=False, index=True)
    key_hash: Mapped[str] = mapped_column(String, nullable=False)
    scopes: Mapped[list[str]] = mapped_column(JSONB, nullable=False, default=list)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

    __table_args__ = (Index("uq_service_account_domain_name", "domain_id", "name", unique=True),)


class AuditEvent(Base):
    """不可变审计链：状态与 Outbox 在同一事务提交（契约第 4.4 节）。"""

    __tablename__ = "audit_event"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("audit_"))
    occurred_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    actor_type: Mapped[str] = mapped_column(String, nullable=False)
    actor_id: Mapped[str] = mapped_column(String, nullable=False)
    action: Mapped[str] = mapped_column(String, nullable=False)
    aggregate_type: Mapped[str] = mapped_column(String, nullable=False)
    aggregate_id: Mapped[str] = mapped_column(String, nullable=False)
    payload: Mapped[dict[str, Any] | None] = mapped_column(JSONB, nullable=True)
    trace_id: Mapped[str | None] = mapped_column(String, nullable=True)

    __table_args__ = (
        # 聚合时间线是审计的主要查询路径（最左前缀覆盖聚合定位）
        Index("ix_audit_event_aggregate", "aggregate_type", "aggregate_id", "occurred_at"),
        Index("ix_audit_event_occurred_at", "occurred_at"),
    )


class OutboxEvent(Base):
    """Transactional Outbox：已提交领域事实的可靠投递队列。"""

    __tablename__ = "outbox_event"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("event_"))
    occurred_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    aggregate_type: Mapped[str] = mapped_column(String, nullable=False)
    aggregate_id: Mapped[str] = mapped_column(String, nullable=False)
    event_type: Mapped[str] = mapped_column(String, nullable=False)
    payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False)
    status: Mapped[str] = mapped_column(String, nullable=False, default="pending")
    attempts: Mapped[int] = mapped_column(nullable=False, default=0)
    delivered_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

    __table_args__ = (
        CheckConstraint(
            "status IN ('pending', 'delivered', 'failed')",
            name="status_values",
        ),
        # 投递循环按状态+时间扫描待处理事件
        Index("ix_outbox_event_status_occurred", "status", "occurred_at"),
        Index("ix_outbox_event_aggregate", "aggregate_type", "aggregate_id"),
    )


CONVERSATION_REALM_CK = CheckConstraint(
    "realm IN ('reality', 'world', 'simulation')", name="realm_values"
)


class Conversation(Base):
    """对话容器：归属个人域（垂直切片 WP-03 最小集）。"""

    __tablename__ = "conversation"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("conversation_")
    )
    personal_domain_id: Mapped[str] = mapped_column(
        ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False, index=True
    )
    title: Mapped[str] = mapped_column(String, nullable=False, default="未命名对话")
    realm: Mapped[str] = mapped_column(String, nullable=False, default="reality")
    current_branch_id: Mapped[str | None] = mapped_column(
        ForeignKey("branch.id", ondelete="set null", use_alter=True), nullable=True
    )
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
    )

    __table_args__ = (CONVERSATION_REALM_CK,)


class Branch(Base):
    """对话分支：创建会话时生成默认主分支。"""

    __tablename__ = "branch"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("branch_"))
    conversation_id: Mapped[str] = mapped_column(
        ForeignKey("conversation.id", ondelete="cascade"), nullable=False, index=True
    )
    title: Mapped[str] = mapped_column(String, nullable=False, default="主脉")
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )


class Message(Base):
    """消息：content 为 canonical ContentBlock JSON（本切片为 Text/Markdown 子集）。"""

    __tablename__ = "message"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("message_"))
    conversation_id: Mapped[str] = mapped_column(
        ForeignKey("conversation.id", ondelete="cascade"), nullable=False, index=True
    )
    branch_id: Mapped[str] = mapped_column(
        ForeignKey("branch.id", ondelete="cascade"), nullable=False, index=True
    )
    role: Mapped[str] = mapped_column(String, nullable=False)
    realm: Mapped[str] = mapped_column(String, nullable=False, default="reality")
    canonized_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
    parent_message_id: Mapped[str | None] = mapped_column(
        ForeignKey("message.id", ondelete="set null"), nullable=True
    )
    variant_kind: Mapped[str] = mapped_column(String, nullable=False, default="origin")
    run_id: Mapped[str | None] = mapped_column(
        ForeignKey("run.id", ondelete="set null"), nullable=True, index=True
    )
    content: Mapped[list[dict[str, Any]]] = mapped_column(JSONB, nullable=False)
    parser_version: Mapped[str | None] = mapped_column(String, nullable=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        CheckConstraint("role IN ('user', 'assistant', 'system', 'tool')", name="role_values"),
        CheckConstraint(
            "realm IN ('reality', 'world', 'simulation')", name="realm_values"
        ),
        CheckConstraint(
            "variant_kind IN ('origin', 'revision', 'candidate')", name="variant_kind_values"
        ),
    )


class Run(Base):
    """Agent 执行：状态机见 Agent 运行时第 3 节；本切片空转即完成。"""

    __tablename__ = "run"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("run_"))
    personal_domain_id: Mapped[str] = mapped_column(
        ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False, index=True
    )
    conversation_id: Mapped[str | None] = mapped_column(
        ForeignKey("conversation.id", ondelete="cascade"), nullable=True, index=True
    )
    status: Mapped[str] = mapped_column(String, nullable=False, default="queued")
    max_tool_calls: Mapped[int] = mapped_column(nullable=False, default=10)  # RunBudget 硬上限
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

    __table_args__ = (
        CheckConstraint(
            "status IN ('queued', 'running', 'waiting_approval', "
            "'completed', 'failed', 'cancelled')",
            name="status_values",
        ),
        Index("ix_run_domain_status", "personal_domain_id", "status"),
    )


class IdempotencyRecord(Base):
    """幂等键记录：按 认证主体+路由+键 隔离，保存请求哈希与结果引用（契约第 6 节）。"""

    __tablename__ = "idempotency_record"

    key: Mapped[str] = mapped_column(String, primary_key=True)
    owner_domain_id: Mapped[str] = mapped_column(
        ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False
    )
    route: Mapped[str] = mapped_column(String, nullable=False)
    request_hash: Mapped[str] = mapped_column(String, nullable=False)
    response_status: Mapped[int] = mapped_column(nullable=False)
    resource_ids: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        Index("uq_idempotency_owner_route_key", "owner_domain_id", "route", "key", unique=True),
    )


class RunEvent(Base):
    """Run 事件流：持久化后可重放；sequence 在 Run 内单调（契约第 5 节）。"""

    __tablename__ = "run_event"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("event_"))
    run_id: Mapped[str] = mapped_column(
        ForeignKey("run.id", ondelete="cascade"), nullable=False
    )
    sequence: Mapped[int] = mapped_column(nullable=False)
    type: Mapped[str] = mapped_column(String, nullable=False)
    data: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        CheckConstraint(
            "type IN ('content.block.started', 'content.block.delta', 'content.block.progress', "
            "'content.block.completed', 'content.block.failed', 'content.block.cancelled', "
            "'message.completed', 'run.status.changed')",
            name="type_values",
        ),
        # Run 内 sequence 单调且唯一（重放去重的服务端保证）
        Index("uq_run_event_run_sequence", "run_id", "sequence", unique=True),
    )


class CharacterVersion(Base):
    """角色版本链：baseline/初照自陈/内驱力修订/铸魂/人格候选（不可变版本）。"""

    __tablename__ = "character_version"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("character_version_")
    )
    character_id: Mapped[str] = mapped_column(
        ForeignKey("character.id", ondelete="cascade"), nullable=False, index=True
    )
    kind: Mapped[str] = mapped_column(String, nullable=False)
    status: Mapped[str] = mapped_column(String, nullable=False, default="approved")
    payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        CheckConstraint(
            "kind IN ('baseline', 'first_statement', 'drive_revision', 'reforging', "
            "'persona_candidate')",
            name="kind_values",
        ),
        CheckConstraint("status IN ('pending', 'approved', 'rejected')", name="status_values"),
    )


class Character(Base):
    """角色：稳定身份、生命周期状态、道体基线与内驱力（WP-02）。"""

    __tablename__ = "character"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("character_")
    )
    personal_domain_id: Mapped[str] = mapped_column(
        ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False, index=True
    )
    name: Mapped[str] = mapped_column(String, nullable=False)
    # 生命周期：灵胚 → 启镜 → 静修/归藏（可复照）；死亡走两步确认，deceased 不可逆
    status: Mapped[str] = mapped_column(String, nullable=False, default="draft")
    origin: Mapped[str] = mapped_column(String, nullable=False, default="original")
    based_on_real_person: Mapped[bool] = mapped_column(nullable=False, default=False)
    real_person_attested: Mapped[bool] = mapped_column(nullable=False, default=False)
    # 道体基线（identity_baseline）：最小稳定身份锚点，普通对话/记忆不可静默覆盖
    identity_baseline: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
    # 内驱力（character_drives）：声明式动机维度，用户可审阅编辑（ADR-018）
    drives: Mapped[list[dict[str, Any]]] = mapped_column(JSONB, nullable=False, default=list)
    current_version_id: Mapped[str | None] = mapped_column(
        ForeignKey("character_version.id", ondelete="set null", use_alter=True), nullable=True
    )
    death_requested_at: Mapped[datetime | None] = mapped_column(
        DateTime(timezone=True), nullable=True
    )
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
    )

    __table_args__ = (
        CheckConstraint(
            "status IN ('draft', 'active', 'resting', 'archived', 'death_pending', 'deceased')",
            name="status_values",
        ),
        CheckConstraint(
            "origin IN ('original', 'serendipity', 'template', 'import', 'fork')",
            name="origin_values",
        ),
    )


class LogicalModel(Base):
    """逻辑模型：业务只引用能力与逻辑名，不感知 Provider（契约第 5 节分面）。"""

    __tablename__ = "logical_model"

    id: Mapped[str] = mapped_column(String, primary_key=True)  # kebab-case，如 default-chat
    capabilities: Mapped[list[str]] = mapped_column(JSONB, nullable=False, default=list)
    description: Mapped[str | None] = mapped_column(String, nullable=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )


class ProviderEndpoint(Base):
    """Provider 端点：密钥只存环境变量名，永不落库明文。"""

    __tablename__ = "provider_endpoint"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("endpoint_")
    )
    logical_model_id: Mapped[str] = mapped_column(
        ForeignKey("logical_model.id", ondelete="cascade"), nullable=False, index=True
    )
    provider: Mapped[str] = mapped_column(String, nullable=False)
    name: Mapped[str] = mapped_column(String, nullable=False)
    base_url: Mapped[str] = mapped_column(String, nullable=False)
    model_id: Mapped[str] = mapped_column(String, nullable=False)
    api_key_env: Mapped[str] = mapped_column(String, nullable=False)
    priority: Mapped[int] = mapped_column(nullable=False, default=100)
    enabled: Mapped[bool] = mapped_column(nullable=False, default=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        CheckConstraint(
            "provider IN ('openai_compatible', 'anthropic')", name="provider_values"
        ),
    )


class Turn(Base):
    """Turn：Run 内一次模型决策及其工具交互阶段。"""

    __tablename__ = "turn"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("turn_"))
    run_id: Mapped[str] = mapped_column(
        ForeignKey("run.id", ondelete="cascade"), nullable=False, index=True
    )
    index: Mapped[int] = mapped_column(nullable=False, default=0)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        Index("uq_turn_run_index", "run_id", "index", unique=True),
    )


class ModelCall(Base):
    """每次上游 attempt 单独持久化：重试/故障转移不覆盖（ADR-003）。

    Provider 未返回的 usage 字段保持 null，不估算伪装。
    """

    __tablename__ = "model_call"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("model_call_")
    )
    turn_id: Mapped[str] = mapped_column(
        ForeignKey("turn.id", ondelete="cascade"), nullable=False, index=True
    )
    endpoint_id: Mapped[str | None] = mapped_column(
        ForeignKey("provider_endpoint.id", ondelete="set null"), nullable=True
    )
    attempt: Mapped[int] = mapped_column(nullable=False, default=1)
    status: Mapped[str] = mapped_column(String, nullable=False, default="pending")
    request_summary: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
    usage: Mapped[dict[str, Any] | None] = mapped_column(JSONB, nullable=True)
    ttft_ms: Mapped[int | None] = mapped_column(nullable=True)
    error: Mapped[str | None] = mapped_column(String, nullable=True)
    started_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

    __table_args__ = (
        CheckConstraint(
            "status IN ('pending', 'streaming', 'succeeded', 'failed')", name="status_values"
        ),
        Index("uq_model_call_turn_attempt", "turn_id", "attempt", unique=True),
    )


MEMORY_KIND_CK = CheckConstraint(
    "kind IN ('fact', 'preference', 'event', 'relationship')", name="kind_values"
)
SENSITIVITY_CK = CheckConstraint(
    "sensitivity IN ('none', 'low', 'medium', 'high')", name="sensitivity_values"
)
MEMORY_REALM_CK = CheckConstraint(
    "realm IN ('reality', 'world', 'simulation')", name="realm_values"
)


class MemoryCandidate(Base):
    """记忆候选：待判定提取结果，不参与召回（ADR-011）。"""

    __tablename__ = "memory_candidate"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("memory_candidate_")
    )
    owner_personal_domain_id: Mapped[str] = mapped_column(
        ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False, index=True
    )
    character_id: Mapped[str | None] = mapped_column(
        ForeignKey("character.id", ondelete="cascade"), nullable=True
    )
    kind: Mapped[str] = mapped_column(String, nullable=False)
    sensitivity: Mapped[str] = mapped_column(String, nullable=False, default="none")
    realm: Mapped[str] = mapped_column(String, nullable=False, default="reality")
    payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
    source: Mapped[str] = mapped_column(String, nullable=False, default="manual")
    source_ref: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
    content_hash: Mapped[str | None] = mapped_column(String, nullable=True)
    status: Mapped[str] = mapped_column(String, nullable=False, default="pending")
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    decided_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

    __table_args__ = (
        MEMORY_KIND_CK,
        SENSITIVITY_CK,
        MEMORY_REALM_CK,
        CheckConstraint(
            "status IN ('pending', 'approved', 'rejected', 'expired')", name="status_values"
        ),
        CheckConstraint(
            "source IN ('manual', 'auto', 'big_cycle', 'canonization')", name="source_values"
        ),
    )


class MemoryVersion(Base):
    """不可变记忆版本：纠正/取代/恢复都创建新版本（ADR-011）。"""

    __tablename__ = "memory_version"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("memory_version_")
    )
    memory_id: Mapped[str] = mapped_column(
        ForeignKey("memory.id", ondelete="cascade"), nullable=False, index=True
    )
    version: Mapped[int] = mapped_column(nullable=False)
    payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
    supersedes_version_id: Mapped[str | None] = mapped_column(
        ForeignKey("memory_version.id", ondelete="set null"), nullable=True
    )
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        Index("uq_memory_version_number", "memory_id", "version", unique=True),
    )


class Memory(Base):
    """权威长期记忆：候选批准后创建；当前版本由指针引用。"""

    __tablename__ = "memory"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("memory_"))
    owner_personal_domain_id: Mapped[str] = mapped_column(
        ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False, index=True
    )
    character_id: Mapped[str | None] = mapped_column(
        ForeignKey("character.id", ondelete="cascade"), nullable=True, index=True
    )
    kind: Mapped[str] = mapped_column(String, nullable=False)
    sensitivity: Mapped[str] = mapped_column(String, nullable=False, default="none")
    realm: Mapped[str] = mapped_column(String, nullable=False, default="reality")
    status: Mapped[str] = mapped_column(String, nullable=False, default="active")
    valid_from: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
    pinned: Mapped[bool] = mapped_column(nullable=False, default=False)
    current_version_id: Mapped[str | None] = mapped_column(
        ForeignKey("memory_version.id", ondelete="set null", use_alter=True), nullable=True
    )
    resource_version: Mapped[int] = mapped_column(nullable=False, default=1)  # ETag 源
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
    )

    __table_args__ = (
        MEMORY_KIND_CK,
        SENSITIVITY_CK,
        MEMORY_REALM_CK,
        CheckConstraint(
            "status IN ('active', 'superseded', 'archived', 'deleted')", name="status_values"
        ),
        Index("ix_memory_domain_status_kind", "owner_personal_domain_id", "status", "kind"),
    )


class BigCycle(Base):
    """大周天循环：cycle_ 聚合根，四阶段评估（ADR-018/023）。"""

    __tablename__ = "big_cycle"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("cycle_"))
    character_id: Mapped[str] = mapped_column(
        ForeignKey("character.id", ondelete="cascade"), nullable=False, index=True
    )
    status: Mapped[str] = mapped_column(String, nullable=False, default="pending")
    trigger: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
    phase_memory: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
    produced_version_ids: Mapped[list[str]] = mapped_column(JSONB, nullable=False, default=list)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

    __table_args__ = (
        CheckConstraint(
            "status IN ('pending', 'running', 'completed', 'failed')", name="status_values"
        ),
    )


class Tool(Base):
    """工具注册表：内置工具与后续插件贡献统一登记（WP-06）。"""

    __tablename__ = "tool"

    name: Mapped[str] = mapped_column(String, primary_key=True)  # kebab-case
    description: Mapped[str] = mapped_column(String, nullable=False, default="")
    input_schema: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
    risk_level: Mapped[str] = mapped_column(String, nullable=False, default="read_only")
    requires_approval: Mapped[bool] = mapped_column(nullable=False, default=False)
    enabled: Mapped[bool] = mapped_column(nullable=False, default=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        CheckConstraint(
            "risk_level IN ('read_only', 'side_effect', 'high_impact')",
            name="risk_level_values",
        ),
    )


class ToolCall(Base):
    """工具调用：Schema 校验与 Policy 判定后的执行记录（含审批态）。"""

    __tablename__ = "tool_call"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("tool_call_")
    )
    run_id: Mapped[str] = mapped_column(
        ForeignKey("run.id", ondelete="cascade"), nullable=False, index=True
    )
    tool_name: Mapped[str] = mapped_column(String, nullable=False)
    input: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
    output: Mapped[dict[str, Any] | None] = mapped_column(JSONB, nullable=True)
    status: Mapped[str] = mapped_column(String, nullable=False, default="pending_approval")
    error: Mapped[str | None] = mapped_column(String, nullable=True)
    idempotency_key: Mapped[str | None] = mapped_column(String, nullable=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

    __table_args__ = (
        CheckConstraint(
            "status IN ('pending_approval', 'approved', 'denied', "
            "'executing', 'succeeded', 'failed')",
            name="status_values",
        ),
        Index(
            "uq_tool_call_idempotency", "run_id", "tool_name", "idempotency_key",
            unique=True,
        ),
    )


class Listing(Base):
    """市场商品（WP-13）：带版本、价格与许可；此处为最小商品形态。"""

    __tablename__ = "listing"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("listing_")
    )
    creator_domain_id: Mapped[str] = mapped_column(
        ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False, index=True
    )
    title: Mapped[str] = mapped_column(String, nullable=False)
    price_minor: Mapped[int] = mapped_column(nullable=False, default=0)  # 0=免费
    currency: Mapped[str] = mapped_column(String, nullable=False, default="CNY")
    status: Mapped[str] = mapped_column(String, nullable=False, default="published")
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        CheckConstraint("price_minor >= 0", name="price_non_negative"),
    )


class Order(Base):
    """订单（契约 order_status 六态）；下单即价格快照，客户端金额不可信。"""

    __tablename__ = "order"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("order_"))
    buyer_domain_id: Mapped[str] = mapped_column(
        ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False, index=True
    )
    status: Mapped[str] = mapped_column(String, nullable=False, default="pending_payment")
    total_minor: Mapped[int] = mapped_column(nullable=False, default=0)
    currency: Mapped[str] = mapped_column(String, nullable=False, default="CNY")
    idempotency_key: Mapped[str | None] = mapped_column(String, nullable=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    paid_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
    refunded_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

    __table_args__ = (
        CheckConstraint(
            "status IN ('pending_payment', 'paid', 'partially_refunded', 'refunded', "
            "'disputed', 'cancelled')",
            name="status_values",
        ),
        Index("uq_order_buyer_idempotency", "buyer_domain_id", "idempotency_key", unique=True),
    )


class OrderItem(Base):
    """订单行：商品与价格快照（下单时冻结，后续改价不影响）。"""

    __tablename__ = "order_item"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("item_"))
    order_id: Mapped[str] = mapped_column(
        ForeignKey("order.id", ondelete="cascade"), nullable=False, index=True
    )
    listing_id: Mapped[str] = mapped_column(
        ForeignKey("listing.id", ondelete="restrict"), nullable=False
    )
    title_snapshot: Mapped[str] = mapped_column(String, nullable=False)
    price_minor_snapshot: Mapped[int] = mapped_column(nullable=False)


class LedgerEntry(Base):
    """不可变账务分录（ADR-009）：修正只写反向分录，禁止更新删除。

    带符号金额：charge/payable/fee 为正，reversal 为负；
    平衡不变量：每笔订单 sum(charge+reversal) == sum(fee+fee_rev+payable+pay_rev)。
    """

    __tablename__ = "ledger_entry"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("ledger_")
    )
    order_id: Mapped[str] = mapped_column(
        ForeignKey("order.id", ondelete="restrict"), nullable=False, index=True
    )
    entry_type: Mapped[str] = mapped_column(String, nullable=False)
    amount_minor: Mapped[int] = mapped_column(nullable=False)  # 带符号
    currency: Mapped[str] = mapped_column(String, nullable=False, default="CNY")
    note: Mapped[str | None] = mapped_column(String, nullable=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        CheckConstraint(
            "entry_type IN ('charge', 'refund', 'platform_fee', 'creator_payable', "
            "'tax', 'reserve', 'payout', 'reversal')",
            name="entry_type_values",
        ),
        Index("ix_ledger_order_type", "order_id", "entry_type"),
    )


class WebhookEvent(Base):
    """支付 Webhook 事件：按 Provider 事件 ID 幂等，允许乱序到达。"""

    __tablename__ = "webhook_event"

    provider_event_id: Mapped[str] = mapped_column(String, primary_key=True)
    provider: Mapped[str] = mapped_column(String, nullable=False)
    event_type: Mapped[str] = mapped_column(String, nullable=False)
    payload_hash: Mapped[str] = mapped_column(String, nullable=False)
    status: Mapped[str] = mapped_column(String, nullable=False, default="processed")
    received_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        CheckConstraint("status IN ('processed', 'ignored')", name="status_values"),
    )


class CommunityContent(Base):
    """社区内容：帖子与角色 Release（WP-11）。

    角色 Release 由服务端构造公开快照；私密记忆/关系/对话在结构上不进入发布物。
    """

    __tablename__ = "community_content"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("content_")
    )
    author_domain_id: Mapped[str] = mapped_column(
        ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False, index=True
    )
    kind: Mapped[str] = mapped_column(String, nullable=False, default="post")
    title: Mapped[str] = mapped_column(String, nullable=False)
    body: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
    character_id: Mapped[str | None] = mapped_column(
        ForeignKey("character.id", ondelete="set null"), nullable=True
    )
    visibility: Mapped[str] = mapped_column(String, nullable=False, default="public")
    status: Mapped[str] = mapped_column(String, nullable=False, default="published")
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
    )

    __table_args__ = (
        CheckConstraint("kind IN ('post', 'character_release')", name="kind_values"),
        CheckConstraint("visibility IN ('public', 'followers')", name="visibility_values"),
        CheckConstraint(
            "status IN ('draft', 'submitted', 'published', 'limited', 'suspended', 'removed')",
            name="status_values",
        ),
    )


class Comment(Base):
    """社区评论：平铺 + 可选父级；下架内容下的评论不可见。"""

    __tablename__ = "comment"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("comment_"))
    content_id: Mapped[str] = mapped_column(
        ForeignKey("community_content.id", ondelete="cascade"), nullable=False, index=True
    )
    author_domain_id: Mapped[str] = mapped_column(
        ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False
    )
    parent_comment_id: Mapped[str | None] = mapped_column(
        ForeignKey("comment.id", ondelete="cascade"), nullable=True
    )
    body: Mapped[str] = mapped_column(String, nullable=False)
    status: Mapped[str] = mapped_column(String, nullable=False, default="visible")
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        CheckConstraint("status IN ('visible', 'removed')", name="status_values"),
    )


class Reaction(Base):
    """互动：点赞/收藏；(content, actor, kind) 唯一防重复。"""

    __tablename__ = "reaction"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("reaction_"))
    content_id: Mapped[str] = mapped_column(
        ForeignKey("community_content.id", ondelete="cascade"), nullable=False, index=True
    )
    actor_domain_id: Mapped[str] = mapped_column(
        ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False
    )
    kind: Mapped[str] = mapped_column(String, nullable=False)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        CheckConstraint("kind IN ('like', 'save')", name="kind_values"),
        Index(
            "uq_reaction_content_actor_kind",
            "content_id", "actor_domain_id", "kind",
            unique=True,
        ),
    )


class Follow(Base):
    """关注关系（域→域）。"""

    __tablename__ = "follow"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("follow_"))
    # 双 FK 同指 personal_domain：显式命名避免 convention 同名冲突
    follower_domain_id: Mapped[str] = mapped_column(
        ForeignKey(
            "personal_domain.id", ondelete="cascade", name="fk_follow_follower_domain"
        ),
        nullable=False,
        index=True,
    )
    followee_domain_id: Mapped[str] = mapped_column(
        ForeignKey(
            "personal_domain.id", ondelete="cascade", name="fk_follow_followee_domain"
        ),
        nullable=False,
        index=True,
    )
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        Index(
            "uq_follow_pair", "follower_domain_id", "followee_domain_id", unique=True
        ),
    )


class Report(Base):
    """举报：创建即生成司议案（治理队列入口）。"""

    __tablename__ = "report"

    id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: new_id("report_"))
    reporter_domain_id: Mapped[str] = mapped_column(
        ForeignKey("personal_domain.id", ondelete="cascade"), nullable=False, index=True
    )
    target_type: Mapped[str] = mapped_column(String, nullable=False)
    target_id: Mapped[str] = mapped_column(String, nullable=False)
    reason: Mapped[str] = mapped_column(String, nullable=False)
    status: Mapped[str] = mapped_column(String, nullable=False, default="pending")
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        CheckConstraint("target_type IN ('content', 'comment')", name="target_type_values"),
        CheckConstraint("status IN ('pending', 'reviewed', 'actioned')", name="status_values"),
    )


class ModerationCase(Base):
    """司议案：由举报生成，处置动作与结果留痕。"""

    __tablename__ = "moderation_case"

    id: Mapped[str] = mapped_column(
        String, primary_key=True, default=lambda: new_id("moderation_")
    )
    report_id: Mapped[str] = mapped_column(
        ForeignKey("report.id", ondelete="cascade"), nullable=False, index=True
    )
    status: Mapped[str] = mapped_column(String, nullable=False, default="pending")
    action_taken: Mapped[str | None] = mapped_column(String, nullable=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )

    __table_args__ = (
        CheckConstraint("status IN ('pending', 'resolved')", name="status_values"),
    )