Files
paper-doc/docs/OVERVIEW.md
T
govin b97aab6f30 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.
2026-09-22 21:50:39 +08:00

46 KiB
Raw Blame History

paper-doc

A tool that supports the paper-writing process: it manages the materials, sections, figures, and references that go into a paper. The name reflects the document-centric core of the workflow — a paper is composed from structured documents rather than written in one pass.

The first feature to land is the template configuration: a reusable library of section fields plus named templates built from them, so that a paper is written by filling in a known structure instead of deciding one.

The second is paper authoring: a paper is a document written against a template, sentence by sentence, paragraph by paragraph. The structure is never copied into the paper — it is read from the template on every render — so switching a paper's template re-shapes the whole document in one write without touching a single sentence.

Tech Stack

Backend

  • FastAPI (Python) — REST API
  • SQLAlchemy + Alembic — ORM layer and schema migrations
  • TiDB v8.5.0 — MySQL-compatible distributed SQL database, deployed in k3s
  • MCP Python SDK — the same domain layer, exposed as MCP tools (see below)
  • Dependencies managed with venv + requirements.txt

Frontend

  • Vue 3 + Vite — single-page application
  • axios — HTTP client
  • vue-router — client-side routing
  • pinia + pinia-plugin-persistedstate — state management with persistence
  • Element Plus — UI component library
  • Dependencies managed with pnpm

Architecture

A decoupled SPA + REST API layout:

  • The Vue SPA runs in the browser and talks to the backend exclusively over HTTP/JSON via axios. It holds no direct database access.
  • The FastAPI backend owns all persistence. It connects to TiDB through SQLAlchemy sessions and owns the schema through Alembic migrations.
  • TiDB runs inside the existing k3s cluster. The backend reaches it either through the in-cluster Service (tidb-tidb.tidb:4000) or, during local development, through the NodePort 192.168.1.88:32738.

Development runs both parts locally: Vite serves the SPA with a dev proxy that forwards /api to the FastAPI process, so the browser sees a single origin and no CORS configuration is required.

Browser ──HTTP/JSON──▶ FastAPI ──SQLAlchemy──▶ TiDB (k3s)
   │                      ▲
   └── Vite dev server ───┘  (proxy /api)

Domain 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:

template_title                    one reusable heading (字段库)
  id, name, level, font_size, font_color

template                          a named outline (模板)
  id, name, abstract

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

paper_sentence                    one sentence, at one position, in one paper
  id, paper_id → paper, template_id, paper_template_filed_sort, sort, content

paper_sentence_reference          the citations of one sentence
  id, sentence_id → paper_sentence, reference_id → reference, quote, sort

reference                         the 参考文献 module: the literature itself
  id, type, title, subtitle, container_title, volume, issue, pages,
  publisher, publisher_place, publication_year, doi, url, …

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

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 typography the template gives it, and the same sentence-by-sentence editing as every other paragraph. A column for it would be a second home for the same text, one the document never reads: a paper could show two different abstracts, 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.

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 title library is flat, not a tree

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. 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 placement table

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, 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 ordering is always total and stable. The UI warns about ties too, and offers a button that renumbers the selection 1..N.

Templates hold references, not copies

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_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 can share a position, so a sentence that remembers "I sit at position 7" lands on whatever the new template puts at position 7 when the paper is switched. The alternative — pointing at a placement row — would make every sentence belong to one template and turn a switch into a re-mapping of every line.

Three behaviours fall out of that one choice:

  • The structure exists before the content. A paragraph is any position the template defines or any position a sentence occupies, so an unwritten paragraph still renders, empty, and a paper created a second ago already has its full shape.
  • A switch destroys nothing. Positions the new template does not define are 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_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_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.

The reference library holds literature, not citations

reference is the literature: one row per document the writer has read, and it is global — the same article is cited from several papers, so the entry cannot belong to one of them. The citation is a different fact — "this sentence quotes this passage" — and it lives on the paper side, in paper_sentence_reference, which carries the quote and the citation's order inside the sentence.

So the relation is many-to-many in both directions, through that table:

paper_sentence ──< paper_sentence_reference >── reference
                        (quote, sort)              (title, year, …)

Two questions follow from it, and each is answered from its own side: "what does this sentence quote?" is a lookup by sentence_id, and "where have I used this article?" is a lookup by reference_id (GET /references/{id}/citations). One column on paper_sentence could not express the first of those — it would cap a sentence at one citation — which is why the relation is a table rather than a foreign key.

Why these columns and no others

The field set is the intersection of the formats a paper has to survive:

Format What it decided
CSL JSON (csl-data.json: 103 fields, 45 types) the field names, and partial dates as year / month / day rather than one DATE
GB/T 7714-2015 every entry carries a type with its marker; patents need patent_country + patent_number, standards standard_number, online resources accessed_date
BibTeX / RIS citation_key, and the one-field-per-fact layout that makes an export a mapping rather than a parse

