6020310b3f
A tag is the writer's filing of a row — 「综述」, 「必读」 — and it is a different fact from `reference.keywords`, which are the 关键词 printed on the article. A tag never prints, one document carries several, and the same label is on many documents, so it gets two tables rather than a column: reference_tag name (unique), colour, note reference_tag_link reference_id + tag_id — the pair is the primary key The link is a bare link, which is why it is `_link` and not `_placement`: there is no `sort` to own, so the pair *is* the row and the same label cannot be applied twice. A tag is made first and applied second: `tag_ids`, never tag names, so a typo cannot invent a label — an unknown id is a 400 naming it, and nothing is written. Deleting a tag is deliberately *not* guarded the way deleting a cited reference is: both foreign keys cascade, so the labels go and the literature stays. `GET /references?tag=1&tag=2` narrows rather than widens — the rows carrying both labels — because that is what a second filter reads as. The smoke test now walks the whole flow in the order the feature intends: labels first, then tagged references, then a rename that follows every row.
423 lines
15 KiB
Python
423 lines
15 KiB
Python
"""Request/response schemas for the reference library (参考文献).
|
|
|
|
The field set and where it comes from is documented on
|
|
:mod:`app.models.reference`; this module is about the wire format:
|
|
|
|
* **Nothing is stored that a style can derive.** ``authors`` arrives as an
|
|
ordered list and replaces the stored list wholesale, like a template's
|
|
placements — the citation prints them in exactly the order sent.
|
|
* **A DOI is stored canonically.** ``https://doi.org/10.1000/xyz``,
|
|
``doi:10.1000/xyz`` and ``10.1000/xyz`` are the same DOI, so the prefix is
|
|
stripped on write and the column holds one spelling.
|
|
* **A date is as precise as it is known.** Year, month and day are separate and
|
|
independently optional, which is what CSL calls a partial date: a book has a
|
|
year, a newspaper article a day, a patent its 公告日期.
|
|
"""
|
|
|
|
from datetime import date, datetime
|
|
|
|
from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
|
|
|
|
from app.models.reference import (
|
|
REFERENCE_AUTHOR_ROLES,
|
|
REFERENCE_LANGUAGES,
|
|
REFERENCE_TYPES,
|
|
)
|
|
from app.schemas.reference_tag import ReferenceTagRef
|
|
|
|
#: Prefixes people paste along with a DOI. Stripped on write so the column has
|
|
#: one spelling, and so a citation builder never has to test for them.
|
|
_DOI_PREFIXES = (
|
|
"https://doi.org/",
|
|
"http://doi.org/",
|
|
"https://dx.doi.org/",
|
|
"http://dx.doi.org/",
|
|
"doi:",
|
|
"DOI:",
|
|
)
|
|
|
|
|
|
def normalize_doi(value: str | None) -> str | None:
|
|
"""Return the bare DOI, or ``None`` when nothing was given."""
|
|
if value is None:
|
|
return None
|
|
text = value.strip()
|
|
for prefix in _DOI_PREFIXES:
|
|
if text.lower().startswith(prefix.lower()):
|
|
text = text[len(prefix) :]
|
|
break
|
|
return text.strip() or None
|
|
|
|
|
|
class ReferenceAuthorInput(BaseModel):
|
|
"""One contributor as the client sends it.
|
|
|
|
``name`` is required — it is what prints. ``family_name`` / ``given_name``
|
|
are optional enrichment for styles that invert or initialise a name, and a
|
|
``sort`` that is left out is assigned from the position in the list.
|
|
"""
|
|
|
|
name: str = Field(min_length=1, max_length=255)
|
|
family_name: str | None = Field(default=None, max_length=128)
|
|
given_name: str | None = Field(default=None, max_length=128)
|
|
role: str = Field(default="author", max_length=16)
|
|
sort: int | None = Field(default=None, ge=-1_000_000, le=1_000_000)
|
|
|
|
@field_validator("name")
|
|
@classmethod
|
|
def _require_name(cls, value: str) -> str:
|
|
text = value.strip()
|
|
if not text:
|
|
raise ValueError("责任者姓名不能为空")
|
|
return text
|
|
|
|
@field_validator("family_name", "given_name")
|
|
@classmethod
|
|
def _strip_optional(cls, value: str | None) -> str | None:
|
|
if value is None:
|
|
return None
|
|
return value.strip() or None
|
|
|
|
@field_validator("role")
|
|
@classmethod
|
|
def _check_role(cls, value: str) -> str:
|
|
if value not in REFERENCE_AUTHOR_ROLES:
|
|
raise ValueError(
|
|
"责任者角色只能是:" + "、".join(REFERENCE_AUTHOR_ROLES)
|
|
)
|
|
return value
|
|
|
|
|
|
class ReferenceAuthorRead(BaseModel):
|
|
"""A stored contributor."""
|
|
|
|
model_config = ConfigDict(from_attributes=True)
|
|
|
|
id: int
|
|
sort: int
|
|
name: str
|
|
family_name: str | None
|
|
given_name: str | None
|
|
role: str
|
|
|
|
|
|
class ReferenceBase(BaseModel):
|
|
"""Every field a reference may carry, all optional but the title."""
|
|
|
|
type: str = Field(default="journal-article", max_length=32)
|
|
title: str = Field(min_length=1, max_length=512)
|
|
subtitle: str | None = Field(default=None, max_length=512)
|
|
title_translated: str | None = Field(default=None, max_length=512)
|
|
title_short: str | None = Field(default=None, max_length=255)
|
|
container_title: str | None = Field(default=None, max_length=512)
|
|
container_title_short: str | None = Field(default=None, max_length=255)
|
|
series_title: str | None = Field(default=None, max_length=512)
|
|
series_number: str | None = Field(default=None, max_length=32)
|
|
edition: str | None = Field(default=None, max_length=64)
|
|
volume: str | None = Field(default=None, max_length=32)
|
|
issue: str | None = Field(default=None, max_length=32)
|
|
pages: str | None = Field(default=None, max_length=64)
|
|
article_number: str | None = Field(default=None, max_length=64)
|
|
publisher: str | None = Field(default=None, max_length=255)
|
|
publisher_place: str | None = Field(default=None, max_length=255)
|
|
event_title: str | None = Field(default=None, max_length=512)
|
|
event_place: str | None = Field(default=None, max_length=255)
|
|
event_date: str | None = Field(default=None, max_length=64)
|
|
publication_year: int | None = Field(default=None, ge=1, le=2999)
|
|
publication_month: int | None = Field(default=None, ge=1, le=12)
|
|
publication_day: int | None = Field(default=None, ge=1, le=31)
|
|
accessed_date: date | None = None
|
|
doi: str | None = Field(default=None, max_length=255)
|
|
isbn: str | None = Field(default=None, max_length=32)
|
|
issn: str | None = Field(default=None, max_length=32)
|
|
url: str | None = Field(default=None, max_length=1024)
|
|
patent_country: str | None = Field(default=None, max_length=64)
|
|
patent_number: str | None = Field(default=None, max_length=64)
|
|
standard_number: str | None = Field(default=None, max_length=64)
|
|
report_number: str | None = Field(default=None, max_length=64)
|
|
arxiv_id: str | None = Field(default=None, max_length=64)
|
|
abstract: str | None = None
|
|
keywords: str | None = Field(default=None, max_length=512)
|
|
note: str | None = None
|
|
citation_key: str | None = Field(default=None, max_length=64)
|
|
language: str | None = Field(default=None, max_length=16)
|
|
authors: list[ReferenceAuthorInput] = Field(default_factory=list)
|
|
#: The tags to apply, by id. Tags are made first and applied second, so this
|
|
#: names labels that already exist rather than carrying spellings that could
|
|
#: invent new ones. Unknown ids are refused by name.
|
|
tag_ids: list[int] = Field(default_factory=list)
|
|
|
|
@field_validator("title")
|
|
@classmethod
|
|
def _require_title(cls, value: str) -> str:
|
|
text = value.strip()
|
|
if not text:
|
|
raise ValueError("文献题名不能为空")
|
|
return text
|
|
|
|
@field_validator("type")
|
|
@classmethod
|
|
def _check_type(cls, value: str) -> str:
|
|
if value not in REFERENCE_TYPES:
|
|
raise ValueError("文献类型只能是:" + "、".join(REFERENCE_TYPES))
|
|
return value
|
|
|
|
@field_validator("language")
|
|
@classmethod
|
|
def _check_language(cls, value: str | None) -> str | None:
|
|
if value is None or value == "":
|
|
return None
|
|
if value not in REFERENCE_LANGUAGES:
|
|
raise ValueError("语种只能是:" + "、".join(REFERENCE_LANGUAGES))
|
|
return value
|
|
|
|
@field_validator("doi")
|
|
@classmethod
|
|
def _normalise_doi(cls, value: str | None) -> str | None:
|
|
return normalize_doi(value)
|
|
|
|
@field_validator(
|
|
"subtitle",
|
|
"title_translated",
|
|
"title_short",
|
|
"container_title",
|
|
"container_title_short",
|
|
"series_title",
|
|
"series_number",
|
|
"edition",
|
|
"volume",
|
|
"issue",
|
|
"pages",
|
|
"article_number",
|
|
"publisher",
|
|
"publisher_place",
|
|
"event_title",
|
|
"event_place",
|
|
"event_date",
|
|
"isbn",
|
|
"issn",
|
|
"url",
|
|
"patent_country",
|
|
"patent_number",
|
|
"standard_number",
|
|
"report_number",
|
|
"arxiv_id",
|
|
"keywords",
|
|
"citation_key",
|
|
)
|
|
@classmethod
|
|
def _blank_to_none(cls, value: str | None) -> str | None:
|
|
"""Treat a whitespace-only string as "not set" rather than as a value."""
|
|
if value is None:
|
|
return None
|
|
return value.strip() or None
|
|
|
|
@model_validator(mode="after")
|
|
def _check_online_resource(self) -> "ReferenceBase":
|
|
"""An online resource must say where it is.
|
|
|
|
GB/T 7714 prints a URL for ``[EB/OL]`` and nothing else identifies the
|
|
document; a row typed as a web page or a dataset with no URL is a row
|
|
that cannot be cited.
|
|
"""
|
|
if self.type in ("web-page", "dataset") and not (self.url or self.doi):
|
|
raise ValueError("网页/数据集类型的文献必须至少给出 URL 或 DOI")
|
|
return self
|
|
|
|
|
|
class ReferenceCreate(ReferenceBase):
|
|
"""Payload for ``POST /references``."""
|
|
|
|
|
|
class ReferenceUpdate(BaseModel):
|
|
"""Payload for ``PATCH /references/{id}`` — every part optional.
|
|
|
|
``authors`` is a full replacement when present, like a template's
|
|
placements: the citation prints the list in the order it arrives.
|
|
"""
|
|
|
|
type: str | None = Field(default=None, max_length=32)
|
|
title: str | None = Field(default=None, min_length=1, max_length=512)
|
|
subtitle: str | None = Field(default=None, max_length=512)
|
|
title_translated: str | None = Field(default=None, max_length=512)
|
|
title_short: str | None = Field(default=None, max_length=255)
|
|
container_title: str | None = Field(default=None, max_length=512)
|
|
container_title_short: str | None = Field(default=None, max_length=255)
|
|
series_title: str | None = Field(default=None, max_length=512)
|
|
series_number: str | None = Field(default=None, max_length=32)
|
|
edition: str | None = Field(default=None, max_length=64)
|
|
volume: str | None = Field(default=None, max_length=32)
|
|
issue: str | None = Field(default=None, max_length=32)
|
|
pages: str | None = Field(default=None, max_length=64)
|
|
article_number: str | None = Field(default=None, max_length=64)
|
|
publisher: str | None = Field(default=None, max_length=255)
|
|
publisher_place: str | None = Field(default=None, max_length=255)
|
|
event_title: str | None = Field(default=None, max_length=512)
|
|
event_place: str | None = Field(default=None, max_length=255)
|
|
event_date: str | None = Field(default=None, max_length=64)
|
|
publication_year: int | None = Field(default=None, ge=1, le=2999)
|
|
publication_month: int | None = Field(default=None, ge=1, le=12)
|
|
publication_day: int | None = Field(default=None, ge=1, le=31)
|
|
accessed_date: date | None = None
|
|
doi: str | None = Field(default=None, max_length=255)
|
|
isbn: str | None = Field(default=None, max_length=32)
|
|
issn: str | None = Field(default=None, max_length=32)
|
|
url: str | None = Field(default=None, max_length=1024)
|
|
patent_country: str | None = Field(default=None, max_length=64)
|
|
patent_number: str | None = Field(default=None, max_length=64)
|
|
standard_number: str | None = Field(default=None, max_length=64)
|
|
report_number: str | None = Field(default=None, max_length=64)
|
|
arxiv_id: str | None = Field(default=None, max_length=64)
|
|
abstract: str | None = None
|
|
keywords: str | None = Field(default=None, max_length=512)
|
|
note: str | None = None
|
|
citation_key: str | None = Field(default=None, max_length=64)
|
|
language: str | None = Field(default=None, max_length=16)
|
|
authors: list[ReferenceAuthorInput] | None = None
|
|
#: Full replacement when present, like ``authors``: the list is the set of
|
|
#: labels on the row, so sending it means "these and no others" and ``[]``
|
|
#: clears every label. Omitting the key leaves the labels alone.
|
|
tag_ids: list[int] | None = None
|
|
|
|
@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("type")
|
|
@classmethod
|
|
def _check_type(cls, value: str | None) -> str | None:
|
|
if value is None:
|
|
return None
|
|
if value not in REFERENCE_TYPES:
|
|
raise ValueError("文献类型只能是:" + "、".join(REFERENCE_TYPES))
|
|
return value
|
|
|
|
@field_validator("language")
|
|
@classmethod
|
|
def _check_language(cls, value: str | None) -> str | None:
|
|
if value is None or value == "":
|
|
return None
|
|
if value not in REFERENCE_LANGUAGES:
|
|
raise ValueError("语种只能是:" + "、".join(REFERENCE_LANGUAGES))
|
|
return value
|
|
|
|
@field_validator("doi")
|
|
@classmethod
|
|
def _normalise_doi(cls, value: str | None) -> str | None:
|
|
return normalize_doi(value)
|
|
|
|
|
|
class ReferenceListItem(BaseModel):
|
|
"""A reference as it appears in the library table."""
|
|
|
|
id: int
|
|
type: str
|
|
title: str
|
|
subtitle: str | None
|
|
container_title: str | None
|
|
#: 出版者. Carried on the row because a book, a thesis and a report have no
|
|
#: container to show and the publisher *is* their "where".
|
|
publisher: str | None
|
|
publication_year: int | None
|
|
volume: str | None
|
|
issue: str | None
|
|
pages: str | None
|
|
doi: str | None
|
|
#: The printed author list, joined — a table row needs the line, not the
|
|
#: rows behind it.
|
|
authors_line: str
|
|
author_count: int
|
|
#: The labels the writer put on it, ready to paint. Loading them here rather
|
|
#: than per row is what keeps a page of the library one query for the tags.
|
|
tags: list[ReferenceTagRef] = Field(default_factory=list)
|
|
#: How many sentences cite it. Drives the refusal message on delete, and
|
|
#: tells the writer at a glance what is already used.
|
|
citation_count: int
|
|
created_at: datetime
|
|
updated_at: datetime
|
|
|
|
|
|
class ReferenceRead(BaseModel):
|
|
"""A reference with everything the table does not need."""
|
|
|
|
id: int
|
|
type: str
|
|
title: str
|
|
subtitle: str | None
|
|
title_translated: str | None
|
|
title_short: str | None
|
|
container_title: str | None
|
|
container_title_short: str | None
|
|
series_title: str | None
|
|
series_number: str | None
|
|
edition: str | None
|
|
volume: str | None
|
|
issue: str | None
|
|
pages: str | None
|
|
article_number: str | None
|
|
publisher: str | None
|
|
publisher_place: str | None
|
|
event_title: str | None
|
|
event_place: str | None
|
|
event_date: str | None
|
|
publication_year: int | None
|
|
publication_month: int | None
|
|
publication_day: int | None
|
|
accessed_date: date | None
|
|
doi: str | None
|
|
isbn: str | None
|
|
issn: str | None
|
|
url: str | None
|
|
patent_country: str | None
|
|
patent_number: str | None
|
|
standard_number: str | None
|
|
report_number: str | None
|
|
arxiv_id: str | None
|
|
abstract: str | None
|
|
keywords: str | None
|
|
note: str | None
|
|
citation_key: str | None
|
|
language: str | None
|
|
authors: list[ReferenceAuthorRead]
|
|
tags: list[ReferenceTagRef] = Field(default_factory=list)
|
|
citation_count: int
|
|
created_at: datetime
|
|
updated_at: datetime
|
|
|
|
|
|
class ReferenceCitationRead(BaseModel):
|
|
"""One sentence that cites a reference — the reverse lookup.
|
|
|
|
"Which of my sentences use this article?" is the question a reference
|
|
library exists to answer, and it needs the sentence, the paragraph it sits
|
|
in, and the paper it belongs to.
|
|
"""
|
|
|
|
citation_id: int
|
|
sentence_id: int
|
|
sentence_content: str
|
|
quote: str
|
|
paper_id: int
|
|
paper_title: str
|
|
paper_template_filed_sort: int
|
|
paragraph_name: str | None = None
|
|
|
|
|
|
__all__ = [
|
|
"ReferenceAuthorInput",
|
|
"ReferenceAuthorRead",
|
|
"ReferenceBase",
|
|
"ReferenceCitationRead",
|
|
"ReferenceCreate",
|
|
"ReferenceListItem",
|
|
"ReferenceRead",
|
|
"ReferenceUpdate",
|
|
"normalize_doi",
|
|
]
|