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.

backend/app/crud/__init__.py

@@ -1,7 +1,10 @@
 """Data-access helpers.
 
 Functions here take a :class:`sqlalchemy.orm.Session` and operate on ORM
-models. There are none yet — this package is a placeholder for that layer.
+models. They own the commit: a route calls one function and gets back either a
+persisted object or ``None``.
 """
 
-__all__: list[str] = []
+from app.crud import paper_template, section_field
+
+__all__ = ["paper_template", "section_field"]

backend/app/crud/filters.py

@@ -0,0 +1,19 @@
+"""Query-building helpers shared by the CRUD modules."""
+
+LIKE_ESCAPE = "\\"
+
+
+def like_pattern(keyword: str) -> str:
+    """Turn user input into a safe ``%keyword%`` LIKE pattern.
+
+    A user searching for ``50%`` or ``a_b`` means those characters literally,
+    but ``%`` and ``_`` are LIKE wildcards. Escaping them — backslash first,
+    or the escape characters added for ``%`` would be doubled — keeps the
+    search behaving the way the search box implies.
+    """
+    escaped = (
+        keyword.replace(LIKE_ESCAPE, LIKE_ESCAPE * 2)
+        .replace("%", f"{LIKE_ESCAPE}%")
+        .replace("_", f"{LIKE_ESCAPE}_")
+    )
+    return f"%{escaped}%"

backend/app/crud/paper_template.py

@@ -0,0 +1,180 @@
+"""Data access for paper templates and their ordered field selections."""
+
+from collections.abc import Sequence
+
+from sqlalchemy import func, or_, select
+from sqlalchemy.orm import Session
+
+from app.crud.filters import LIKE_ESCAPE, like_pattern
+from app.models import PaperTemplate, SectionField, TemplateField
+from app.schemas.paper_template import PaperTemplateListItem, TemplateFieldInput
+
+
+def _conditions(keyword: str | None) -> list:
+    """Search both the name and the abstract from one box."""
+    if not keyword:
+        return []
+    pattern = like_pattern(keyword)
+    return [
+        or_(
+            PaperTemplate.name.like(pattern, escape=LIKE_ESCAPE),
+            PaperTemplate.abstract.like(pattern, escape=LIKE_ESCAPE),
+        )
+    ]
+
+
+def _field_count_column():
+    """A correlated ``COUNT`` of the template's placement rows."""
+    return (
+        select(func.count(TemplateField.id))
+        .where(TemplateField.template_id == PaperTemplate.id)
+        .correlate(PaperTemplate)
+        .scalar_subquery()
+    )
+
+
+def list_templates(
+    db: Session,
+    *,
+    keyword: str | None = None,
+    page: int = 1,
+    page_size: int = 20,
+) -> tuple[list[PaperTemplateListItem], int]:
+    """Return one page of templates with their field counts, plus the total.
+
+    The outline itself is left out: a table row needs the count, not the rows.
+    Recently edited templates come first, since that is what a user returns to.
+    """
+    conditions = _conditions(keyword)
+
+    total = db.scalar(
+        select(func.count(PaperTemplate.id)).where(*conditions)
+    ) or 0
+
+    stmt = (
+        select(PaperTemplate, _field_count_column().label("field_count"))
+        .where(*conditions)
+        .order_by(PaperTemplate.updated_at.desc(), PaperTemplate.id.desc())
+        .offset((page - 1) * page_size)
+        .limit(page_size)
+    )
+
+    items = [
+        PaperTemplateListItem(
+            id=template.id,
+            name=template.name,
+            abstract=template.abstract,
+            field_count=field_count,
+            created_at=template.created_at,
+            updated_at=template.updated_at,
+        )
+        for template, field_count in db.execute(stmt).all()
+    ]
+    return items, total
+
+
+def get(db: Session, template_id: int) -> PaperTemplate | None:
+    """Return one template with its outline already loaded, or ``None``.
+
+    ``items`` (ordered by ``sort``) and each item's ``field`` are both
+    configured for eager loading on the relationships, so this is a fixed
+    number of queries rather than one per field.
+    """
+    return db.get(PaperTemplate, template_id)
+
+
+def name_taken(db: Session, name: str, *, exclude_id: int | None = None) -> bool:
+    """Whether another template already uses ``name``."""
+    stmt = select(func.count(PaperTemplate.id)).where(PaperTemplate.name == name)
+    if exclude_id is not None:
+        stmt = stmt.where(PaperTemplate.id != exclude_id)
+    return bool(db.scalar(stmt))
+
+
+def missing_field_ids(db: Session, field_ids: Sequence[int]) -> list[int]:
+    """Which of ``field_ids`` do not exist in the field library.
+
+    Returning the offenders rather than a boolean lets the API name them, which
+    is the difference between a usable error and "invalid request".
+    """
+    wanted = set(field_ids)
+    if not wanted:
+        return []
+    found = set(
+        db.scalars(select(SectionField.id).where(SectionField.id.in_(wanted))).all()
+    )
+    return sorted(wanted - found)
+
+
+def _build_items(fields: Sequence[TemplateFieldInput]) -> list[TemplateField]:
+    """Materialise the client's selection into placement rows."""
+    return [TemplateField(field_id=item.field_id, sort=item.sort) for item in fields]
+
+
+def create(
+    db: Session,
+    *,
+    name: str,
+    abstract: str | None,
+    fields: Sequence[TemplateFieldInput],
+) -> PaperTemplate:
+    """Insert a template together with its ordered selection."""
+    template = PaperTemplate(name=name, abstract=abstract)
+    template.items = _build_items(fields)
+    db.add(template)
+    db.commit()
+    db.refresh(template)
+    return template
+
+
+def update(
+    db: Session,
+    template: PaperTemplate,
+    *,
+    name: str | None = None,
+    abstract: str | None = None,
+    abstract_provided: bool = False,
+    fields: Sequence[TemplateFieldInput] | None = None,
+) -> PaperTemplate:
+    """Apply a partial update. ``fields=None`` leaves the selection untouched.
+
+    ``abstract_provided`` distinguishes "clear the abstract" from "leave it" —
+    both arrive as ``None`` in the payload, and only the caller knows which the
+    client meant.
+    """
+    if name is not None:
+        template.name = name
+    if abstract_provided:
+        template.abstract = abstract
+    if fields is not None:
+        # delete-orphan removes the dropped rows on flush. TiDB does not
+        # enforce ON DELETE CASCADE, so this ORM-level cascade is the only
+        # thing cleaning up the join table.
+        template.items.clear()
+        db.flush()
+        template.items.extend(_build_items(fields))
+
+    db.commit()
+    db.refresh(template)
+    return template
+
+
+def delete(db: Session, template: PaperTemplate) -> None:
+    """Delete a template and its placement rows."""
+    db.delete(template)
+    db.commit()
+
+
+def delete_many(db: Session, template_ids: Sequence[int]) -> int:
+    """Delete several templates, returning how many actually existed."""
+    if not template_ids:
+        return 0
+    templates = list(
+        db.scalars(
+            select(PaperTemplate).where(PaperTemplate.id.in_(list(template_ids)))
+        ).all()
+    )
+    for template in templates:
+        db.delete(template)
+    db.commit()
+    return len(templates)