Contributors are a child table, not a column, and each row stores the printed name and its two halves. That is not duplication: a citation prints 「张三」, Zhang, S. or S. Zhang depending on the style, so the printed form is the authority for display and the halves are the authority for rewriting a name — and an institutional author (「世界卫生组织」) has no halves at all.

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 punctuation rules and no comma handling: one line in the editor is one sentence, and what the writer types is what is stored, minus runs of whitespace (leading, trailing, and any newline pasted inside a line, which fold to a single space so a sentence really is one line). Commas never break anything — the only place a comma separates anything in this project is the keyword field.

That is deliberate. A splitter that guesses wrong corrupts content, and the guess would have to be right for every abbreviation (et al., i.e.), every decimal (3.14), every numbered list and every language the tool is used in. The writer decides where a sentence ends; the software only decides what goes at the seam between two of them.

Exactly one split has ever been performed, in revision a83f5c21d7b6, to move the old paper.abstract column into the body. It cut after a Chinese full stop (。) and nothing else — deliberately conservative: an English abstract survives that migration as a single row rather than being cut at the first et al., and one long line is a line the writer can split by hand.

What goes at the seam

A paragraph is printed by concatenating its sentences in sort order, so the seam between two of them has to be spelled out: app.crud.paper.sentence_separator returns "" or a single space, and the document response carries it as SentenceRead.separator_before.

Seam Separator Why
……缺口。 + 本研究…… "" Chinese needs nothing; the full stop separates
First sentence. + Second. " " without it the two print as First sentence.Second.
缺口。 + This study " " mixed text takes the space
test. + 本研究…… " " same, in the other direction
anything + an empty sentence "" an empty line carries citations, not text

So the rule is about the seam rather than the language: a space goes in unless both sides are CJK, where adjacency is already the convention. It is derived on every read and never stored — a stored separator is one that can go stale against the text it separates — and a client prints separator_before + content and adds no spacing of its own.

separator_before was added because the alternative was already a bug: CJK sentences printed correctly by accident (the full stop hides the missing space), so nothing looked wrong until the first English paper, whose sentences would have run together.

Citations are a table, not a column

One sentence may quote several references, so paper_sentence_reference holds one row per citation. quote — 引用内容 — is required and must not be blank: a citation that does not say what it quotes is rejected with 422 rather than stored as a half-record. reference_id is a plain nullable integer with no foreign key, because the reference library does not exist yet; a citation may therefore be written now and linked later.

Foreign keys are declared, and this cluster enforces them

TiDB parses FOREIGN KEY for compatibility, and from v6.6 honours it when tidb_enable_foreign_key is on. On the cluster this project runs against it is on, so the constraints are real integrity rather than documentation: a dangling insert is rejected (1452) and ON DELETE CASCADE / SET NULL actually fire. Two consequences are worth knowing before touching a migration:

  • Tables must be created in dependency order, and a rename must be checked rather than assumed. RENAME TABLE does carry a referencing constraint along with the renamed table here (the rename in revision f27a1c6d9e04 was rehearsed against the cluster before it was written), but that is a property of the deployment, not of SQL.
  • The API still checks first. A database violation surfaces as a generic driver error, while the application refuses with a message that names the row and the count:
    • deleting a library field still placed in a template → 409, naming the field and how many templates use it;
    • deleting a template a paper is written against → 409, naming the template and how many papers use it — the template is that paper's structure, so removing it would empty the paper rather than tidy up;
    • creating a template that references a missing field → 400, and creating or patching a paper that references a missing template likewise.

The ORM cascades stay as well. Template.items, Paper.sentences and PaperSentence.citations use cascade="all, delete-orphan", so deleting a row 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.

Method Path Notes
GET /health liveness plus a TiDB probe
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
POST /templates/batch-delete body { "ids": [...] }
GET /papers keyword matches title/author/keywords, plus status, template_id
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, 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, 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
PATCH DELETE /papers/{id}/sentences/{id} edit or remove one sentence

Conventions worth knowing:

  • font_color is stored and returned as canonical #RRGGBB. The API also accepts rgb(r, g, b), #rgb and bare aabbcc, and normalises them on write.
  • font_size is a JSON number, not a string — a client should not have to parse it before using it in a CSS rule.
  • 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-titles for template_title, /papers for paper.
  • A paper document returns its paragraphs in ascending position order, 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 blank quote is refused with 422.
  • keywords is stored as a canonical , -joined string; ,、; and ; are accepted on write and de-duplicated.
  • Paper status is one of draft, writing, done.
  • A citation's reference_id is checked against the library: citing literature that does not exist is a 400 naming the ids, not a foreign-key error from the driver. A citation with no reference_id stays legal — a 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.

