Files
paper-doc/backend/app/schemas/paper.py
T
govin 960450f744 frontend: typeset the LaTeX, and let a sentence start a new line
Two things a paper needs that the paragraph model could not express.

**Formulas.** A sentence stores the LaTeX the writer typed — `$\ell$`,
`$$ … \tag{1} $$` — because that is the editable form, and it was being printed
as source. `src/utils/math.ts` now splits a sentence into text and formulas,
gives the formulas to KaTeX and escapes everything else; `math-error` in red
when KaTeX cannot read one, rather than an exception that blanks the paragraph
(the paper in the database has 106 sentences with formulas, 29 of them
display). Four delimiters are recognised — `$$…$$`, `\[…\]`, `$…$`, `\(…\)` —
and an unmatched `$` is left alone instead of swallowing the rest of the
paragraph. A display formula is a block, so it takes its own line and centres
itself without any flagging; text goes through `v-html` escaped, and KaTeX runs
with trust off.

**Line breaks.** A paragraph is its sentences run together, which is right for
prose and wrong for a display formula, a list of items or an author line.
`paper_sentence.line_break_before` is that request: a flag rather than a
newline inside `content`, because content folds its whitespace on purpose (a
sentence really is one line) and because a break hidden in a string is one
nobody can see or remove. It prints a `<br>`, it is a checkbox on the
sentence's row in the editor, and it *replaces* the separator rather than
adding to it — the new line already separates, and a space as well would indent
the line by a blank.

Verified against the real paper in the browser: 214 inline formulas and 29
display formulas typeset with zero failures and no `$$` left on the page; a
sentence flagged for a break lands on its own line while its neighbour stays
inline; the display formula centres on a line of its own and the sentence after
it starts below. 54 paper checks (2 new), 61 reference checks and 76 MCP checks
pass, with `vue-tsc` and the build clean.

Also: `.pnpm-store/` is ignored — pnpm put its content-addressed store in the
project root rather than the home directory.
2026-09-23 11:30:29 +08:00

430 lines
15 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""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 = ""
#: Start a new line at this sentence rather than running on from the last.
line_break_before: bool = False
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
line_break_before: bool | 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
#: Whether a line break prints before this sentence. See
#: :attr:`app.models.paper_sentence.PaperSentence.line_break_before`.
line_break_before: bool
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",
]