"""The template <-> field join table (关联表), which owns the display order. This table is the heart of the design. It carries exactly one piece of information that belongs to neither side alone: ``sort`` — where this field sits in *this* template. Consequences worth stating explicitly, because they are the requirements: * A field can appear in many templates, at a different position in each. * A field can legitimately appear **more than once** in the same template (e.g. a level-2 "Background" under both "1. Introduction" and "2. Related Work"), so there is deliberately **no** unique constraint on ``(template_id, field_id)``. The UI warns about repeats; it does not forbid them. * The user picks fields in any order they like. Nothing about the selection order is stored — readers order strictly by ``sort``, then by ``id`` as a stable tie-breaker. """ from typing import TYPE_CHECKING from sqlalchemy import ForeignKey, Index, Integer from sqlalchemy.orm import Mapped, mapped_column, relationship from app.db.base import Base if TYPE_CHECKING: # pragma: no cover - typing only from app.models.template import Template from app.models.template_title import TemplateTitle class TemplateTitlePlacement(Base): """One placement of one library title inside one template.""" __tablename__ = "template_title_placement" __table_args__ = ( # Every read is "the placements of template X, in order", so the index # covers both the filter and the sort. Index("ix_template_title_placement_template_sort", "template_id", "sort"), Index("ix_template_title_placement_title_id", "title_id"), ) id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True) template_id: Mapped[int] = mapped_column( ForeignKey("template.id", ondelete="CASCADE"), nullable=False, ) #: ``RESTRICT``: a title still placed in a template must not vanish from #: under it. The API checks this in Python too, so a refusal names the row #: rather than surfacing a driver error. title_id: Mapped[int] = mapped_column( ForeignKey("template_title.id", ondelete="RESTRICT"), nullable=False, ) #: Display position within the template. Plain ascending integer — lower #: sorts render first regardless of the title's ``level``. sort: Mapped[int] = mapped_column(Integer, nullable=False, default=0) template: Mapped["Template"] = relationship(back_populates="placements") #: Eager-loaded because every template read needs the title's name and #: typography; lazy loading would emit one query per row. title: Mapped["TemplateTitle"] = relationship(lazy="joined") def __repr__(self) -> str: # pragma: no cover - debugging aid return ( f"" )