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

"""
Story Layer 数据模型。

- stories: 可独立讲述的人生故事，canonical_markdown 为正文真源
- story_versions: 版本链，记录每次生成/编辑
- story_evidence_links: story 与 evidence（chunk/fact/timeline_event/summary）的关联
"""

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

from app.core.db import Base, utc_now


class Story(Base):
    """可独立讲述的一段人生故事，正文真源。"""

    __tablename__ = "stories"

    id = Column(String, primary_key=True)
    user_id = Column(String, ForeignKey("users.id"), nullable=False, index=True)
    title = Column(String, nullable=False)
    stage = Column(
        String, nullable=True
    )  # childhood / education / career / family / belief / summary
    story_type = Column(
        String, nullable=True
    )  # event / person / relationship / reflection / turning_point
    summary = Column(Text, nullable=True)
    canonical_markdown = Column(Text, nullable=True)  # 当前生效正文
    time_start = Column(String, nullable=True)  # 起始时间，粗粒度 year/month/date
    time_end = Column(String, nullable=True)
    people_refs = Column(JSON, nullable=True)
    place_refs = Column(JSON, nullable=True)
    tag_refs = Column(JSON, nullable=True)
    status = Column(String, default="active")  # active / archived / merged / draft
    confidence = Column(Float, 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)

    versions = relationship(
        "StoryVersion",
        back_populates="story",
        foreign_keys="StoryVersion.story_id",
        cascade="all, delete-orphan",
    )
    current_version = relationship(
        "StoryVersion",
        primaryjoin="Story.current_version_id == StoryVersion.id",
        foreign_keys="StoryVersion.id",
    )
    user = relationship("User", back_populates="stories")
    evidence_links = relationship(
        "StoryEvidenceLink",
        back_populates="story",
        cascade="all, delete-orphan",
    )
    chapter_links = relationship(
        "ChapterStoryLink",
        back_populates="story",
        cascade="all, delete-orphan",
    )
    image_intents = relationship(
        "StoryImageIntent",
        back_populates="story",
        cascade="all, delete-orphan",
    )


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

    __tablename__ = "story_versions"

    id = Column(String, primary_key=True)
    story_id = Column(
        String, ForeignKey("stories.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("story_versions.id", ondelete="SET NULL"), nullable=True
    )
    prompt_meta = Column(JSON, nullable=True)
    created_at = Column(DateTime(timezone=True), default=utc_now)

    story = relationship("Story", back_populates="versions", foreign_keys=[story_id])
    parent_version = relationship(
        "StoryVersion",
        remote_side="StoryVersion.id",
        foreign_keys=[parent_version_id],
    )


class StoryEvidenceLink(Base):
    """Story 与 evidence 的关联。"""

    __tablename__ = "story_evidence_links"

    id = Column(String, primary_key=True)
    story_id = Column(
        String, ForeignKey("stories.id", ondelete="CASCADE"), nullable=False, index=True
    )
    evidence_type = Column(
        String, nullable=False
    )  # chunk / fact / timeline_event / summary
    evidence_id = Column(String, nullable=False)
    role = Column(String, nullable=True)  # primary / supporting / background
    weight = Column(Float, nullable=True)
    created_at = Column(DateTime(timezone=True), default=utc_now)

    story = relationship("Story", back_populates="evidence_links")


class StoryImageIntent(Base):
    """Story 主插图意图，每个 active story 仅允许 1 条 intent_role=primary。"""

    __tablename__ = "story_image_intents"

    id = Column(String, primary_key=True)
    story_id = Column(
        String, ForeignKey("stories.id", ondelete="CASCADE"), nullable=False, index=True
    )
    story_version_id = Column(
        String,
        ForeignKey("story_versions.id", ondelete="SET NULL"),
        nullable=True,
    )
    intent_role = Column(String, nullable=False)  # primary
    source_span = Column(JSON, nullable=True)
    caption = Column(String, nullable=True)
    prompt_brief = Column(Text, nullable=True)
    style_profile = Column(String, nullable=True)
    status = Column(String, nullable=False)  # pending / processing / completed / failed
    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)

    story = relationship("Story", back_populates="image_intents")
    story_version = relationship(
        "StoryVersion",
        foreign_keys=[story_version_id],
    )