Files
paper-doc/backend/app/schemas/__init__.py
T
govin d7bb777264 backend: add the reference library (参考文献)
One table per document the writer has read, and one for its contributors:

    reference          id, type, title, subtitle, title_translated,
                       container_title, volume, issue, pages, publisher,
                       publisher_place, event_*, publication_year/month/day,
                       accessed_date, doi, isbn, issn, url, patent_*,
                       standard_number, report_number, arxiv_id, abstract,
                       keywords, note, citation_key, language
    reference_author   reference_id, sort, name, family_name, given_name, role

The field set is the intersection of the formats a paper has to survive, taken
from the CSL JSON schema (103 fields, 45 types — what Zotero, Mendeley and
Pandoc exchange) against GB/T 7714-2015, BibTeX and RIS. The mapping is on
`app.models.reference` rather than in a commit message, because the next person
to add a column needs it more than this one does. Three decisions worth naming:

* **Partial dates.** Year, month and day are separate nullable integers, which
  is CSL's `issued`: a book has a year, a newspaper article a day, a patent its
  公告日期, and nothing invents the rest.
* **Contributors are rows, not a column.** A citation prints an ordered list
  with 编 / 译 marks, and styles rewrite names (「张三」 / "Zhang, S." /
  "S. Zhang"), so the printed form and its two halves are stored separately —
  display reads `name`, a reformatting style reads the halves, and an
  institutional author has neither.
* **`volume` / `issue` / `pages` are strings.** Journals print `12(Suppl.)`,
  `S1` and `e12345`, and a citation reproduces what is printed.

The library is global: the same article is cited from several papers, so the
entry cannot belong to one of them. The citation stays on the paper side in
`paper_sentence_reference`, which now carries a real foreign key to `reference`
(`ON DELETE RESTRICT`) — the column had been a loose integer waiting for this
table. A sentence may quote several documents and a document may be quoted by
many sentences, which is why the relation is a table and not a column on
`paper_sentence`.

Refusals are raised once, in the data layer, as `UnknownReference`, and
translated where each caller speaks: `400` with the offending ids for REST (one
exception handler, no route carries the check), a readable tool error for MCP
(one wrapper in the tool registry). Neither entry point can skip it, so the
foreign key never has to be the thing that complains.

API: `/references` CRUD plus batch delete, and `/references/{id}/citations` for
the reverse lookup — "where have I used this article?" — which is what tells a
writer whether an entry is safe to delete.

Verified: 29 new checks in `scripts/smoke_references.py` (partial dates, DOI
normalisation, author order and roles, search by author/type/year/cited, the
citation round trip, 400 on a phantom id, 409 on a cited entry), the paper
suite's 45 and the MCP suite's 47 still pass. The MCP suite now cites a real
entry instead of a phantom id, which is what an agent has to do now.
2026-09-22 17:13:32 +08:00

90 lines
1.9 KiB
Python

"""Pydantic schemas for request and response payloads."""
from app.schemas.common import (
BatchDeleteRequest,
BatchDeleteResult,
PageResult,
normalize_hex_color,
)
from app.schemas.paper import (
CitationInput,
CitationRead,
PaperCitationRead,
PaperCreate,
PaperDocumentRead,
PaperListItem,
PaperRead,
PaperStatus,
PaperUpdate,
ParagraphListRead,
ParagraphRead,
ParagraphUpdate,
SentenceCreate,
SentenceRead,
SentenceUpdate,
)
from app.schemas.reference import (
ReferenceAuthorInput,
ReferenceAuthorRead,
ReferenceCitationRead,
ReferenceCreate,
ReferenceListItem,
ReferenceRead,
ReferenceUpdate,
normalize_doi,
)
from app.schemas.template import (
TemplateCreate,
TemplateListItem,
TemplateRead,
TemplateUpdate,
TemplateTitlePlacementInput,
TemplateTitlePlacementRead,
)
from app.schemas.template_title import (
TemplateTitleCreate,
TemplateTitleRead,
TemplateTitleRef,
TemplateTitleUpdate,
)
__all__ = [
"BatchDeleteRequest",
"ReferenceAuthorInput",
"ReferenceAuthorRead",
"ReferenceCitationRead",
"ReferenceCreate",
"ReferenceListItem",
"ReferenceRead",
"ReferenceUpdate",
"normalize_doi",
"CitationInput",
"CitationRead",
"PaperCitationRead",
"PaperCreate",
"PaperDocumentRead",
"PaperListItem",
"PaperRead",
"PaperStatus",
"PaperUpdate",
"ParagraphListRead",
"ParagraphRead",
"ParagraphUpdate",
"SentenceCreate",
"SentenceRead",
"SentenceUpdate",
"BatchDeleteResult",
"PageResult",
"TemplateCreate",
"TemplateListItem",
"TemplateRead",
"TemplateUpdate",
"TemplateTitleCreate",
"TemplateTitleRead",
"TemplateTitleRef",
"TemplateTitleUpdate",
"TemplateTitlePlacementInput",
"TemplateTitlePlacementRead",
"normalize_hex_color",
]