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.
263 lines
12 KiB
Python
263 lines
12 KiB
Python
"""The reference library (参考文献库) — the literature a paper cites.
|
|
|
|
One row is one document the writer has read and may cite: a journal article, a
|
|
conference paper, a book, a patent, a standard, a dataset. It is **global**, not
|
|
owned by a paper, because the same article is cited from several papers — and
|
|
the citation itself (which sentence quotes which passage) belongs to the paper,
|
|
in :class:`~app.models.paper_sentence_reference.PaperSentenceReference`.
|
|
|
|
Why these columns
|
|
-----------------
|
|
The field set is the intersection of the formats a Chinese journal paper
|
|
actually has to survive, so that one row can be rendered as any of them without
|
|
a second home for anything:
|
|
|
|
* **CSL JSON** (``csl-data.json``, 103 fields / 45 types) — what Zotero,
|
|
Mendeley and Pandoc exchange. Our names follow it wherever a field is the
|
|
same field: ``title``, ``container-title``, ``volume``, ``issue``, ``page``,
|
|
``publisher``, ``publisher-place``, ``edition``, ``DOI``, ``ISBN``,
|
|
``ISSN``, ``URL``, ``abstract``, ``keyword``, ``language``, ``note``,
|
|
``citation-key``, ``event-title``, ``event-place``, ``issued``, ``accessed``.
|
|
* **GB/T 7714-2015** — the Chinese national standard a domestic journal will
|
|
demand. It is why every entry carries a ``type`` with a marker, and why
|
|
patents need ``patent_country`` and ``patent_number``, standards need
|
|
``standard_number``, and online resources need ``accessed_date``.
|
|
* **BibTeX / RIS** — the export formats a reference manager is judged by.
|
|
``citation_key`` is the BibTeX key; the rest map one-to-one with the fields
|
|
above.
|
|
|
|
Contributors are **not** columns: a document has an ordered list of them, each
|
|
with a role, which is what :class:`~app.models.reference_author.ReferenceAuthor`
|
|
holds. Formats disagree about names anyway — 「张三」, ``Zhang San``,
|
|
``Zhang, S.`` are the same person in three styles — so the printed form and the
|
|
two halves are stored separately and a style picks what it needs.
|
|
|
|
Labels are not columns either
|
|
-----------------------------
|
|
``keywords`` here are the 关键词 printed on the document — part of the citation
|
|
record. The writer's *own* filing of a row (「综述」, 「必读」) is a different
|
|
fact with a different lifetime, and it lives in
|
|
:mod:`app.models.reference_tag`, reachable as :attr:`Reference.tags`. A tag never
|
|
prints in a reference list, so it must not be able to reach one by accident.
|
|
|
|
What is deliberately missing
|
|
----------------------------
|
|
The 103 CSL fields include roles this project will never print (narrator,
|
|
performer, chair, illustrator, curator…) and archival fields (call-number,
|
|
archive-place). Adding a column for each would be a schema nobody reads. They
|
|
can arrive when a real citation needs one.
|
|
"""
|
|
|
|
from datetime import date
|
|
from typing import TYPE_CHECKING
|
|
|
|
from sqlalchemy import Date, Index, Integer, SmallInteger, String, Text, text
|
|
from sqlalchemy.orm import Mapped, mapped_column, relationship
|
|
|
|
from app.db.base import Base
|
|
from app.models.mixins import TimestampMixin
|
|
|
|
if TYPE_CHECKING: # pragma: no cover - typing only
|
|
from app.models.reference_author import ReferenceAuthor
|
|
from app.models.reference_tag import ReferenceTag
|
|
|
|
#: Document types this library holds, with the marker each format uses for it.
|
|
#:
|
|
#: ====================== ================ ========= ==========================
|
|
#: our value CSL type GB/T [X] example
|
|
#: ====================== ================ ========= ==========================
|
|
#: journal-article article-journal [J] 期刊论文
|
|
#: book book [M] 专著
|
|
#: book-chapter chapter [M] 析出文献(书里的一章)
|
|
#: conference-paper paper-conference [C] 会议论文
|
|
#: thesis thesis [D] 学位论文
|
|
#: patent patent [P] 专利
|
|
#: standard standard [S] 标准
|
|
#: report report [R] 报告
|
|
#: newspaper-article article-newspaper[N] 报纸文章
|
|
#: web-page webpage [EB/OL] 网页/在线资源
|
|
#: dataset dataset [DS] 数据集
|
|
#: software software [CP] 计算机程序
|
|
#: preprint article [EB/OL] 预印本(arXiv 等)
|
|
#: other document [Z] 其他
|
|
#: ====================== ================ ========= ==========================
|
|
REFERENCE_TYPES: tuple[str, ...] = (
|
|
"journal-article",
|
|
"book",
|
|
"book-chapter",
|
|
"conference-paper",
|
|
"thesis",
|
|
"patent",
|
|
"standard",
|
|
"report",
|
|
"newspaper-article",
|
|
"web-page",
|
|
"dataset",
|
|
"software",
|
|
"preprint",
|
|
"other",
|
|
)
|
|
|
|
#: The roles a contributor can have. ``author`` is the default and the one that
|
|
#: prints in the citation; the others carry the 编 / 译 / 主编 marks that GB/T
|
|
#: 7714 puts after a name.
|
|
REFERENCE_AUTHOR_ROLES: tuple[str, ...] = (
|
|
"author",
|
|
"editor",
|
|
"translator",
|
|
"compiler",
|
|
)
|
|
|
|
#: Languages a row is written in — used to choose which title is primary and
|
|
#: which is the 并列题名.
|
|
REFERENCE_LANGUAGES: tuple[str, ...] = ("zh", "en", "ja", "other")
|
|
|
|
|
|
class Reference(TimestampMixin, Base):
|
|
"""One document in the reference library."""
|
|
|
|
__tablename__ = "reference"
|
|
|
|
__table_args__ = (
|
|
# The list endpoint filters by type and orders by year, which this
|
|
# serves. There is deliberately no index on ``title``: the search box
|
|
# matches with a leading wildcard, which no B-tree can use.
|
|
Index("ix_reference_type_year", "type", "publication_year"),
|
|
)
|
|
|
|
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
|
|
|
|
#: One of :data:`REFERENCE_TYPES`. Stored as the token, never the Chinese
|
|
#: label, so the wording can change without a migration.
|
|
type: Mapped[str] = mapped_column(
|
|
String(32),
|
|
nullable=False,
|
|
default="journal-article",
|
|
server_default=text("'journal-article'"),
|
|
)
|
|
|
|
# --- the document's name ------------------------------------------------
|
|
#: 题名, as printed.
|
|
title: Mapped[str] = mapped_column(String(512), nullable=False)
|
|
|
|
#: 其他题名信息 — the part after a colon (": 基于……的实证研究").
|
|
subtitle: Mapped[str | None] = mapped_column(String(512), nullable=True)
|
|
|
|
#: 并列题名 / 译名 — the title in the other language, which a bilingual
|
|
#: manuscript prints alongside the first.
|
|
title_translated: Mapped[str | None] = mapped_column(String(512), nullable=True)
|
|
|
|
#: Short form for in-text citations (CSL ``title-short``).
|
|
title_short: Mapped[str | None] = mapped_column(String(255), nullable=True)
|
|
|
|
# --- where it was published --------------------------------------------
|
|
#: 刊名 / 书名 / 论文集名 / 报纸名 — the container the entry sits in.
|
|
container_title: Mapped[str | None] = mapped_column(String(512), nullable=True)
|
|
|
|
#: 刊名缩写 (CSL ``container-title-short``). Some styles print only this.
|
|
container_title_short: Mapped[str | None] = mapped_column(
|
|
String(255), nullable=True
|
|
)
|
|
|
|
#: 丛书 / 系列名, and its number.
|
|
series_title: Mapped[str | None] = mapped_column(String(512), nullable=True)
|
|
series_number: Mapped[str | None] = mapped_column(String(32), nullable=True)
|
|
|
|
#: 版本项 — "3版", "2nd ed.".
|
|
edition: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
|
|
|
#: 卷 and 期. Strings rather than integers: journals print "12(Suppl.)",
|
|
#: "S1" and "春季号", and a citation has to reproduce what is printed.
|
|
volume: Mapped[str | None] = mapped_column(String(32), nullable=True)
|
|
issue: Mapped[str | None] = mapped_column(String(32), nullable=True)
|
|
|
|
#: 页码, as printed — "1024-1032", "e12345", "12-15, 20".
|
|
pages: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
|
|
|
#: 文章编号 / eLocation, for journals that have no page numbers.
|
|
article_number: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
|
|
|
# --- publisher ----------------------------------------------------------
|
|
#: 出版者. For a thesis this is the 保存者 (the university), for a report the
|
|
#: issuing body, for a standard the publisher — the same role in three
|
|
#: formats, which is why there is one column and not three.
|
|
publisher: Mapped[str | None] = mapped_column(String(255), nullable=True)
|
|
|
|
#: 出版地.
|
|
publisher_place: Mapped[str | None] = mapped_column(String(255), nullable=True)
|
|
|
|
# --- events (conferences) ----------------------------------------------
|
|
#: 会议名称 / 会议地点 / 会期. GB/T prints the proceedings title, APA and
|
|
#: IEEE print the meeting, and a conference paper usually needs both.
|
|
event_title: Mapped[str | None] = mapped_column(String(512), nullable=True)
|
|
event_place: Mapped[str | None] = mapped_column(String(255), nullable=True)
|
|
#: Free text on purpose: conferences run "2024-05-01/03" and styles print
|
|
#: the range as written.
|
|
event_date: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
|
|
|
# --- dates --------------------------------------------------------------
|
|
# Partial dates, exactly as CSL models ``issued``: a book has a year, a
|
|
# newspaper article has a day, a patent has its 公告日期.
|
|
publication_year: Mapped[int | None] = mapped_column(SmallInteger, nullable=True)
|
|
publication_month: Mapped[int | None] = mapped_column(SmallInteger, nullable=True)
|
|
publication_day: Mapped[int | None] = mapped_column(SmallInteger, nullable=True)
|
|
|
|
#: 引用日期 — required by GB/T 7714 for anything online, because a URL's
|
|
#: content can change after it was read.
|
|
accessed_date: Mapped[date | None] = mapped_column(Date, nullable=True)
|
|
|
|
# --- identifiers --------------------------------------------------------
|
|
#: Canonical DOI, without the ``https://doi.org/`` prefix.
|
|
doi: Mapped[str | None] = mapped_column(String(255), nullable=True)
|
|
isbn: Mapped[str | None] = mapped_column(String(32), nullable=True)
|
|
issn: Mapped[str | None] = mapped_column(String(32), nullable=True)
|
|
url: Mapped[str | None] = mapped_column(String(1024), nullable=True)
|
|
|
|
#: 专利国别 + 专利号 — GB/T 7714 prints both inside the [P] marker.
|
|
patent_country: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
|
patent_number: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
|
|
|
#: 标准编号 ("GB/T 7714-2015") and 报告编号.
|
|
standard_number: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
|
report_number: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
|
|
|
#: Preprint identifier ("arXiv:2405.12345"), which is how an AI paper is
|
|
#: cited before it has a DOI.
|
|
arxiv_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
|
|
|
# --- the writer's own notes --------------------------------------------
|
|
abstract: Mapped[str | None] = mapped_column(Text, nullable=True)
|
|
#: 文献关键词, comma-separated like the paper's own keywords.
|
|
keywords: Mapped[str | None] = mapped_column(String(512), nullable=True)
|
|
#: Free text: why it was kept, what it is for, where the PDF is.
|
|
note: Mapped[str | None] = mapped_column(Text, nullable=True)
|
|
|
|
# --- library metadata ---------------------------------------------------
|
|
#: The BibTeX key (CSL ``citation-key``), for export.
|
|
citation_key: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
|
|
|
#: One of :data:`REFERENCE_LANGUAGES`; decides which title leads.
|
|
language: Mapped[str | None] = mapped_column(String(16), nullable=True)
|
|
|
|
#: The contributors, in the order the citation prints them.
|
|
authors: Mapped[list["ReferenceAuthor"]] = relationship(
|
|
back_populates="reference",
|
|
cascade="all, delete-orphan",
|
|
order_by="ReferenceAuthor.sort, ReferenceAuthor.id",
|
|
lazy="selectin",
|
|
)
|
|
|
|
#: The writer's own labels (:mod:`app.models.reference_tag`). Not a column of
|
|
#: the citation: a document may carry several, the same label is on many
|
|
#: documents, and none of them prints. Loaded eagerly for the same reason the
|
|
#: contributors are — every table row shows them.
|
|
tags: Mapped[list["ReferenceTag"]] = relationship(
|
|
secondary="reference_tag_link",
|
|
back_populates="references",
|
|
order_by="ReferenceTag.id",
|
|
lazy="selectin",
|
|
)
|
|
|
|
def __repr__(self) -> str: # pragma: no cover - debugging aid
|
|
return f"<Reference id={self.id} type={self.type} title={self.title!r}>"
|