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:
+61
-37
@@ -62,15 +62,15 @@ Six tables. Every one is prefixed with the module it belongs to, and a model
|
||||
class is named after its table, so the schema can be read as three groups:
|
||||
|
||||
```
|
||||
template_field_library the 字段库: reusable headings
|
||||
template_title one reusable heading (字段库)
|
||||
id, name, level, font_size, font_color
|
||||
|
||||
template a named outline (模板)
|
||||
id, name, abstract
|
||||
|
||||
template_field a field placed in a template — and the only
|
||||
id, template_id → template, home of display order
|
||||
field_id → template_field_library, sort
|
||||
template_title_placement that heading placed in a template — and the
|
||||
id, template_id → template, only home of display order
|
||||
title_id → template_title, sort
|
||||
|
||||
paper the document
|
||||
id, title, template_id, author, status, keywords, target_journal
|
||||
@@ -82,6 +82,29 @@ paper_sentence_reference the citations of one sentence
|
||||
id, sentence_id → paper_sentence, reference_id, quote, sort
|
||||
```
|
||||
|
||||
### How the tables are named
|
||||
|
||||
Three rules, applied everywhere:
|
||||
|
||||
1. **A table is its module's name plus what it holds** — `template*` belongs to
|
||||
the 模板 module, `paper*` to the 论文 module.
|
||||
2. **A class is named after its table** (`TemplateTitle` → `template_title`), so
|
||||
reading a class name tells you which table to look at.
|
||||
3. **One concept, one word.** The library entry, the placement and the paper's
|
||||
paragraph are three different things and never share a name.
|
||||
|
||||
The join table is a *placement* rather than a `_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. Calling it a link
|
||||
would describe two foreign keys and hide the column the whole ordering rule
|
||||
rests on.
|
||||
|
||||
`template_title` and `template_title_placement` are one word apart on purpose —
|
||||
the first is the catalogue, the second is one use of it — and the earlier pair
|
||||
(`template_field_library` / `template_field`) hid that distinction behind a
|
||||
prefix that meant the opposite kind of thing. Revision `b19e4d7a3c58` renamed
|
||||
them.
|
||||
|
||||
`paper` has no `abstract` column, and that is a decision rather than an
|
||||
omission. A paper's abstract *is* a paragraph of its body — the template's
|
||||
`0 Abstract` field — so it has a position in the document, the heading and
|
||||
@@ -92,38 +115,39 @@ and the one in the column could drift from the one in the body. Revision
|
||||
`a83f5c21d7b6` removed it, moving each stored abstract into the abstract
|
||||
paragraph first.
|
||||
|
||||
`template_field` and `template_field_library` 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* the field was picked from,
|
||||
shared by every template and owned by none. The library is managed from the
|
||||
模板 menu, because it is the raw material a template is built out of.
|
||||
The two template tables are one word apart and mean different things, which is
|
||||
what the names are for: `template_title_placement` is a *placement* — this
|
||||
template puts this title here, `sort` included — while `template_title` is the
|
||||
*catalogue* the title was picked from, shared by every template and owned by
|
||||
none. The library is managed from the 模板 menu, because it is the raw material
|
||||
a template is built out of.
|
||||
|
||||
### The field library is flat, not a tree
|
||||
### The title library is flat, not a tree
|
||||
|
||||
`template_field_library` has no `parent_id`. Hierarchy is expressed only by `level`
|
||||
`template_title` has no `parent_id`. Hierarchy is expressed only by `level`
|
||||
(1 for `1.`, 2 for `1.1`), which is a *rendering hint*: it drives indentation
|
||||
and numbering semantics in the UI and nothing else.
|
||||
|
||||
The reason is reuse. With a parent pointer a level-2 heading would belong to
|
||||
exactly one level-1 heading, so "Background" could not sit under both
|
||||
`1. Introduction` and `2. Related Work`. Flat fields are attached to templates,
|
||||
not to each other, so one field can appear in any number of templates, in a
|
||||
`1. Introduction` and `2. Related Work`. Titles are attached to templates,
|
||||
not to each other, so one title can appear in any number of templates, in a
|
||||
different position in each.
|
||||
|
||||
The numbering a reader sees is part of `name` and is written by the user
|
||||
(`"1. Introduction"`, `"0 Abstract"`). Nothing derives or rewrites it.
|
||||
|
||||
### Display order lives in the join table
|
||||
### Display order lives in the placement table
|
||||
|
||||
`template_field.sort` is a plain ascending integer and is the **only** thing
|
||||
that decides what order a template's fields appear in. The order the user
|
||||
clicked fields in is never stored, so selecting `字段1, 字段2.1, 字段2, 字段1.1`
|
||||
and setting sorts `1, 4, 3, 2` renders as `字段1, 字段1.1, 字段2, 字段2.1`.
|
||||
`template_title_placement.sort` is a plain ascending integer and is the **only**
|
||||
thing that decides what order a template's titles appear in. The order the user
|
||||
clicked titles in is never stored, so selecting `标题1, 标题2.1, 标题2, 标题1.1`
|
||||
and setting sorts `1, 4, 3, 2` renders as `标题1, 标题1.1, 标题2, 标题2.1`.
|
||||
|
||||
Two consequences are deliberate:
|
||||
|
||||
- **There is no unique constraint on `(template_id, field_id)`.** Placing the
|
||||
same field twice in one template is a legitimate layout — the same level-2
|
||||
- **There is no unique constraint on `(template_id, title_id)`.** Placing the
|
||||
same title twice in one template is a legitimate layout — the same level-2
|
||||
heading under two different level-1 headings. The UI warns about a repeat; it
|
||||
does not forbid one.
|
||||
- **Ties are legal.** Equal `sort` values are broken by insertion order, so the
|
||||
@@ -132,16 +156,16 @@ Two consequences are deliberate:
|
||||
|
||||
### Templates hold references, not copies
|
||||
|
||||
`template_field` points at a library field; it does not snapshot its name or
|
||||
typography. Renaming or restyling a field therefore updates every template that
|
||||
places it, which is what makes "fix the template and the section names follow"
|
||||
work.
|
||||
`template_title_placement` points at a library title; it does not snapshot its
|
||||
name or typography. Renaming or restyling a title therefore updates every
|
||||
template that places it, which is what makes "fix the template and the section
|
||||
names follow" work.
|
||||
|
||||
### A sentence is addressed by position, not by field id
|
||||
|
||||
`paper_sentence.paper_template_filed_sort` holds the `sort` of the template
|
||||
placement the sentence belongs to — **not** `template_field.id`, and not
|
||||
`template_field_library.id`. Together with `sort`, the sentence's own position inside
|
||||
placement the sentence belongs to — **not** `template_title_placement.id`, and not
|
||||
`template_title.id`. Together with `sort`, the sentence's own position inside
|
||||
that paragraph, it is everything needed to place a line of text.
|
||||
|
||||
The indirection is the feature. Two templates have no rows in common, but they
|
||||
@@ -160,12 +184,12 @@ Three behaviours fall out of that one choice:
|
||||
still rendered, in their place in the order, under the heading 未设定. Switch
|
||||
back and the old headings return, because the sentences never moved.
|
||||
- **Ties and gaps are fine.** Sentences may share a `sort` (broken by `id`) and
|
||||
may be numbered `10, 20, 30` to leave room, exactly as `template_field.sort`
|
||||
may be numbered `10, 20, 30` to leave room, exactly as `template_title_placement.sort`
|
||||
allows.
|
||||
|
||||
The name `paper_template_filed_sort` keeps the spelling the feature was
|
||||
specified with; it is the template field's `sort` (the `sort` column of
|
||||
`template_field`). `paper_sentence.template_id` is the template the sentence was
|
||||
`template_title_placement`). `paper_sentence.template_id` is the template the sentence was
|
||||
written against. It is kept in step with the paper's current template and is
|
||||
provenance rather than a lookup key: rendering never filters on it, which is
|
||||
precisely why content survives a switch.
|
||||
@@ -263,10 +287,10 @@ All routes are mounted under `/api`. Interactive docs at `/docs`.
|
||||
| Method | Path | Notes |
|
||||
|---|---|---|
|
||||
| `GET` | `/health` | liveness plus a TiDB probe |
|
||||
| `GET` | `/template-field-library` | `keyword`, `level`, `page`, `page_size` |
|
||||
| `POST` | `/template-field-library` | create a library entry |
|
||||
| `GET` `PATCH` `DELETE` | `/template-field-library/{id}` | read / partial update / delete |
|
||||
| `POST` | `/template-field-library/batch-delete` | body `{ "ids": [...] }` |
|
||||
| `GET` | `/template-titles` | `keyword`, `level`, `page`, `page_size` |
|
||||
| `POST` | `/template-titles` | create a library entry |
|
||||
| `GET` `PATCH` `DELETE` | `/template-titles/{id}` | read / partial update / delete |
|
||||
| `POST` | `/template-titles/batch-delete` | body `{ "ids": [...] }` |
|
||||
| `GET` | `/templates` | `keyword` matches name **or** abstract |
|
||||
| `POST` | `/templates` | name + abstract + ordered `fields` |
|
||||
| `GET` `PATCH` `DELETE` | `/templates/{id}` | `PATCH` with `fields` replaces the selection |
|
||||
@@ -290,7 +314,7 @@ Conventions worth knowing:
|
||||
- List endpoints return `{ items, total, page, page_size, pages }`.
|
||||
- A template read returns `fields` already ordered by `sort`; clients never sort.
|
||||
- Route paths mirror table names one for one: `/templates` for `template`,
|
||||
`/template-field-library` for `template_field_library`, `/papers` for
|
||||
`/template-titles` for `template_title`, `/papers` for
|
||||
`paper`.
|
||||
- A paper document returns its `paragraphs` in ascending position order,
|
||||
already carrying their sentences and citation numbering. The client sorts
|
||||
@@ -451,7 +475,7 @@ are not lists (the paper document) keep scrolling normally.
|
||||
| `/papers/:id` | one paper, read as a document | `papers` |
|
||||
| `/templates` | redirects to `/templates/list` | — |
|
||||
| `/templates/list` | template table + CRUD | `templates` |
|
||||
| `/templates/fields` | field library + CRUD | `templates` |
|
||||
| `/templates/fields` | title library + CRUD (the UI label is 字段管理) | `templates` |
|
||||
|
||||
### The paper view
|
||||
|
||||
@@ -479,7 +503,7 @@ paper-doc/
|
||||
├── backend/ # FastAPI application
|
||||
│ ├── app/
|
||||
│ │ ├── api/routes/ # route handlers (health, papers, templates,
|
||||
│ │ │ # template_field_library)
|
||||
│ │ │ # template_title)
|
||||
│ │ ├── core/ # settings and configuration
|
||||
│ │ ├── crud/ # data-access helpers
|
||||
│ │ ├── db/ # engine, session, declarative base
|
||||
@@ -487,7 +511,7 @@ paper-doc/
|
||||
│ │ ├── models/ # SQLAlchemy models
|
||||
│ │ └── schemas/ # Pydantic request/response models
|
||||
│ ├── alembic/ # migration environment and revisions
|
||||
│ ├── scripts/seed.py # idempotent seed for the field library + templates
|
||||
│ ├── scripts/seed.py # idempotent seed for the title library + templates
|
||||
│ ├── scripts/smoke_papers.py # end-to-end check of the writing loop
|
||||
│ ├── scripts/mcp_server.py # MCP entry point (stdio / http)
|
||||
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
|
||||
@@ -557,7 +581,7 @@ alembic upgrade head
|
||||
|
||||
**Seed data**
|
||||
|
||||
`scripts/seed.py` fills the field library with a standard academic outline (20
|
||||
`scripts/seed.py` fills the title library with a standard academic outline (20
|
||||
fields, from `0 Abstract` to `7 References`) and creates three starter
|
||||
templates. It matches fields and templates by name, so running it twice adds
|
||||
nothing:
|
||||
|
||||
Reference in New Issue
Block a user