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:
+138
-37
@@ -58,7 +58,7 @@ Browser ──HTTP/JSON──▶ FastAPI ──SQLAlchemy──▶ TiDB (k3s)
|
|||||||
|
|
||||||
## Domain Model
|
## 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:
|
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
|
reference_author its contributors, in print order
|
||||||
id, reference_id → reference, sort, name, family_name, given_name, role
|
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
|
### 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
|
performer, curator) and archival fields (call-number, archive-place). They are
|
||||||
left out on purpose; see :mod:`app.models.reference`.
|
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
|
### A sentence is a line, not parsed text
|
||||||
|
|
||||||
Nothing in the writing path splits text. There is no sentence detector, no
|
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 |
|
| `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 |
|
| `GET` `PATCH` `DELETE` | `/papers/{id}` | `PATCH` with `template_id` **is** the template switch |
|
||||||
| `POST` | `/papers/batch-delete` | body `{ "ids": [...] }` |
|
| `POST` | `/papers/batch-delete` | body `{ "ids": [...] }` |
|
||||||
| `GET` | `/references` | `keyword` (题名/刊名/作者/DOI/关键词/备注), `type`, `year`, `cited` |
|
| `GET` | `/references` | `keyword` (题名/刊名/作者/DOI/关键词/备注), `type`, `year`, `cited`, `tag` |
|
||||||
| `POST` | `/references` | the whole entry, `authors` in print order |
|
| `POST` | `/references` | the whole entry, `authors` in print order, `tag_ids` to label it |
|
||||||
| `GET` `PATCH` `DELETE` | `/references/{id}` | `PATCH` with `authors` replaces the list |
|
| `GET` `PATCH` `DELETE` | `/references/{id}` | `PATCH` with `authors` or `tag_ids` replaces that list |
|
||||||
| `POST` | `/references/batch-delete` | body `{ "ids": [...] }` |
|
| `POST` | `/references/batch-delete` | body `{ "ids": [...] }` |
|
||||||
| `GET` | `/references/{id}/citations` | which sentences cite it, and in which paragraph |
|
| `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}/document` | the whole paper: paragraphs in order, citations, warnings |
|
||||||
| `GET` | `/papers/{id}/paragraphs/{sort}` | one paragraph, assembled as the document renders it |
|
| `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 |
|
| `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.
|
quote may be written before it is linked.
|
||||||
- Deleting a reference a sentence cites is refused with `409`, naming the entry
|
- Deleting a reference a sentence cites is refused with `409`, naming the entry
|
||||||
and how many citations use it.
|
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
|
- A DOI is stored without its ``https://doi.org/`` prefix, so the column holds
|
||||||
one spelling whichever way it was pasted.
|
one spelling whichever way it was pasted.
|
||||||
|
|
||||||
@@ -447,29 +500,41 @@ nothing.
|
|||||||
### Shell
|
### Shell
|
||||||
|
|
||||||
```
|
```
|
||||||
┌───────────────────┬──────────────────────────────────────┐
|
┌───────────────────────────┬──────────────────────────────────────┐
|
||||||
│ [mark] paper-doc │ 论文 模板 [mk] │ header
|
│ [mark] paper-doc │ 论文 模板 参考文献 [mk] │ header
|
||||||
├───────────────────┼──────────────────────────────────────┤
|
├───────────────────────────┼──────────────────────────────────────┤
|
||||||
│ 论文 │ │ second-level
|
│ 论文 │ │ second-level
|
||||||
│ 论文列表 │ <RouterView> │ menu, left
|
│ 论文列表 │ <RouterView> │ menu, left
|
||||||
│ 新建论文 │ │
|
│ 新建论文 │ │
|
||||||
│ ── 我的论文 ── │ │
|
│ ── 我的论文 ── │ │
|
||||||
│ ● 论文标题 A │ │
|
│ ● 论文标题 A │ │
|
||||||
│ ● 论文标题 B │ │
|
│ ● 论文标题 B │ │
|
||||||
└───────────────────┴──────────────────────────────────────┘
|
└───────────────────────────┴──────────────────────────────────────┘
|
||||||
<- 208px ->
|
<- 208px ->
|
||||||
```
|
```
|
||||||
|
|
||||||
The mark appears at both ends of the header. The second-level menu sits on the
|
The mark appears at both ends of the header. The three top-level entries are the
|
||||||
**left** and is driven by `route.meta.section`, so a route declares which menu
|
two surfaces a paper is worked *in* — 论文 and 模板 — and, marked out to their
|
||||||
it belongs to and deep links render correctly on first paint. Routes without a
|
right, 参考文献: the library is drawn *from* rather than worked in, so it is a
|
||||||
`section` (the welcome page) show no menu.
|
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
|
The second-level menu sits on the **left** and is driven by `route.meta.section`,
|
||||||
themselves, read from the `papers` store, so a paper can be opened straight from
|
so a route declares which menu it belongs to and deep links render correctly on
|
||||||
the rail. Every page that creates, renames or deletes a paper reloads that
|
first paint. Routes without a `section` (the welcome page) show no menu.
|
||||||
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.
|
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:
|
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
|
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
|
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
|
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`,
|
simply show more. The five list pages (`/papers`, `/templates/list`,
|
||||||
`/templates/fields`) therefore stretch the table to the height the window
|
`/templates/fields`, `/references`, `/references/tags`) therefore stretch the
|
||||||
offers, with the toolbar above it and the pagination below it staying put while
|
table to the height the window offers, with the toolbar above it and the
|
||||||
the rows scroll inside the table.
|
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
|
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
|
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` | redirects to `/templates/list` | — |
|
||||||
| `/templates/list` | template table + CRUD | `templates` |
|
| `/templates/list` | template table + CRUD | `templates` |
|
||||||
| `/templates/fields` | title library + CRUD (the UI label is 字段管理) | `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
|
### 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
|
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.
|
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
|
## Directory Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
paper-doc/
|
paper-doc/
|
||||||
├── backend/ # FastAPI application
|
├── backend/ # FastAPI application
|
||||||
│ ├── app/
|
│ ├── app/
|
||||||
│ │ ├── api/routes/ # route handlers (health, papers, templates,
|
│ │ ├── api/routes/ # route handlers (health, papers, references,
|
||||||
│ │ │ # template_title)
|
│ │ │ # reference_tags, templates, template_title)
|
||||||
│ │ ├── core/ # settings and configuration
|
│ │ ├── core/ # settings and configuration
|
||||||
│ │ ├── crud/ # data-access helpers
|
│ │ ├── crud/ # data-access helpers
|
||||||
│ │ ├── db/ # engine, session, declarative base
|
│ │ ├── db/ # engine, session, declarative base
|
||||||
@@ -577,6 +672,7 @@ paper-doc/
|
|||||||
│ ├── scripts/seed.py # idempotent seed for the title 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/smoke_papers.py # end-to-end check of the writing loop
|
||||||
│ ├── scripts/smoke_references.py # end-to-end check of the reference library
|
│ ├── 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/mcp_server.py # MCP entry point (stdio / http)
|
||||||
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
|
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
|
||||||
│ ├── alembic.ini
|
│ ├── alembic.ini
|
||||||
@@ -585,12 +681,15 @@ paper-doc/
|
|||||||
├── frontend/ # Vue 3 SPA
|
├── frontend/ # Vue 3 SPA
|
||||||
│ ├── src/
|
│ ├── src/
|
||||||
│ │ ├── api/ # axios instance and endpoint modules
|
│ │ ├── 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
|
│ │ ├── 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
|
│ │ ├── styles/ # global reset and the shell viewport contract
|
||||||
│ │ ├── utils/ # formatting helpers
|
│ │ ├── utils/ # formatting helpers
|
||||||
│ │ └── views/ # route-level components (papers/, templates/)
|
│ │ └── views/ # route-level components (papers/, references/,
|
||||||
|
│ │ # templates/)
|
||||||
│ ├── package.json
|
│ ├── package.json
|
||||||
│ └── vite.config.ts
|
│ └── vite.config.ts
|
||||||
├── deploy/ # packaging and the k3s manifests
|
├── deploy/ # packaging and the k3s manifests
|
||||||
@@ -658,10 +757,12 @@ cd backend
|
|||||||
|
|
||||||
**Checking the reference library end to end**
|
**Checking the reference library end to end**
|
||||||
|
|
||||||
`scripts/smoke_references.py` adds literature, finds it again by author, type,
|
`scripts/smoke_references.py` makes the labels first, adds literature and tags
|
||||||
year and whether it has been cited, edits it, cites it from a sentence, looks
|
it, finds it again by author, type, year and tag, edits it, cites it from a
|
||||||
the citation up from the reference side, and checks that a cited entry cannot be
|
sentence, looks the citation up from the reference side, checks that a cited
|
||||||
deleted. It cleans up after itself:
|
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
|
```bash
|
||||||
cd backend
|
cd backend
|
||||||
|
|||||||
Reference in New Issue
Block a user