d7bb777264
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.
83 lines
3.2 KiB
Python
83 lines
3.2 KiB
Python
"""The contributors of one reference (文献责任者).
|
|
|
|
A citation prints its authors in a fixed order, with a mark for anyone who is
|
|
not the author — 「张三, 编」, "Ed. by Smith" — so the list is a child table
|
|
rather than a column, and each row knows its position and its role.
|
|
|
|
Why a name is three fields
|
|
--------------------------
|
|
Citation styles rewrite names, and they disagree:
|
|
|
|
=========== ================ ==================
|
|
style 「张三」 "John Smith"
|
|
=========== ================ ==================
|
|
GB/T 7714 张三 Smith J
|
|
APA Zhang, S. Smith, J.
|
|
IEEE S. Zhang J. Smith
|
|
=========== ================ ==================
|
|
|
|
So the printed form and the two halves are kept apart: ``name`` is what the
|
|
writer typed and what prints when a style does not need to rearrange anything,
|
|
while ``family_name`` / ``given_name`` are what a style needs to invert or
|
|
initialise a name. Both are optional enrichment — a row with only ``name`` is
|
|
complete — and that is deliberate rather than duplication: ``name`` is the
|
|
authority for display, the halves are the authority for reformatting, and a
|
|
style uses whichever it needs. Institutional authors ("世界卫生组织") have no
|
|
halves at all, which is why they are not required.
|
|
"""
|
|
|
|
from typing import TYPE_CHECKING
|
|
|
|
from sqlalchemy import ForeignKey, Index, Integer, String, text
|
|
from sqlalchemy.orm import Mapped, mapped_column, relationship
|
|
|
|
from app.db.base import Base
|
|
|
|
if TYPE_CHECKING: # pragma: no cover - typing only
|
|
from app.models.reference import Reference
|
|
|
|
|
|
class ReferenceAuthor(Base):
|
|
"""One contributor of one reference, at one position, with one role."""
|
|
|
|
__tablename__ = "reference_author"
|
|
|
|
__table_args__ = (
|
|
# Reads are always "the contributors of this reference, in order".
|
|
Index("ix_reference_author_reference_sort", "reference_id", "sort"),
|
|
)
|
|
|
|
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
|
|
|
|
reference_id: Mapped[int] = mapped_column(
|
|
ForeignKey("reference.id", ondelete="CASCADE"),
|
|
nullable=False,
|
|
)
|
|
|
|
#: Print order, ascending. Ties are broken by ``id``, as everywhere else.
|
|
sort: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
|
|
|
|
#: What prints: 「张三」, "John Smith", "世界卫生组织".
|
|
name: Mapped[str] = mapped_column(String(255), nullable=False)
|
|
|
|
#: Optional halves, for styles that invert or initialise a name.
|
|
family_name: Mapped[str | None] = mapped_column(String(128), nullable=True)
|
|
given_name: Mapped[str | None] = mapped_column(String(128), nullable=True)
|
|
|
|
#: One of :data:`app.models.reference.REFERENCE_AUTHOR_ROLES`. The default
|
|
#: is the one that needs no mark in the citation.
|
|
role: Mapped[str] = mapped_column(
|
|
String(16),
|
|
nullable=False,
|
|
default="author",
|
|
server_default=text("'author'"),
|
|
)
|
|
|
|
reference: Mapped["Reference"] = relationship(back_populates="authors")
|
|
|
|
def __repr__(self) -> str: # pragma: no cover - debugging aid
|
|
return (
|
|
f"<ReferenceAuthor reference_id={self.reference_id} "
|
|
f"sort={self.sort} name={self.name!r} role={self.role}>"
|
|
)
|