MCP server

The same domain layer is also served over the Model Context Protocol, so an agent — Claude Code, Codex, the DeepSeek Harness — can write a paper without a browser. Full manual: docs/MCP.md.

It is a third front door rather than a second implementation. The REST routes, the MCP tools and the seed script all call app.crud and all validate through app.schemas, so a rule fixed in the CRUD layer is fixed everywhere and a paper written by an agent is indistinguishable from one written by hand. What app/mcp/ adds is only what a model needs and a browser does not:

Addition Why the REST shape is wrong for a model
29 tools with paper_ / paragraph_ / sentence_ / template_ / field_ prefixes a model picks a tool out of a list by its name, not by reading 29 descriptions
JSON strings, None-free, no pagination envelope on reads a tool result is paid for in context tokens
paragraph_write addressed by heading as well as position nobody writing "1. Introduction" knows the template places it at sort = 20
paper_write / paper_write_text "generate the paper, then put it in" is one intention, not thirty round trips
paper_delete refuses once before it deletes a cascading delete has no undo in a tool call
sentence_search across papers the job is consistency — one paper says 洪水损失, the next must not say GUL
reference_* and reference_tag_* the reference library is what makes a citation mean something; an agent that can cite id 42 but cannot look up what 42 is is writing blind
reference_import "here are the twenty references I cited" is one intention, and twenty round trips would spend twenty schemas on it

Two transports are served from one build: stdio, which is what a client spawns, and streamable-http, which is what a client on another machine connects to (behind a bearer token). The package is split so that only app/mcp/server.py knows a transport exists:

app/mcp/
├── server.py      transports, CLI, health probes, the instructions sent at initialize
├── support.py     sessions, JSON shaping, heading resolution, the one text splitter
├── specs.py       the shapes a model may send (a paragraph, a sentence, a citation)
├── selfcheck.py   --check: connect once and print the tool surface
└── tools/         papers, paragraphs, sentences, templates, fields — registered
                   by register_all(), each tool three lines around an app.crud call

/healthz and /readyz exist for Kubernetes and are the only unauthenticated routes. They answer different questions on purpose: liveness touches nothing, so a database that is briefly unreachable cannot become a restart loop, while readiness runs SELECT 1 so the pod leaves the Service's endpoints while TiDB is down and rejoins when it is not.

Two shape decisions are worth knowing before adding a tool. A nested argument model keeps model_fields_set, which a flattened signature cannot: 38 bibliographic fields spread across keyword parameters would arrive with the omitted ones indistinguishable from explicit nulls, so reference_update takes its changes as one object and forwards only the keys the caller actually wrote. And a domain refusal belongs in DOMAIN_REFUSALS in tools/registry.py on the day it is written — UnknownReference was translated there when the reference tools were still to come, and the tag rules (UnknownTag, DuplicateTagName) had to be added when those tools landed, because an unlisted refusal reaches the model as Error executing tool … and says nothing about what to fix.

Two more decisions are worth knowing. Results are registered with structured_output=False: inferred from a -> str annotation, the SDK publishes a {"result": …} envelope and sends the JSON twice, once as structuredContent and once as text, and clients that read only one of the two then disagree about what the tool returned. And the docstring is the tool description verbatim, sent with every request — so a tool docstring is one or two lines and the reasoning goes in the module docstring, where it costs nothing.

Frontend

Shell

┌───────────────────────────┬──────────────────────────────────────┐
│ [mark] paper-doc          │  论文  模板  参考文献           [mk] │  header
├───────────────────────────┼──────────────────────────────────────┤
│  论文                     │                                      │  second-level
│   论文列表                │  <RouterView>                        │  menu, left
│   新建论文                │                                      │
│   ── 我的论文 ──          │                                      │
│   ● 论文标题 A            │                                      │
│   ● 论文标题 B            │                                      │
└───────────────────────────┴──────────────────────────────────────┘
             <- 208px ->

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 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:

  • Which side the menu lands on follows from its DOM order inside the flex row in App.vue — first child, left. Moving it is a one-block change there, not a stylesheet override.
  • The logo block is exactly as wide as the rail. Both read asideWidth() from src/layout.ts, so they cannot drift apart, and collapsing the rail narrows the logo block with it (dropping the wordmark and centring the mark). The header's own padding is zeroed for this; the two insets come from ASIDE_INSET so the mark lines up with the section title below it.

The column also carries through to the content: the rail is 208px and both the top nav's first item and .el-main are inset a further 20px by their own Element Plus defaults, so the menu text, the page body, and the page header all start on the same vertical line.

Shell metrics

src/layout.ts is the single source for the rail's width and inset. It is a module rather than CSS custom properties because el-aside takes its width through a prop, which would otherwise fight an inline style coming from the stylesheet.

