backend: add section-field and paper-template schema, API, and seed data
Three tables behind the template configuration feature:
section_field the reusable heading library (name, level, font size,
colour)
paper_template a named outline (name, abstract)
template_field the join, and the only home of display order (sort)
The field library is deliberately flat. A `parent_id` would tie a level-2
heading to exactly one level-1 heading, and the point of the feature is that
a field such as "Background" can sit under both "1. Introduction" and
"2. Related Work" — and in any number of templates, at a different position
in each. Hierarchy is expressed only by `level`, which is a rendering hint.
Display order lives entirely in `template_field.sort`. The order fields were
picked in is never stored, so selecting fields out of order and assigning
sorts renders in sort order. Two consequences are intentional and documented
on the model: repeats are allowed (no unique constraint on template+field)
and ties are legal (broken by insertion order, so the ordering is total).
Templates reference library fields rather than copying them, so renaming or
restyling a field updates every template that places it.
TiDB parses FOREIGN KEY and then ignores it, so the constraints are declared
for documentation and the integrity is enforced in the application layer:
deleting a field still in use is refused with the field names, creating a
template against a missing field is refused, and deleting a template removes
its join rows through the ORM's delete-orphan cascade.
Also normalises font_color to #RRGGBB on write (accepting rgb() and
shorthand) and emits font_size as a JSON number rather than pydantic's
default Decimal string.
scripts/seed.py is idempotent and fills the library with a standard academic
outline plus three starter templates.
This commit is contained in:
@@ -0,0 +1,46 @@
|
||||
"""Paper templates (模板表).
|
||||
|
||||
A template is a named, ordered selection of library fields — the outline a
|
||||
paper is written against. It stores no typography of its own: font size and
|
||||
colour are read from the referenced :class:`~app.models.section_field.SectionField`,
|
||||
so correcting a field's styling updates every template that uses it.
|
||||
"""
|
||||
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
from sqlalchemy import String, Text
|
||||
from sqlalchemy.orm import Mapped, mapped_column, relationship
|
||||
|
||||
from app.db.base import Base
|
||||
from app.models.mixins import TimestampMixin
|
||||
|
||||
if TYPE_CHECKING: # pragma: no cover - typing only
|
||||
from app.models.template_field import TemplateField
|
||||
|
||||
|
||||
class PaperTemplate(TimestampMixin, Base):
|
||||
"""A named outline: a template name, a summary, and its ordered fields."""
|
||||
|
||||
__tablename__ = "paper_template"
|
||||
|
||||
id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
|
||||
|
||||
name: Mapped[str] = mapped_column(String(255), nullable=False)
|
||||
|
||||
#: Free-text abstract (摘要) describing when to use this template.
|
||||
abstract: Mapped[str | None] = mapped_column(Text, nullable=True)
|
||||
|
||||
#: The template's fields, always handed to callers in display order.
|
||||
#:
|
||||
#: ``delete-orphan`` is doing real work here: TiDB parses but does not
|
||||
#: enforce ``ON DELETE CASCADE``, so removing a template's rows in the join
|
||||
#: table is the ORM's job, not the database's.
|
||||
items: Mapped[list["TemplateField"]] = relationship(
|
||||
back_populates="template",
|
||||
cascade="all, delete-orphan",
|
||||
order_by="TemplateField.sort, TemplateField.id",
|
||||
lazy="selectin",
|
||||
)
|
||||
|
||||
def __repr__(self) -> str: # pragma: no cover - debugging aid
|
||||
return f"<PaperTemplate id={self.id} name={self.name!r}>"
|
||||
Reference in New Issue
Block a user