docs: describe the citation styles and the per-work numbering

Records the decisions the 参考文献 list now rests on: a citation is a place in
the text and an entry is a work, so a paper with 86 citations to 65 works lists
65 entries; the entries are written by `app/citation_styles` and a client prints
them verbatim; a gap is reported through `missing` rather than quietly rendered
as a shorter entry.

Also documents `scripts/check_citation_styles.py` — the formatter is checked
with no server and no database, because a wrong branch prints something that
looks like a bibliography entry instead of failing loudly — and why the
reference smoke test now stamps a token into everything it creates.
This commit is contained in:
2026-09-22 21:50:39 +08:00
parent 340e0777ce
commit b97aab6f30
2 changed files with 83 additions and 10 deletions
+77 -9
View File
@@ -370,6 +370,42 @@ The ORM cascades stay as well. `Template.items`, `Paper.sentences` and
removes its dependents whether or not the database would have done it too —
which keeps behaviour identical on a cluster with foreign keys switched off.
### The 参考文献 list is one entry per work, written by a style
A citation and a bibliography entry are two different counts, and confusing them
is the mistake this design is shaped around. `paper_sentence_reference` holds one
row per *place in the text* that quotes something: a paper of 86 citations to 65
works has 86 rows. The 参考文献 list has 65 entries, each numbered where the
reader first meets it, and every citation of that work carries the same number.
So `[7]` means one article everywhere — in the text, in the tooltip on the
marker, and in the list — and a work cannot appear twice under two numbers.
The entries themselves are written by :mod:`app.citation_styles`, which is a
package of one module per style:
```
app/citation_styles/
├── __init__.py the registry, DEFAULT_STYLE, format_reference/missing_fields
└── springer.py Springer's basic style — the numbered one
```
`GET /papers/{id}/document` returns `references` (the entries, in order) and
`reference_style` (which style wrote them). Three consequences are deliberate:
- **The client prints `text` verbatim.** Formatting a bibliography from fields
is a rule, and a second implementation of a rule prints a second bibliography
eventually. The paper view, the MCP text renderer and a future export all read
the same assembled entries.
- **A citation with no library row keeps its number and gets no entry.** It is
listed as its own entry with empty text and a warning, rather than dropped —
dropping it would leave a `[12]` in the text pointing at nothing.
- **A gap is reported, not filled in.** Each entry carries `missing` — the parts
a complete entry needs and does not have, in Chinese (「缺 责任者、出版年」) —
and the document warns about the incomplete ones by number. An entry that is
short because fields are empty looks like a fact about the document; saying so
is the difference between a library that needs attention and a bibliography
that lies.
## API
All routes are mounted under `/api`. Interactive docs at `/docs`.
@@ -398,7 +434,7 @@ All routes are mounted under `/api`. Interactive docs at `/docs`.
| `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, the formatted `references`, 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 |
| `POST` | `/papers/{id}/sentences` | append one sentence |
@@ -416,9 +452,14 @@ Conventions worth knowing:
`/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
nothing and merges nothing: two implementations of the same ordering rule
would eventually disagree.
already carrying their sentences and citation numbering, and its `references`
as formatted entries. The client sorts nothing, merges nothing and formats
nothing: two implementations of the same rule would eventually disagree.
- A citation's `index` is the number of its **work**, so 86 citations to 65
works produce 65 entries and repeated numbers in `citations` — see 「The
参考文献 list is one entry per work」 above.
- A document's `reference_style` names the style the entries were written in
(`springer`), so a client can label the block without hard-coding the choice.
- Sentence `content` is folded to a single line (leading, trailing and inner
whitespace runs collapse to one space), so an all-whitespace sentence becomes
the empty string — legal, and rendered as a blank line. A citation with a
@@ -630,8 +671,12 @@ alone knows how to do:
- **an edit button beside every paragraph**, written or not — content only ever
enters a paper through the paragraph editor, so it may never be the thing that
is missing;
- **numbered citation markers** in the text, matching the 参考文献 list, which
is numbered in reading order rather than per paragraph;
- **numbered citation markers** in the text, whose number is the number of the
*work* in the 参考文献 list below — a paper that cites one article in three
sentences prints the same number three times;
- **the 参考文献 block, printed from the server's entries and not reassembled** —
each entry is one work with its bibliography line, and the paragraphs that
cite it hang underneath it, with the quoted passages in the tooltip;
- **a 切换模板 dialog that previews the impact** — how much content lands under
a new heading, how much keeps its place under 未设定, and how many empty
paragraphs the new template adds — because a switch re-shapes the whole
@@ -676,6 +721,8 @@ paper-doc/
│ ├── app/
│ │ ├── api/routes/ # route handlers (health, papers, references,
│ │ │ # reference_tags, templates, template_title)
│ │ ├── citation_styles/ # how a reference prints: springer.py, and the
│ │ │ # registry that names the styles
│ │ ├── core/ # settings and configuration
│ │ ├── crud/ # data-access helpers
│ │ ├── db/ # engine, session, declarative base
@@ -687,6 +734,8 @@ paper-doc/
│ ├── 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/check_citation_styles.py # the formatter, one entry per type
│ │ # (no server, no database)
│ ├── 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
@@ -774,15 +823,34 @@ cd backend
`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:
entry cannot be deleted while a tag can, that a tag id the library does not have
is refused by name rather than invented, and that the paper's 参考文献 list
prints one formatted entry per work. It cleans up after itself:
```bash
cd backend
.venv/bin/python scripts/smoke_references.py
```
Every row it creates carries a per-run token in its title, in one author's name
and in its label names, and it asserts against searches for that token. The
library it runs against is a real one, so "the search found one row" is only a
statement about this run if the run can name its own rows.
**Checking the citation formatter**
`scripts/check_citation_styles.py` needs nothing running: it builds a reference
of every document type in memory and asserts the exact entry Springer's basic
style calls for — authors and initials, the six-author limit, the en-dashed page
range, the DOI, and what is reported missing. A wrong branch here prints
something that *looks* like a bibliography entry, which is exactly the kind of
bug that survives a smoke test:
```bash
cd backend
.venv/bin/python scripts/check_citation_styles.py
```
**Checking the paper feature end to end**
`scripts/smoke_papers.py` walks the whole writing loop against a running API —