docs: describe the tags, the library pages, and the way in

Ten tables now, and the two new ones are argued for where the other
schema decisions are: why a tag is not a keyword, why the link is bare,
why a tag is made before it is applied, and why deleting one is not
refused while deleting a cited reference is.

Also corrects the table count — the section claimed nine while listing
eight — and the shell diagram, which had a header with two entries and
named the wrong side for the second-level menu.
This commit is contained in:
2026-09-22 17:55:23 +08:00
parent 872ad8cf3b
commit a29badd362
+138 -37
View File
@@ -58,7 +58,7 @@ Browser ──HTTP/JSON──▶ FastAPI ──SQLAlchemy──▶ TiDB (k3s)
## Domain Model
Nine tables. Every one is prefixed with the module it belongs to, and a model
Ten 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 four groups:
```
@@ -87,6 +87,13 @@ reference the 参考文献 module: the literature itself
reference_author its contributors, in print order
id, reference_id → reference, sort, name, family_name, given_name, role
reference_tag the writer's own labels (文献标签)
id, name (unique), color, note
reference_tag_link which literature carries which label
reference_id → reference, — the pair is the primary key and the
tag_id → reference_tag row holds nothing else
```
### How the tables are named
@@ -244,6 +251,39 @@ The 103 CSL fields include roles this project will never print (narrator,
performer, curator) and archival fields (call-number, archive-place). They are
left out on purpose; see :mod:`app.models.reference`.
### Tags are the writer's filing, not the document's keywords
``reference.keywords`` is a field of the *document* — the 关键词 printed on the
article, transcribed because a citation record should be able to reproduce it.
A tag is a fact about the *writer*: 「综述」, 「必读」, 「待精读」, the labels that
narrow a library of a few hundred entries to the handful that matter for the
paragraph being written. They never print, one document carries several, and the
same label is on many documents. Two different facts with two different
lifetimes cannot share a column, so labels live in their own two tables:
```
reference_tag one label: name (unique), colour, note
reference_tag_link reference_id + tag_id — the pair is the primary key
```
The link table is named ``_link`` and not ``_placement`` for the reason
``template_title_placement`` is not: it carries nothing of its own. There is no
``sort`` here, so the pair *is* the row — which also means the same label cannot
be applied to the same document twice, and that is a property of the key rather
than a rule anyone has to remember to enforce.
**A tag is made first and applied second.** A reference is created with
``tag_ids``, never with tag names, so a typo cannot invent a label and two
clients cannot create two spellings of one. An id the library does not have is
refused with ``400`` naming it, and nothing is written.
**Deleting a tag is not guarded, deliberately.** Both foreign keys cascade, so
removing a label removes labels and leaves the literature where it was. That is
the opposite of deleting a *cited reference*, which is refused with ``409``: a
citation is a claim the paper makes, while a label is only a way of finding the
row again. The confirmation in the UI says how many entries will lose the label,
which is the honest form of that warning.
### A sentence is a line, not parsed text
Nothing in the writing path splits text. There is no sentence detector, no
@@ -349,11 +389,15 @@ All routes are mounted under `/api`. Interactive docs at `/docs`.
| `POST` | `/papers` | title + template + author/status/keywords/journal; no sentence rows are created |
| `GET` `PATCH` `DELETE` | `/papers/{id}` | `PATCH` with `template_id` **is** the template switch |
| `POST` | `/papers/batch-delete` | body `{ "ids": [...] }` |
| `GET` | `/references` | `keyword` (题名/刊名/作者/DOI/关键词/备注), `type`, `year`, `cited` |
| `POST` | `/references` | the whole entry, `authors` in print order |
| `GET` `PATCH` `DELETE` | `/references/{id}` | `PATCH` with `authors` replaces the list |
| `GET` | `/references` | `keyword` (题名/刊名/作者/DOI/关键词/备注), `type`, `year`, `cited`, `tag` |
| `POST` | `/references` | the whole entry, `authors` in print order, `tag_ids` to label it |
| `GET` `PATCH` `DELETE` | `/references/{id}` | `PATCH` with `authors` or `tag_ids` replaces that list |
| `POST` | `/references/batch-delete` | body `{ "ids": [...] }` |
| `GET` | `/references/{id}/citations` | which sentences cite it, and in which paragraph |
| `GET` | `/reference-tags` | `keyword` matches 标签名称 **or** 备注; each row carries its 文献数 |
| `POST` | `/reference-tags` | name is unique — a duplicate is `409` naming it |
| `GET` `PATCH` `DELETE` | `/reference-tags/{id}` | renaming follows every reference carrying it |
| `POST` | `/reference-tags/batch-delete` | body `{ "ids": [...] }`; unlabels, never deletes literature |
| `GET` | `/papers/{id}/document` | the whole paper: paragraphs in order, citations, warnings |
| `GET` | `/papers/{id}/paragraphs/{sort}` | one paragraph, assembled as the document renders it |
| `PUT` | `/papers/{id}/paragraphs/{sort}` | full replacement; optional `target_sort` moves it |
@@ -388,6 +432,15 @@ Conventions worth knowing:
quote may be written before it is linked.
- Deleting a reference a sentence cites is refused with `409`, naming the entry
and how many citations use it.
- Applying a tag that does not exist is a `400` naming the ids, not a
foreign-key error: the library is checked before the write, and a reference
naming a label that is not there is refused whole rather than stored
half-labelled.
- Deleting a tag is **not** refused. The label rows go and the literature stays,
because a label is the writer's filing rather than a claim the paper makes.
- `tag` may be given more than once, and the filters narrow rather than widen:
`?tag=1&tag=2` returns the rows carrying **both** labels, which is how the
rail's labels compose with the toolbar's.
- A DOI is stored without its ``https://doi.org/`` prefix, so the column holds
one spelling whichever way it was pasted.
@@ -447,29 +500,41 @@ nothing.
### Shell
```
┌───────────────────┬──────────────────────────────────────┐
│ [mark] paper-doc │ 论文 模板 [mk] │ header
├───────────────────┼──────────────────────────────────────┤
│ 论文 │ │ second-level
│ 论文列表 │ <RouterView> │ menu, left
│ 新建论文 │ │
│ ── 我的论文 ── │ │
│ ● 论文标题 A │ │
│ ● 论文标题 B │ │
└───────────────────┴──────────────────────────────────────┘
<- 208px ->
┌───────────────────────────┬──────────────────────────────────────┐
│ [mark] paper-doc │ 论文 模板 参考文献 [mk] │ header
├───────────────────────────┼──────────────────────────────────────┤
│ 论文 │ │ second-level
│ 论文列表 │ <RouterView> │ menu, left
│ 新建论文 │ │
│ ── 我的论文 ── │ │
│ ● 论文标题 A │ │
│ ● 论文标题 B │ │
└───────────────────────────┴──────────────────────────────────────┘
<- 208px ->
```
The mark appears at both ends of the header. The second-level menu sits on the
**left** and is driven by `route.meta.section`, so a route declares which menu
it belongs to and deep links render correctly on first paint. Routes without a
`section` (the welcome page) show no menu.
The mark appears at both ends of the header. The three top-level entries are the
two surfaces a paper is worked *in* — 论文 and 模板 — and, marked out to their
right, 参考文献: the library is drawn *from* rather than worked in, so it is a
button one step away instead of a third thing to choose between (§ the rail
lists what is in it).
The 论文 menu is the one that is not a static list: it carries the papers
themselves, read from the `papers` store, so a paper can be opened straight from
the rail. Every page that creates, renames or deletes a paper reloads that
store, which is what keeps the rail and the table showing the same thing. A
filter box appears once there are more than six papers.
The second-level menu sits on the **left** and is driven by `route.meta.section`,
so a route declares which menu it belongs to and deep links render correctly on
first paint. Routes without a `section` (the welcome page) show no menu.
Two menus are not static lists, and both carry real data rather than links. 论文
lists the papers themselves, read from the `papers` store, so a paper can be
opened straight from the rail. 参考文献 lists the tags, read from the
`referenceTags` store, so a label can be picked straight from the rail — and
because both are driven by their stores, every page that creates, renames or
deletes one reloads it, which is what keeps the rail and the table showing the
same thing. Each rail grows a filter box once its list passes six entries.
A tag in the rail links to `/references?tag=<id>`, which makes the query
parameter part of the *view* rather than a hidden filter state:
`SectionAside` highlights that entry by matching the parameter, and the table's
own tag selector writes the same parameter back.
Two things about this layout are deliberate and easy to break by accident:
@@ -499,10 +564,10 @@ stylesheet.
A table is the page. Left alone it is as tall as its rows, so on a large screen
most of the window sits empty below the last row while the *page* is still the
thing that scrolls — the wrong half of the screen moving for a list that should
simply show more. The three list pages (`/papers`, `/templates/list`,
`/templates/fields`) therefore stretch the table to the height the window
offers, with the toolbar above it and the pagination below it staying put while
the rows scroll inside the table.
simply show more. The five list pages (`/papers`, `/templates/list`,
`/templates/fields`, `/references`, `/references/tags`) therefore stretch the
table to the height the window offers, with the toolbar above it and the
pagination below it staying put while the rows scroll inside the table.
It is CSS only — no resize listener, no measured pixel height, nothing to go
stale when the rail collapses or the window changes. Four links carry it, and
@@ -539,6 +604,8 @@ are not lists (the paper document) keep scrolling normally.
| `/templates` | redirects to `/templates/list` | — |
| `/templates/list` | template table + CRUD | `templates` |
| `/templates/fields` | title library + CRUD (the UI label is 字段管理) | `templates` |
| `/references` | reference table + CRUD (`?tag=<id>` filters, `?new=1` opens the create dialog) | `references` |
| `/references/tags` | tag library + CRUD (the UI label is 标签管理) | `references` |
### The paper view
@@ -559,14 +626,42 @@ alone knows how to do:
Changing a paper's template from the metadata form is deliberately disabled: a
silent re-shape of the document is exactly what the preview exists to prevent.
### The reference library view
`references/ReferenceListView` is the library and `references/TagManageView` is
the label library beside it. Three things about the pair are decisions rather
than layout:
- **The tag filter lives in the URL.** The rail links to
`/references?tag=<id>` and the toolbar's selector writes the same parameter
back, so the two cannot disagree about which label is being looked at, the
rail can highlight it, and a filtered view is a link someone can be sent. The
page reads `route.query.tag`, which is why the filter survives a refresh and a
back-navigation.
- **The citation count is a door.** "Which of my sentences use this?" is the
question that decides whether an entry is safe to delete, and the count in the
row opens the answer (`ReferenceCitationsDialog`: the paper, the paragraph
heading, the sentence, and the quoted passage) rather than being a number to
interpret.
- **A tag is created before it is applied.** The form's picker offers the labels
that exist and allows a new name to be typed; that name is created through the
tag API *before* the reference is written, so no stored reference can point at
a label that is not there. The dialog says so, and links to 标签管理 for anyone
who would rather file first and tag second — which is the intended order.
The form itself is grouped by tab (基本信息 / 责任者 / 出版信息 / 标识与链接 /
摘要与备注) rather than listed flat: the field set is the union of what CSL,
GB/T 7714 and BibTeX need, and forty inputs in a column is a form nobody fills
in correctly.
## Directory Structure
```
paper-doc/
├── backend/ # FastAPI application
│ ├── app/
│ │ ├── api/routes/ # route handlers (health, papers, templates,
│ │ │ # template_title)
│ │ ├── api/routes/ # route handlers (health, papers, references,
│ │ │ # reference_tags, templates, template_title)
│ │ ├── core/ # settings and configuration
│ │ ├── crud/ # data-access helpers
│ │ ├── db/ # engine, session, declarative base
@@ -577,6 +672,7 @@ paper-doc/
│ ├── scripts/seed.py # idempotent seed for the title library + templates
│ ├── scripts/smoke_papers.py # end-to-end check of the writing loop
│ ├── scripts/smoke_references.py # end-to-end check of the reference library
│ │ # and its tags
│ ├── scripts/mcp_server.py # MCP entry point (stdio / http)
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
│ ├── alembic.ini
@@ -585,12 +681,15 @@ paper-doc/
├── frontend/ # Vue 3 SPA
│ ├── src/
│ │ ├── api/ # axios instance and endpoint modules
│ │ ├── components/ # shell, field, template and paper components
│ │ ├── components/ # shell, field, template, paper and reference
│ │ │ # components
│ │ ├── router/ # vue-router configuration
│ │ ├── stores/ # pinia stores (UI prefs persisted, the paper list not)
│ │ ├── stores/ # pinia stores (UI prefs persisted, the paper and
│ │ │ # tag lists not)
│ │ ├── styles/ # global reset and the shell viewport contract
│ │ ├── utils/ # formatting helpers
│ │ └── views/ # route-level components (papers/, templates/)
│ │ └── views/ # route-level components (papers/, references/,
│ │ # templates/)
│ ├── package.json
│ └── vite.config.ts
├── deploy/ # packaging and the k3s manifests
@@ -658,10 +757,12 @@ cd backend
**Checking the reference library end to end**
`scripts/smoke_references.py` adds literature, finds it again by author, type,
year and whether it has been cited, edits it, cites it from a sentence, looks
the citation up from the reference side, and checks that a cited entry cannot be
deleted. It cleans up after itself:
`scripts/smoke_references.py` makes the labels first, adds literature and tags
it, finds it again by author, type, year and tag, edits it, cites it from a
sentence, looks the citation up from the reference side, checks that a cited
entry cannot be deleted while a tag can, and checks that a tag id the library
does not have is refused by name rather than invented. It cleans up after
itself:
```bash
cd backend