refactor: call a heading a title, and its use a placement

`template_field_library` and `template_field` were one word apart and meant
opposite kinds of thing — a catalogue of rows versus one row — and neither name
said what a row actually is. Every row of the library is a **heading**: a piece
of text like 「1. Introduction」 with a level and typography, which is what the
reader sees at the top of a paragraph; and every row of the join table is that
heading *placed* in a template, `sort` included.

    template_field_library  -> template_title
    template_field          -> template_title_placement
    field_id (the column)   -> title_id
    TemplateFieldLibrary    -> TemplateTitle
    TemplateField           -> TemplateTitlePlacement

The join table keeps its own name rather than becoming `_link`, because it is
not a bare link: it carries `sort`, the only place display order is stored, and
it deliberately allows the same title twice in one template. `_link` would
describe two foreign keys and hide the column the ordering rule rests on.

Carried through every level, because a half-renamed layer is how the confusing
pair got there in the first place: HTTP paths (`/template-field-library` ->
`/template-titles`), the template payload (`fields`/`field_id` ->
`placements`/`title_id`, and `field_count` -> `placement_count`), the Pydantic
schemas, the CRUD modules, the seed script, the frontend API module and types,
and `docs/OVERVIEW.md`, which now states the naming rules outright.

Two deliberate exceptions:

* `paper_template_filed_sort` is untouched — it is a column of the paper module
  and is spelled as the feature was specified.
* The MCP tools keep their agent-facing names (`field_list`, `field_ids`, and
  the `fields`/`field_id` keys in their responses). Agents already call them by
  those names; the storage names they read underneath have changed.

The migration renames in place (data preserved: 4 templates, 45 titles, 63
placements) and is written to tolerate a database where part of it already ran,
which is not hypothetical — the first attempt renamed the tables and then failed
on the column, because Alembic's MySQL dialect wants an explicit type for
`alter_column` and will not rename a column without one. TiDB carries the
foreign key along with both the renamed table and the renamed column, rehearsed
against the cluster first, and it stays enforced.

