"""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", ]