backend: tag the literature, in a table of its own

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.
This commit is contained in:
2026-09-22 17:55:15 +08:00
parent d7bb777264
commit 6020310b3f
14 changed files with 1042 additions and 29 deletions
+20
View File
@@ -32,6 +32,14 @@ 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,
@@ -51,6 +59,7 @@ 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.
#:
@@ -238,5 +247,16 @@ class Reference(TimestampMixin, Base):
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}>"