backend/app/crud/section_field.py

@@ -0,0 +1,118 @@
+"""Data access for the reusable section-field library (字段管理)."""
+
+from collections.abc import Sequence
+
+from sqlalchemy import Select, func, select
+from sqlalchemy.orm import Session
+
+from app.crud.filters import LIKE_ESCAPE, like_pattern
+from app.models import SectionField, TemplateField
+from app.schemas.section_field import SectionFieldCreate, SectionFieldUpdate
+
+
+def _conditions(keyword: str | None, level: int | None) -> list:
+    """Translate the list filters into SQLAlchemy predicates."""
+    conditions = []
+    if keyword:
+        conditions.append(
+            SectionField.name.like(like_pattern(keyword), escape=LIKE_ESCAPE)
+        )
+    if level is not None:
+        conditions.append(SectionField.level == level)
+    return conditions
+
+
+def _ordered(stmt: Select) -> Select:
+    """Apply the library's canonical browse order.
+
+    Grouped by ``level`` first so the picker reads as an outline, then by
+    insertion order so a field stays where the user put it. Deliberately *not*
+    ordered by ``name``: names carry hand-written numbering ("1.", "10.",
+    "2."), and string ordering would scramble it.
+    """
+    return stmt.order_by(SectionField.level.asc(), SectionField.id.asc())
+
+
+def list_fields(
+    db: Session,
+    *,
+    keyword: str | None = None,
+    level: int | None = None,
+    page: int = 1,
+    page_size: int = 20,
+) -> tuple[list[SectionField], int]:
+    """Return one page of the field library, plus the unpaged total."""
+    conditions = _conditions(keyword, level)
+
+    total = db.scalar(
+        select(func.count(SectionField.id)).where(*conditions)
+    ) or 0
+
+    stmt = _ordered(
+        select(SectionField)
+        .where(*conditions)
+        .offset((page - 1) * page_size)
+        .limit(page_size)
+    )
+    return list(db.scalars(stmt).all()), total
+
+
+def get(db: Session, field_id: int) -> SectionField | None:
+    """Return one field, or ``None``."""
+    return db.get(SectionField, field_id)
+
+
+def get_many(db: Session, field_ids: Sequence[int]) -> list[SectionField]:
+    """Return every field whose id is in ``field_ids`` (missing ids ignored)."""
+    if not field_ids:
+        return []
+    stmt = select(SectionField).where(SectionField.id.in_(list(field_ids)))
+    return list(db.scalars(stmt).all())
+
+
+def usage_counts(db: Session, field_ids: Sequence[int]) -> dict[int, int]:
+    """Count how many *distinct templates* place each field.
+
+    Drives the refusal message when a field in use is deleted. ``DISTINCT``
+    matters because one template may legitimately place the same field twice.
+    """
+    if not field_ids:
+        return {}
+    stmt = (
+        select(
+            TemplateField.field_id,
+            func.count(func.distinct(TemplateField.template_id)),
+        )
+        .where(TemplateField.field_id.in_(list(field_ids)))
+        .group_by(TemplateField.field_id)
+    )
+    return {field_id: count for field_id, count in db.execute(stmt).all()}
+
+
+def create(db: Session, data: SectionFieldCreate) -> SectionField:
+    """Insert a field."""
+    field = SectionField(**data.model_dump())
+    db.add(field)
+    db.commit()
+    db.refresh(field)
+    return field
+
+
+def update(db: Session, field: SectionField, data: SectionFieldUpdate) -> SectionField:
+    """Apply a partial update to a field.
+
+    ``exclude_unset`` is what makes PATCH semantics work: a key the client did
+    not send leaves the column alone, while an explicit ``null`` — which the
+    schemas reject for every nullable-typed column here — would not.
+    """
+    for key, value in data.model_dump(exclude_unset=True).items():
+        setattr(field, key, value)
+    db.commit()
+    db.refresh(field)
+    return field
+
+
+def delete(db: Session, field: SectionField) -> None:
+    """Delete a field. Callers must check :func:`usage_counts` first."""
+    db.delete(field)
+    db.commit()