life-echo/api/app/features/memoir/models.py

from sqlalchemy import (
    JSON,
    Boolean,
    Column,
    DateTime,
    Float,
    ForeignKey,
    Integer,
    String,
    Text,
)
from sqlalchemy.orm import relationship

from app.core.db import Base, utc_now


class Chapter(Base):
    """章节：阅读与导出视图，canonical_markdown 为正文真源。"""

    __tablename__ = "chapters"

    id = Column(String, primary_key=True)
    user_id = Column(String, ForeignKey("users.id"), nullable=False)
    book_id = Column(String, ForeignKey("books.id", ondelete="SET NULL"), nullable=True)
    title = Column(String, nullable=False)
    category = Column(String, nullable=True)
    order_index = Column(Integer, nullable=False)
    summary = Column(Text, nullable=True)
    canonical_markdown = Column(Text, nullable=True)  # 当前生效正文（markdown-first）
    status = Column(String, default="draft")  # active / draft / archived
    cover_asset_id = Column(String, nullable=True)
    current_version_id = Column(String, nullable=True)  # FK 在 migration 中分步添加
    created_at = Column(DateTime(timezone=True), default=utc_now)
    updated_at = Column(DateTime(timezone=True), default=utc_now, onupdate=utc_now)
    is_new = Column(Boolean, default=True)
    is_active = Column(Boolean, default=True)
    source_segments = Column(JSON, nullable=True)
    # 物化当前 canonical 对应的证据闭包（segment / story / memory ids），供评测与审计；见 memoir/chapter_evidence_snapshot
    evidence_bundle_json = Column(JSON, nullable=True)
    # Phase C：指向当前生效的 chapter_evidence_snapshots 行（版本链可审计）
    current_evidence_snapshot_id = Column(
        String,
        ForeignKey("chapter_evidence_snapshots.id", ondelete="SET NULL"),
        nullable=True,
    )
    # story-backed 章节：story 变更后标 True，由 Celery 重组 canonical_markdown
    markdown_compose_dirty = Column(Boolean, default=False, nullable=False)
    markdown_composed_at = Column(DateTime(timezone=True), nullable=True)
    # 与 canonical 同一生成时机物化；无签名 URL，读时 hydrate
    reading_segments_json = Column(JSON, nullable=True)
    source_lineage_json = Column(JSON, nullable=True)

    user = relationship("User", back_populates="chapters")
    book = relationship("Book", back_populates="chapters")
    images = relationship(
        "MemoirImage",
        back_populates="chapter",
        foreign_keys="MemoirImage.chapter_id",
        cascade="all, delete-orphan",
    )
    versions = relationship(
        "ChapterVersion",
        back_populates="chapter",
        foreign_keys="ChapterVersion.chapter_id",
        cascade="all, delete-orphan",
    )
    current_version = relationship(
        "ChapterVersion",
        primaryjoin="Chapter.current_version_id == ChapterVersion.id",
        foreign_keys="ChapterVersion.id",
    )
    story_links = relationship(
        "ChapterStoryLink",
        back_populates="chapter",
        cascade="all, delete-orphan",
    )
    cover_intents = relationship(
        "ChapterCoverIntent",
        back_populates="chapter",
        cascade="all, delete-orphan",
    )
    evidence_snapshots = relationship(
        "ChapterEvidenceSnapshot",
        back_populates="chapter",
        foreign_keys="ChapterEvidenceSnapshot.chapter_id",
        cascade="all, delete-orphan",
    )
    evidence_links = relationship(
        "ChapterEvidenceLink",
        back_populates="chapter",
        cascade="all, delete-orphan",
    )
    current_evidence_snapshot = relationship(
        "ChapterEvidenceSnapshot",
        foreign_keys=[current_evidence_snapshot_id],
        post_update=True,
    )


class MemoirImage(Base):
    __tablename__ = "memoir_images"

    id = Column(String, primary_key=True)
    chapter_id = Column(
        String, ForeignKey("chapters.id", ondelete="CASCADE"), nullable=False
    )
    order_index = Column(Integer, nullable=False, default=0)
    placeholder = Column(Text, nullable=True)
    description = Column(Text, nullable=True)
    status = Column(String, nullable=False, default="pending")
    prompt = Column(Text, nullable=True)
    url = Column(Text, nullable=True)
    storage_key = Column(Text, nullable=True)
    provider = Column(String, nullable=True)
    style = Column(String, nullable=True)
    size = Column(String, nullable=True)
    error = Column(Text, nullable=True)
    retryable = Column(Boolean, nullable=True)
    created_at = Column(DateTime(timezone=True), nullable=True)
    updated_at = Column(DateTime(timezone=True), default=utc_now, onupdate=utc_now)

    chapter = relationship("Chapter", back_populates="images")