Verified: seed re-runs clean, the paper smoke test's 45 checks and the MCP
smoke test's 47 pass, `vue-tsc` and the build are clean, and the UI was driven
in a headless browser through the template list, its preview drawer, the title
library page, the template form (which now posts `placements` with `title_id`)
and the paper document with no console errors.
This commit is contained in:
2026-09-22 16:55:02 +08:00
parent 3732e36e64
commit 199e328b48
40 changed files with 837 additions and 663 deletions
+7 -7
View File
@@ -14,13 +14,13 @@ Every table is prefixed with the module it belongs to, and a class is named
after its table (``Template`` -> ``template``):
template the 模板 module
template_field a field placed in a template, with its position
template_field_library the 字段库 the template module draws on
template_title_placement a field placed in a template, with its position
template_title the 字段库 the template module draws on
paper the 论文 module
paper_sentence one sentence of one paper
paper_sentence_reference a citation of one sentence
``template_field`` and ``template_field_library`` are one word apart and mean
``template_title_placement`` and ``template_title`` are one word apart and mean
opposite things: the first is a *placement* (this template puts this field
here, ``sort`` included), the second is the *catalogue* it was picked from.
"""
@@ -36,8 +36,8 @@ from app.models.paper import (
from app.models.paper_sentence import PaperSentence
from app.models.paper_sentence_reference import PaperSentenceReference
from app.models.template import Template
from app.models.template_field import TemplateField
from app.models.template_field_library import TemplateFieldLibrary
from app.models.template_title_placement import TemplateTitlePlacement
from app.models.template_title import TemplateTitle
__all__ = [
"PAPER_STATUSES",
@@ -48,7 +48,7 @@ __all__ = [
"PaperSentence",
"PaperSentenceReference",
"Template",
"TemplateField",
"TemplateFieldLibrary",
"TemplateTitlePlacement",
"TemplateTitle",
"TimestampMixin",
]
+1 -1
View File
@@ -9,7 +9,7 @@ A paper is a bag of metadata plus two things that are deliberately kept apart:
* its **content**, which lives in
:class:`~app.models.paper_sentence.PaperSentence` — one row per sentence,
addressed by the paragraph's ``sort`` inside that template rather than by a
foreign key to a ``template_field`` row.
foreign key to a ``template_title_placement`` row.
That second choice is what makes the promised workflow work. Because a sentence
remembers "I belong at position 7", not "I belong to placement #42", swapping
+2 -2
View File
@@ -5,12 +5,12 @@ whole design:
``paper_template_filed_sort``
The ``sort`` of the template placement this sentence belongs to — *not* a
foreign key to ``template_field``. It is deliberately the position rather
foreign key to ``template_title_placement``. It is deliberately the position rather
than the row id, because the position is the only thing two templates can
meaningfully have in common. Swap the paper's template and this sentence
lands on whatever the new template puts at that position, with no per
sentence editing. (The name keeps the spelling the feature was specified
with; it reads ``template_field_sort``.)
with; it reads ``template_title_placement_sort``.)
``sort``
Where this sentence sits *inside* that paragraph. A paragraph is reassembled
+8 -8
View File
@@ -1,10 +1,10 @@
"""Templates (模板表) — the outlines a paper can be written against.
A template is a named, ordered selection of library fields — the outline a
A template is a named, ordered selection of library titles — 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.template_field_library.TemplateFieldLibrary`,
so correcting a field's styling updates every template that uses it.
:class:`~app.models.template_title.TemplateTitle`,
so correcting a title's styling updates every template that uses it.
"""
from typing import TYPE_CHECKING
@@ -16,11 +16,11 @@ 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
from app.models.template_title_placement import TemplateTitlePlacement
class Template(TimestampMixin, Base):
"""A named outline: a template name, a summary, and its ordered fields."""
"""A named outline: a template name, a summary, and its ordered titles."""
__tablename__ = "template"
@@ -31,15 +31,15 @@ class Template(TimestampMixin, Base):
#: 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.
#: The template's placements, 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(
placements: Mapped[list["TemplateTitlePlacement"]] = relationship(
back_populates="template",
cascade="all, delete-orphan",
order_by="TemplateField.sort, TemplateField.id",
order_by="TemplateTitlePlacement.sort, TemplateTitlePlacement.id",
lazy="selectin",
)
@@ -9,7 +9,7 @@ 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:`TemplateFieldLibrary.level` (1, 2, 3 ...), which is a *rendering hint* — it
:attr:`TemplateTitle.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.
@@ -18,10 +18,10 @@ 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
``template_title_placement.sort``. This table has no ``sort`` column on purpose, so that
one library field can occupy a different position in every template.
Naming: the table is ``template_field_library`` and one row is one entry of it
Naming: the table is ``template_title`` and one row is one entry of it
— the class is named after the table, as everywhere else in this package. The
library is global, but it belongs to the 模板 module: it is the raw material a
template is built from, and it is managed from the same menu.
@@ -36,10 +36,10 @@ from app.db.base import Base
from app.models.mixins import TimestampMixin
class TemplateFieldLibrary(TimestampMixin, Base):
class TemplateTitle(TimestampMixin, Base):
"""A single reusable heading, with the typography it should render in."""
__tablename__ = "template_field_library"
__tablename__ = "template_title"
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
@@ -77,6 +77,6 @@ class TemplateFieldLibrary(TimestampMixin, Base):
def __repr__(self) -> str: # pragma: no cover - debugging aid
return (
f"<TemplateFieldLibrary id={self.id} name={self.name!r} "
f"<TemplateTitle id={self.id} name={self.name!r} "
f"level={self.level} color={self.font_color}>"
)
@@ -26,19 +26,19 @@ from app.db.base import Base
if TYPE_CHECKING: # pragma: no cover - typing only
from app.models.template import Template
from app.models.template_field_library import TemplateFieldLibrary
from app.models.template_title import TemplateTitle
class TemplateField(Base):
"""One placement of one library field inside one template."""
class TemplateTitlePlacement(Base):
"""One placement of one library title inside one template."""
__tablename__ = "template_field"
__tablename__ = "template_title_placement"
__table_args__ = (
# Every read is "the fields of template X, in order", so the index
# Every read is "the placements of template X, in order", so the index
# covers both the filter and the sort.
Index("ix_template_field_template_sort", "template_id", "sort"),
Index("ix_template_field_field_id", "field_id"),
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)
@@ -48,26 +48,26 @@ class TemplateField(Base):
nullable=False,
)
#: ``RESTRICT``: a field still placed in a template must not vanish from
#: under it. The API enforces this in Python as well, since TiDB does not
#: enforce foreign keys itself.
field_id: Mapped[int] = mapped_column(
ForeignKey("template_field_library.id", ondelete="RESTRICT"),
#: ``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 field's ``level``.
#: 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="items")
template: Mapped["Template"] = relationship(back_populates="placements")
#: Eager-loaded because every template read needs the field's name and
#: Eager-loaded because every template read needs the title's name and
#: typography; lazy loading would emit one query per row.
field: Mapped["TemplateFieldLibrary"] = relationship(lazy="joined")
title: Mapped["TemplateTitle"] = relationship(lazy="joined")
def __repr__(self) -> str: # pragma: no cover - debugging aid
return (
f"<TemplateField template_id={self.template_id} "
f"field_id={self.field_id} sort={self.sort}>"
f"<TemplateTitlePlacement template_id={self.template_id} "
f"title_id={self.title_id} sort={self.sort}>"
)