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:
2026-09-18 15:56:47 +08:00
parent cad96e585f
commit 13e5fc2cc1
18 changed files with 1540 additions and 15 deletions
+77
View File
@@ -0,0 +1,77 @@
"""The reusable section-field library (字段表).
A *section field* is one heading a paper can contain — "1. Introduction",
"2.1 Dataset", "0 Abstract". Fields live in this one global library and are
never owned by a template.
Why there is no ``parent_id``
-----------------------------
A tree would make a field usable under exactly one parent, so a level-2 heading
such as "Background" could not sit under both "1. Introduction" and
"2. Related Work". Hierarchy is therefore expressed only by
:attr:`SectionField.level` (1, 2, 3 ...), which is a *rendering hint* — it
drives indentation and numbering semantics in the UI — while a field stays
free to be attached to any number of templates and any number of parents
within them.
The number that the reader sees is part of :attr:`name` and is written by the
user ("1. Introduction", "0 Abstract"). Nothing derives or rewrites it.
Ordering inside a template is *not* stored here: it lives in
``template_field.sort``. This table has no ``sort`` column on purpose, so that
one library field can occupy a different position in every template.
"""
from decimal import Decimal
from sqlalchemy import Integer, Numeric, String, text
from sqlalchemy.orm import Mapped, mapped_column
from app.db.base import Base
from app.models.mixins import TimestampMixin
class SectionField(TimestampMixin, Base):
"""A single reusable heading, with the typography it should render in."""
__tablename__ = "section_field"
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
#: Display name, numbering included. Stored and rendered verbatim.
name: Mapped[str] = mapped_column(String(255), nullable=False)
#: Heading depth: 1 for "1.", 2 for "1.1", 3 for "1.1.1". Rendering hint
#: only — it does not link fields to each other.
level: Mapped[int] = mapped_column(
Integer,
nullable=False,
default=1,
server_default=text("1"),
)
#: Font size in points. ``Numeric`` rather than ``Integer`` because the
#: conventional Chinese sizes are fractional (五号 = 10.5pt,
#: 小四 = 12pt).
font_size: Mapped[Decimal] = mapped_column(
Numeric(4, 1),
nullable=False,
default=Decimal("12.0"),
server_default=text("12.0"),
)
#: Font colour as ``#RRGGBB`` — the canonical RGB encoding. The API
#: normalises ``rgb(20, 30, 40)``, ``#abc`` and bare ``aabbcc`` to it on
#: write, so the column always holds one comparable format.
font_color: Mapped[str] = mapped_column(
String(7),
nullable=False,
default="#000000",
server_default=text("'#000000'"),
)
def __repr__(self) -> str: # pragma: no cover - debugging aid
return (
f"<SectionField id={self.id} name={self.name!r} "
f"level={self.level} color={self.font_color}>"
)