class ChapterVersion(Base):
    """Chapter 版本快照，记录正文变更与来源。"""

    __tablename__ = "chapter_versions"

    id = Column(String, primary_key=True)
    chapter_id = Column(
        String,
        ForeignKey("chapters.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
    )
    version_no = Column(Integer, nullable=False)
    markdown_snapshot = Column(Text, nullable=False)
    change_summary = Column(Text, nullable=True)
    actor_type = Column(String, nullable=True)  # ai / user / editor / system
    source_type = Column(
        String, nullable=True
    )  # generate / rewrite / merge / manual / migration
    parent_version_id = Column(
        String, ForeignKey("chapter_versions.id", ondelete="SET NULL"), nullable=True
    )
    prompt_meta = Column(JSON, nullable=True)
    created_at = Column(DateTime(timezone=True), default=utc_now)

    chapter = relationship(
        "Chapter", back_populates="versions", foreign_keys=[chapter_id]
    )
    parent_version = relationship(
        "ChapterVersion",
        remote_side="ChapterVersion.id",
        foreign_keys=[parent_version_id],
    )


class ChapterCoverIntent(Base):
    """Chapter 封面意图（结构化）。"""

    __tablename__ = "chapter_cover_intents"

    id = Column(String, primary_key=True)
    chapter_id = Column(
        String,
        ForeignKey("chapters.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
    )
    chapter_version_id = Column(
        String,
        ForeignKey("chapter_versions.id", ondelete="SET NULL"),
        nullable=True,
    )
    story_ids = Column(JSON, nullable=True)
    prompt_brief = Column(Text, nullable=True)
    status = Column(String, nullable=False)
    claim_token = Column(String, nullable=True)
    claimed_at = Column(DateTime(timezone=True), nullable=True)
    attempt_count = Column(Integer, nullable=False, default=0)
    asset_id = Column(String, nullable=True)
    error = Column(Text, nullable=True)
    created_at = Column(DateTime(timezone=True), default=utc_now)
    updated_at = Column(DateTime(timezone=True), default=utc_now, onupdate=utc_now)

    chapter = relationship("Chapter", back_populates="cover_intents")


class ChapterStoryLink(Base):
    """Chapter 与 Story 的编排关联。"""

    __tablename__ = "chapter_story_links"

    id = Column(String, primary_key=True)
    chapter_id = Column(
        String,
        ForeignKey("chapters.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
    )
    story_id = Column(
        String, ForeignKey("stories.id", ondelete="CASCADE"), nullable=False, index=True
    )
    order_index = Column(Integer, nullable=False)
    role = Column(String, nullable=True)  # core / bridge / appendix
    created_at = Column(DateTime(timezone=True), default=utc_now)

    chapter = relationship("Chapter", back_populates="story_links")
    story = relationship("Story", back_populates="chapter_links")


class ChapterEvidenceSnapshot(Base):
    """章节证据闭包版本快照（一行 = 一次物化；current 指针在 Chapter 上）。"""

    __tablename__ = "chapter_evidence_snapshots"

    id = Column(String, primary_key=True)
    chapter_id = Column(
        String,
        ForeignKey("chapters.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
    )
    user_id = Column(String, ForeignKey("users.id"), nullable=False, index=True)
    version_no = Column(Integer, nullable=False)
    schema_version = Column(Integer, nullable=False, default=1)
    segment_ids = Column(JSON, nullable=True)
    conversation_ids = Column(JSON, nullable=True)
    story_ids = Column(JSON, nullable=True)
    memory_chunk_ids = Column(JSON, nullable=True)
    memory_fact_ids = Column(JSON, nullable=True)
    timeline_event_ids = Column(JSON, nullable=True)
    summary_ids = Column(JSON, nullable=True)
    notes = Column(JSON, nullable=True)
    message_lineage_json = Column(JSON, nullable=True)
    captured_at = Column(DateTime(timezone=True), default=utc_now)

    chapter = relationship(
        "Chapter",
        back_populates="evidence_snapshots",
        foreign_keys=[chapter_id],
    )


class ChapterEvidenceLink(Base):
    """与 StoryEvidenceLink 对称：章节当前态绑定的结构化记忆 id（按快照刷新时整批替换）。"""

    __tablename__ = "chapter_evidence_links"

    id = Column(String, primary_key=True)
    chapter_id = Column(
        String,
        ForeignKey("chapters.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
    )
    evidence_type = Column(String, nullable=False)
    evidence_id = Column(String, nullable=False)
    role = Column(String, nullable=True)
    weight = Column(Float, nullable=True)
    created_at = Column(DateTime(timezone=True), default=utc_now)

    chapter = relationship("Chapter", back_populates="evidence_links")


class Book(Base):
    __tablename__ = "books"

    id = Column(String, primary_key=True)
    user_id = Column(String, ForeignKey("users.id"), nullable=False)
    title = Column(String, nullable=False)
    total_pages = Column(Integer, default=0)
    total_words = Column(Integer, default=0)
    cover_image_url = Column(String, nullable=True)
    updated_at = Column(DateTime(timezone=True), default=utc_now, onupdate=utc_now)
    has_update = Column(Boolean, default=False)
    last_update_chapter_id = Column(String, nullable=True)

    user = relationship("User", back_populates="books")
    chapters = relationship(
        "Chapter",
        back_populates="book",
        foreign_keys="Chapter.book_id",
    )


class MemoirState(Base):
    __tablename__ = "memoir_states"

    id = Column(String, primary_key=True)
    user_id = Column(String, ForeignKey("users.id"), unique=True, nullable=False)
    stage_order = Column(JSON, default=list)
    current_stage = Column(String, default="childhood")
    covered_stages = Column(JSON, default=list)
    slots = Column(JSON, nullable=False)
    updated_at = Column(DateTime(timezone=True), default=utc_now, onupdate=utc_now)

    user = relationship("User", back_populates="memoir_state")