List pages fill the window

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 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 each one is load-bearing:

Piece Why
.page--fill min-height: 100% of the content area — a floor that still grows
.card--fill makes the card a column so its body can pass the height down
.card--fill > .el-card__body a column with min-height: 0, without which a flex child refuses to shrink below its content
.table-fill + height="100%" flex: 1 1 0 so the table takes the leftover height instead of claiming its content height as its basis; Element Plus then pins the header and scrolls the rows

Measured in a real browser at three window sizes, with rows to scroll and with none:

Window Table Page scroll Rows scroll Empty state
1920x1080 781px none 519px inside centred, 741px
1440x900 601px none 699px inside centred, 561px
1280x620 321px none 979px inside centred, 281px

.table-fill keeps a 240px floor. Below it — a 1280x420 window — the table stops shrinking, the page grows past the viewport and the content area scrolls, which is the pre-existing behaviour rather than a squashed table. Pages that are not lists (the paper document) keep scrolling normally.

Routes

Path View Section
/ welcome —
/papers paper table + CRUD (?new=1 opens the create dialog) papers
/papers/:id one paper, read as a document papers
/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

PapersView is the library; papers/PaperDetailView is the writing surface. The detail view renders the server's document verbatim and adds three things it 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, 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 document in one write.

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, 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
│   │   ├── mcp/             # MCP server: tools, specs, transports, self-check
│   │   ├── models/          # SQLAlchemy models
│   │   └── schemas/         # Pydantic request/response models
│   ├── alembic/             # migration environment and revisions
│   ├── 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/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
│   ├── requirements.txt
│   └── .env.example
├── frontend/                # Vue 3 SPA
│   ├── src/
│   │   ├── api/             # axios instance and endpoint modules
│   │   ├── components/      # shell, field, template, paper and reference
│   │   │                    #   components
│   │   ├── router/          # vue-router configuration
│   │   ├── 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/, references/,
│   │                        #   templates/)
│   ├── package.json
│   └── vite.config.ts
├── deploy/                  # packaging and the k3s manifests
│   ├── build-mcp-image.sh   # build + push the image from a DinD pod
│   ├── k8s/                 # namespace, ConfigMap, Deployment, Service
│   └── README.md
└── docs/                    # project documentation
    ├── OVERVIEW.md
    └── MCP.md               # the MCP manual: tools, workflows, client configs

Getting Started

Prerequisites

  • Python 3.10+ with venv
  • Node.js 18+ with pnpm
  • Network access to the TiDB instance (local development uses the NodePort)

Backend

cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # then fill in the database credentials
uvicorn app.main:app --reload --port 8000

API docs are then served at http://127.0.0.1:8000/docs.

Frontend

cd frontend
pnpm install
pnpm dev

The SPA is served at http://127.0.0.1:5173 and proxies /api to the backend on port 8000.

Database

The paper_doc database is created once, out of band, against TiDB. Schema changes are applied through Alembic:

cd backend
alembic upgrade head

Seed data

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:

cd backend
.venv/bin/python scripts/seed.py            # add anything missing
.venv/bin/python scripts/seed.py --reset    # empty the tables first

Checking the reference library end to end

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, 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:

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:

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 — create a paper on a template, verify the empty structure, fill a paragraph with sentences and citations, switch the template, check that unmatched positions survive under an unset heading, move a paragraph, and delete it all again. It exits non-zero on the first failed expectation and cleans up after itself:

cd backend
.venv/bin/python scripts/smoke_papers.py

Checking the MCP server

scripts/mcp_server.py --check connects to the database once and prints the tool surface, which is the failure this catches: a client that spawned the server successfully and then sees every call fail. scripts/smoke_mcp.py drives the whole writing loop through a real MCP client — the same child process and JSON-RPC over stdin/stdout that Claude Code, Codex and the Harness use — and runs unchanged against --url for the HTTP transport:

cd backend
.venv/bin/python scripts/mcp_server.py --check
.venv/bin/python scripts/smoke_mcp.py

Deployment

The MCP server runs in k3s in the paper-doc namespace and is reached at http://192.168.1.88:30931/mcp, behind a bearer token. There is no container runtime on this host — k3s runs containerd, and neither ctr nor crictl builds from a Dockerfile — so deploy/build-mcp-image.sh builds inside a throwaway privileged docker-in-docker pod, with the working tree mounted in through a hostPath so the build context is what you are actually looking at. The database is the in-cluster TiDB Service (tidb-tidb.tidb:4000), not the NodePort the host uses. deploy/README.md has the commands, the two traps worth knowing (a reused image tag silently keeps the cached image; COPY carries the working tree's 0600 file mode into the image and a non-root container then cannot read its own code), and how to add the REST API to the same namespace.