diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index 30a4a34..b6cf838 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -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 -│ 论文列表 │ │ menu, left -│ 新建论文 │ │ -│ ── 我的论文 ── │ │ -│ ● 论文标题 A │ │ -│ ● 论文标题 B │ │ -└───────────────────┴──────────────────────────────────────┘ - <- 208px -> +┌───────────────────────────┬──────────────────────────────────────┐ +│ [mark] paper-doc │ 论文 模板 参考文献 [mk] │ header +├───────────────────────────┼──────────────────────────────────────┤ +│ 论文 │ │ second-level +│ 论文列表 │ │ 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=`, 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=` 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=` 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