Files
paper-doc/backend/alembic/versions/b19e4d7a3c58_rename_template_tables_to_titles.py
govin 199e328b48 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.
2026-09-22 16:55:02 +08:00

123 lines
4.8 KiB
Python

"""rename the template tables and columns to the title vocabulary
Three names described the same thing by different words, so the schema read as
if it held four concepts:
template_field_library the catalogue of reusable headings (字段库)
template_field one heading placed in one template, with its sort
``template_field`` is one word away from ``template_field_library`` and means
the opposite kind of thing — a row versus the catalogue of rows — and neither
name says 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. So the library becomes
``template_title`` and the placement becomes ``template_title_placement``, and
the placement's reference to the library becomes ``title_id``. The name now says
which is the catalogue and which is a placement, which is the distinction the
old pair hid.
template_title one reusable heading (字段库)
template_title_placement that heading placed in a template, with `sort`
Nothing else moves: ``template`` keeps its name, and every row in every table is
preserved. ``RENAME TABLE`` moves the data in place, and TiDB carries a
referencing foreign key along with both a renamed table and a renamed column
(rehearsed against the cluster before this revision was written), so the
constraint in ``template_title_placement`` follows without a drop/recreate step
and stays enforced.
Revision ID: b19e4d7a3c58
Revises: a83f5c21d7b6
Create Date: 2026-09-22
"""
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
# revision identifiers, used by Alembic.
revision: str = "b19e4d7a3c58"
down_revision: str | None = "a83f5c21d7b6"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
#: (old, new) index names on the placement table. They embed the table name and
#: the column name, so both renames have to reach them or the schema ends up
#: with indexes named after tables that no longer exist.
_INDEXES = (
("ix_template_field_field_id", "ix_template_title_placement_title_id"),
("ix_template_field_template_sort", "ix_template_title_placement_template_sort"),
)
#: Index names that already say the new thing, so a rerun leaves them alone.
_NEW_INDEXES = {new for _, new in _INDEXES}
def upgrade() -> None:
"""Rename in place, tolerating a database where part of it already ran.
Each step is guarded by what the database actually holds, rather than
assuming a clean start. That is not decoration: the first attempt at this
revision renamed the two tables and then failed on the column, because
Alembic's MySQL dialect wants an explicit type for ``alter_column`` and
won't rename a column without one. A migration that re-runs is the only way
to finish a database left in that state, and it costs three dict lookups to
be able to.
"""
bind = op.get_bind()
inspector = sa.inspect(bind)
tables = set(inspector.get_table_names())
if "template_field_library" in tables:
op.rename_table("template_field_library", "template_title")
if "template_field" in tables:
op.rename_table("template_field", "template_title_placement")
columns = {
column["name"]
for column in inspector.get_columns("template_title_placement")
}
if "field_id" in columns:
# Raw SQL rather than ``op.alter_column``: TiDB supports
# ``RENAME COLUMN`` directly, and the Alembic spelling goes through
# ``CHANGE COLUMN``, which demands the current type be repeated.
op.execute(
"ALTER TABLE template_title_placement RENAME COLUMN field_id TO title_id"
)
indexes = {index["name"] for index in inspector.get_indexes("template_title_placement")}
for old, new in _INDEXES:
if old in indexes and new not in indexes:
op.execute(
f"ALTER TABLE template_title_placement RENAME INDEX {old} TO {new}"
)
def downgrade() -> None:
bind = op.get_bind()
inspector = sa.inspect(bind)
indexes = {
index["name"]
for index in inspector.get_indexes("template_title_placement")
}
for old, new in _INDEXES:
if new in indexes and old not in indexes:
op.execute(
f"ALTER TABLE template_title_placement RENAME INDEX {new} TO {old}"
)
columns = {
column["name"]
for column in inspector.get_columns("template_title_placement")
}
if "title_id" in columns:
op.execute(
"ALTER TABLE template_title_placement RENAME COLUMN title_id TO field_id"
)
op.rename_table("template_title_placement", "template_field")
op.rename_table("template_title", "template_field_library")