76708ce767
The list was printing each citation's quote under a `引用 #53` tag: no authors, no year, no pages, no DOI — the quoted passage where the entry should be — and it numbered *citations*, so a paper with 86 citations to 65 works listed 21 of them two or three times under different numbers. The same article was `[5]` in one paragraph and `[17]` in another. Two rules were wrong, so two are stated here: **A work is numbered where the reader first meets it.** A citation is a place in the text; an entry is a work. `citations` still has one row per place, and each row now carries the number of its *work*, so the marker in the text, the tooltip on it and the entry in the list are the same number. The document grew a `references` list — the entries, in order — and `reference_style`, which names the style that wrote them. **How a reference prints is a property of a style, not of a citation.** The new `app/citation_styles` package holds one module per style; `springer.py` implements Springer's basic style, whose shape is `Names: Title. <where it sits> (year). <identifier>` with a branch per document type — a journal with its volume(issue) and pages, a book with publisher and place, a chapter inside somebody else's book, a patent with its number, a page whose URL is its source. Three of its rules are decisions rather than transcription, and each is documented where it applies: up to six contributors are named and more become three plus `et al.`; a journal prints under its 刊名缩写 when the writer stored one, because no algorithm abbreviates an arbitrary title correctly; and a CJK name keeps its printed form even with halves filled in, because dotting 「三」 into an initial is wrong in Chinese and insufficient in English. Nothing is invented to fill a gap. An entry says what it knows and reports the rest as `missing` (「缺 责任者、出版年」), 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 rather than a library that needs attention. `document_text` had the same bug in the MCP surface and now prints the entries, with in-text markers taken from the document's numbering rather than from each sentence's local position — which is what made the text an agent reads disagree with the list under it. `scripts/check_citation_styles.py` checks the formatter with no server and no database: one reference of every type, and the exact entry the style calls for.
424 lines
15 KiB
Python
424 lines
15 KiB
Python
"""Request/response schemas for papers (论文).
|
||
|
||
Three shapes of payload live here:
|
||
|
||
* the **paper** itself — title, author, status, keywords, target journal and
|
||
the template it is written against;
|
||
* **paragraph** payloads — the writer's unit of work. A paragraph is edited by
|
||
reading every sentence of it and writing the whole set back, so the update
|
||
schema is a full replacement;
|
||
* the **document** — what the reader sees: the template's paragraphs in order,
|
||
each carrying the sentences stored at its position, plus the 参考文献 list,
|
||
already formatted in one citation style.
|
||
|
||
Text normalisation is deliberately strict, because the two sides of the wire
|
||
have to agree on what counts as empty:
|
||
|
||
* a *sentence* is one line — leading/trailing whitespace goes, and any run of
|
||
whitespace inside (including a pasted newline or an ideographic space) folds
|
||
to a single space. An all-whitespace sentence becomes the empty string, which
|
||
is legal and renders as a blank line;
|
||
* a *title* must not be blank once trimmed;
|
||
* a *citation* must quote something — non-blank ``quote`` — or it is rejected.
|
||
"""
|
||
|
||
from datetime import datetime
|
||
from typing import Literal
|
||
|
||
from pydantic import BaseModel, ConfigDict, Field, field_validator
|
||
|
||
from app.citation_styles import DEFAULT_STYLE as DEFAULT_REFERENCE_STYLE
|
||
|
||
#: Writing states, mirroring :data:`app.models.paper.PAPER_STATUSES`. Kept as a
|
||
#: literal so the generated OpenAPI document describes the enum for clients.
|
||
PaperStatus = Literal["draft", "writing", "done"]
|
||
|
||
#: Characters that separate keywords in the stored string. Half-width and
|
||
#: full-width commas, the ideographic comma, and semicolons — a user types
|
||
#: whichever one their input method offers.
|
||
KEYWORD_SEPARATORS = ",,、;;"
|
||
|
||
|
||
def fold_whitespace(value: str) -> str:
|
||
"""Collapse every whitespace run in ``value`` to one space and trim it.
|
||
|
||
``str.split`` with no argument splits on Unicode whitespace, which covers
|
||
the ideographic space (U+3000) a Chinese input method produces, so a pasted
|
||
line cannot smuggle an invisible full-width blank into a "trimmed" field.
|
||
"""
|
||
return " ".join(value.split())
|
||
|
||
|
||
def normalize_keywords(value: str | None) -> str | None:
|
||
"""Canonicalise the keyword string: trimmed, de-duplicated, ``,``-joined.
|
||
|
||
Returns ``None`` for a value that carries no keywords, so "cleared" and
|
||
"never set" are stored the same way.
|
||
"""
|
||
if value is None:
|
||
return None
|
||
|
||
parts: list[str] = []
|
||
for chunk in value.replace(";", ";").replace(",", ",").replace("、", ",").split(";"):
|
||
for item in chunk.split(","):
|
||
word = fold_whitespace(item)
|
||
if word and word not in parts:
|
||
parts.append(word)
|
||
return ", ".join(parts) or None
|
||
|
||
|
||
class CitationInput(BaseModel):
|
||
"""One citation of one sentence.
|
||
|
||
``quote`` is required: the API refuses a citation that does not say what it
|
||
quotes. ``reference_id`` is optional, because the reference library is
|
||
still to come — a citation may be written now and linked later.
|
||
"""
|
||
|
||
reference_id: int | None = Field(default=None, ge=1)
|
||
quote: str = Field(default="", max_length=4000)
|
||
|
||
@field_validator("quote")
|
||
@classmethod
|
||
def _require_quote(cls, value: str) -> str:
|
||
text = value.strip()
|
||
if not text:
|
||
raise ValueError("引用的内容不能为空")
|
||
return text
|
||
|
||
|
||
class SentenceInput(BaseModel):
|
||
"""One sentence of a paragraph, as the editor sends it.
|
||
|
||
``sort`` is optional: omit it and the server numbers the sentences from 1
|
||
in the order they arrive, which is what the editor does by default. Send it
|
||
to keep a deliberate numbering (10, 20, 30 …) or a tie.
|
||
"""
|
||
|
||
sort: int | None = Field(default=None, ge=-1_000_000, le=1_000_000)
|
||
content: str = ""
|
||
citations: list[CitationInput] = Field(default_factory=list)
|
||
|
||
@field_validator("content")
|
||
@classmethod
|
||
def _normalise_content(cls, value: str) -> str:
|
||
return fold_whitespace(value)
|
||
|
||
|
||
class ParagraphUpdate(BaseModel):
|
||
"""Payload for ``PUT /papers/{id}/paragraphs/{sort}``.
|
||
|
||
A full replacement of the paragraph's sentences. ``target_sort`` moves the
|
||
whole paragraph: the sentences are written into another paragraph's
|
||
position, appended after whatever that paragraph already holds. That is the
|
||
manual form of what a template switch does by itself.
|
||
"""
|
||
|
||
sentences: list[SentenceInput] = Field(default_factory=list)
|
||
target_sort: int | None = Field(default=None, ge=-1_000_000, le=1_000_000)
|
||
|
||
|
||
class SentenceCreate(SentenceInput):
|
||
"""Payload for ``POST /papers/{id}/sentences`` — one new sentence."""
|
||
|
||
paper_template_filed_sort: int = Field(ge=-1_000_000, le=1_000_000)
|
||
|
||
|
||
class SentenceUpdate(BaseModel):
|
||
"""Payload for ``PATCH /papers/{id}/sentences/{sentence_id}``.
|
||
|
||
Every part is optional. ``citations`` is a full replacement when present.
|
||
"""
|
||
|
||
sort: int | None = Field(default=None, ge=-1_000_000, le=1_000_000)
|
||
paper_template_filed_sort: int | None = Field(
|
||
default=None, ge=-1_000_000, le=1_000_000
|
||
)
|
||
content: str | None = None
|
||
citations: list[CitationInput] | None = None
|
||
|
||
@field_validator("content")
|
||
@classmethod
|
||
def _normalise_content(cls, value: str | None) -> str | None:
|
||
return None if value is None else fold_whitespace(value)
|
||
|
||
|
||
# --- reads ------------------------------------------------------------------
|
||
|
||
|
||
class CitationRead(BaseModel):
|
||
"""A stored citation."""
|
||
|
||
model_config = ConfigDict(from_attributes=True)
|
||
|
||
id: int
|
||
reference_id: int | None
|
||
quote: str
|
||
sort: int
|
||
|
||
|
||
class SentenceRead(BaseModel):
|
||
"""A stored sentence with its citations."""
|
||
|
||
model_config = ConfigDict(from_attributes=True)
|
||
|
||
id: int
|
||
paper_id: int
|
||
template_id: int | None
|
||
paper_template_filed_sort: int
|
||
sort: int
|
||
content: str
|
||
citations: list[CitationRead]
|
||
#: Text to print before this sentence when the paragraph is put back
|
||
#: together — ``""`` or a single space, never anything else. Derived on
|
||
#: read by :func:`app.crud.paper.sentence_separator`, never stored, because
|
||
#: a separator that is stored is a separator that can go stale.
|
||
separator_before: str = ""
|
||
created_at: datetime
|
||
updated_at: datetime
|
||
|
||
|
||
class ParagraphRead(BaseModel):
|
||
"""One paragraph of a paper: its heading, and the sentences under it.
|
||
|
||
``name`` is ``None`` when the paper's template has no placement at this
|
||
position — the case that makes a template switch non-destructive. The
|
||
heading is then rendered as *未设定* while the sentences keep their place in
|
||
the document; ``matched`` says which of the two happened.
|
||
"""
|
||
|
||
paper_template_filed_sort: int
|
||
#: The placement row this paragraph resolved to, when there was one.
|
||
placement_id: int | None = None
|
||
title_id: int | None = None
|
||
#: Heading text as written in the template — the numbering is part of it.
|
||
name: str | None = None
|
||
level: int = 1
|
||
font_size: float | None = None
|
||
font_color: str | None = None
|
||
#: ``True`` when the template has a placement at this position.
|
||
matched: bool = False
|
||
sentences: list[SentenceRead]
|
||
|
||
|
||
class PaperCitationRead(BaseModel):
|
||
"""One citation — one place in the text where one work is cited.
|
||
|
||
A citation is not a row of the 参考文献 list, and this is the difference that
|
||
matters: a paper that cites the same article in three sentences has three
|
||
citations and **one** entry, so ``index`` is the number of the *work* and is
|
||
shared by all three. The in-text markers and the list therefore cannot
|
||
disagree about what ``[7]`` means.
|
||
"""
|
||
|
||
index: int
|
||
id: int
|
||
reference_id: int | None
|
||
quote: str
|
||
sentence_id: int
|
||
sentence_content: str
|
||
paper_template_filed_sort: int
|
||
paragraph_name: str | None = None
|
||
|
||
|
||
class PaperReferenceRead(BaseModel):
|
||
"""One entry of the 参考文献 list: one work, however often it is cited.
|
||
|
||
``text`` is the entry as it prints — the whole point of the list — and it is
|
||
assembled by :mod:`app.citation_styles` rather than by a client, so the paper
|
||
view, an export and an agent all print the same bibliography.
|
||
"""
|
||
|
||
#: The number the text shows as ``[index]``, assigned in order of first
|
||
#: appearance so the list reads in the order the reader meets the works.
|
||
index: int
|
||
#: The library row it came from, or ``None`` for a citation written before
|
||
#: the literature was entered.
|
||
reference_id: int | None
|
||
#: The formatted entry, or ``""`` when there is no library row to print.
|
||
text: str
|
||
#: Which parts a complete entry still lacks, in Chinese — 责任者、出版年、DOI…
|
||
#: Empty for a complete entry, and empty for an unlinked one, where the
|
||
#: question is not what is missing but what this is.
|
||
missing: list[str] = Field(default_factory=list)
|
||
#: Every place it is cited, in reading order.
|
||
citations: list[PaperCitationRead] = Field(default_factory=list)
|
||
|
||
|
||
class PaperBase(BaseModel):
|
||
"""Shared body of the paper create payload."""
|
||
|
||
title: str = Field(min_length=1, max_length=255)
|
||
template_id: int | None = None
|
||
author: str | None = Field(default=None, max_length=255)
|
||
status: PaperStatus = "draft"
|
||
keywords: str | None = Field(default=None, max_length=255)
|
||
target_journal: str | None = Field(default=None, max_length=255)
|
||
|
||
@field_validator("title")
|
||
@classmethod
|
||
def _require_title(cls, value: str) -> str:
|
||
text = value.strip()
|
||
if not text:
|
||
raise ValueError("论文标题不能为空")
|
||
return text
|
||
|
||
@field_validator("author", "target_journal")
|
||
@classmethod
|
||
def _blank_to_none(cls, value: str | None) -> str | None:
|
||
"""Treat a whitespace-only author or journal as "not set"."""
|
||
if value is None:
|
||
return None
|
||
return value.strip() or None
|
||
|
||
@field_validator("keywords")
|
||
@classmethod
|
||
def _normalise_keywords(cls, value: str | None) -> str | None:
|
||
return normalize_keywords(value)
|
||
|
||
|
||
class PaperCreate(PaperBase):
|
||
"""Payload for ``POST /papers``.
|
||
|
||
Creation is metadata only: the structure comes from the chosen template,
|
||
read live at render time, so there is nothing to copy and no empty rows to
|
||
materialise. The paper appears with its whole outline and no content.
|
||
"""
|
||
|
||
|
||
class PaperUpdate(BaseModel):
|
||
"""Payload for ``PATCH /papers/{id}`` — every part optional.
|
||
|
||
Changing ``template_id`` is the template switch: it re-shapes the document
|
||
in one write. Sentence rows are untouched, which is why switching back
|
||
restores the previous layout exactly.
|
||
"""
|
||
|
||
title: str | None = Field(default=None, min_length=1, max_length=255)
|
||
template_id: int | None = None
|
||
author: str | None = Field(default=None, max_length=255)
|
||
status: PaperStatus | None = None
|
||
keywords: str | None = Field(default=None, max_length=255)
|
||
target_journal: str | None = Field(default=None, max_length=255)
|
||
|
||
@field_validator("title")
|
||
@classmethod
|
||
def _require_title(cls, value: str | None) -> str | None:
|
||
if value is None:
|
||
return None
|
||
text = value.strip()
|
||
if not text:
|
||
raise ValueError("论文标题不能为空")
|
||
return text
|
||
|
||
@field_validator("author", "target_journal")
|
||
@classmethod
|
||
def _blank_to_none(cls, value: str | None) -> str | None:
|
||
if value is None:
|
||
return None
|
||
return value.strip() or None
|
||
|
||
@field_validator("keywords")
|
||
@classmethod
|
||
def _normalise_keywords(cls, value: str | None) -> str | None:
|
||
return normalize_keywords(value)
|
||
|
||
|
||
class PaperListItem(BaseModel):
|
||
"""A paper as it appears in the table, without its content."""
|
||
|
||
id: int
|
||
title: str
|
||
template_id: int | None
|
||
#: The template's name, or ``None`` when no template is chosen.
|
||
template_name: str | None
|
||
author: str | None
|
||
status: PaperStatus
|
||
keywords: str | None
|
||
target_journal: str | None
|
||
#: How many sentences have been written.
|
||
sentence_count: int
|
||
#: How many distinct paragraphs those sentences occupy.
|
||
paragraph_count: int
|
||
#: How many paragraphs the current template defines — the denominator of
|
||
#: the progress read-out. 0 when no template is chosen.
|
||
template_paragraph_count: int
|
||
created_at: datetime
|
||
updated_at: datetime
|
||
|
||
|
||
class PaperRead(PaperListItem):
|
||
"""A paper as its own page needs it.
|
||
|
||
Kept separate from :class:`PaperListItem` even though it currently adds no
|
||
field, because the two are different contracts: the table's row and the
|
||
page's subject. The paper's abstract is not here — it is a paragraph of the
|
||
document (see ``app.crud.paper.build_document``), not a property of the
|
||
paper.
|
||
"""
|
||
|
||
|
||
class PaperDocumentRead(BaseModel):
|
||
"""The whole paper as it reads: structure, content, citations, warnings.
|
||
|
||
Assembled by :func:`app.crud.paper.build_document` in a single pass, so a
|
||
client renders from one response and never has to stitch arrays together.
|
||
"""
|
||
|
||
paper: PaperRead
|
||
#: Paragraphs in ascending position order. Every position that either the
|
||
#: template or a sentence mentions appears exactly once, so an empty
|
||
#: paragraph is still a paragraph — the structure survives with no content.
|
||
paragraphs: list[ParagraphRead]
|
||
#: Citations in reading order, each carrying the number of the work it cites.
|
||
#: One row per place in the text, not per work: this is what renders the
|
||
#: in-text markers.
|
||
citations: list[PaperCitationRead]
|
||
#: The 参考文献 list: one entry per work, numbered in order of first
|
||
#: appearance, already formatted. A client prints these and does not group,
|
||
#: sort or assemble them — two implementations of the same rules would
|
||
#: eventually print two different bibliographies.
|
||
references: list[PaperReferenceRead] = Field(default_factory=list)
|
||
#: The citation style the entries were written in, so a client can name it
|
||
#: without hard-coding the choice (see ``app.citation_styles``).
|
||
reference_style: str = DEFAULT_REFERENCE_STYLE
|
||
#: Anything the reader should be told about the document as a whole, e.g.
|
||
#: a template that places two fields at the same position.
|
||
warnings: list[str] = Field(default_factory=list)
|
||
|
||
|
||
class ParagraphListRead(BaseModel):
|
||
"""Response of a paragraph read: the paragraph plus the paper it belongs to.
|
||
|
||
The editor needs to know which paper it is editing and where else it could
|
||
move the paragraph to, and both are already loaded by the document query.
|
||
"""
|
||
|
||
paper_id: int
|
||
paper_title: str
|
||
template_id: int | None
|
||
paragraph: ParagraphRead
|
||
|
||
|
||
__all__ = [
|
||
"CitationInput",
|
||
"CitationRead",
|
||
"KEYWORD_SEPARATORS",
|
||
"PaperBase",
|
||
"PaperCitationRead",
|
||
"PaperCreate",
|
||
"PaperDocumentRead",
|
||
"PaperListItem",
|
||
"PaperRead",
|
||
"PaperStatus",
|
||
"PaperUpdate",
|
||
"ParagraphListRead",
|
||
"ParagraphRead",
|
||
"ParagraphUpdate",
|
||
"SentenceCreate",
|
||
"SentenceRead",
|
||
"SentenceUpdate",
|
||
"fold_whitespace",
|
||
"normalize_keywords",
|
||
]
|