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
+12
View File
@@ -19,6 +19,10 @@ after its table (``Template`` -> ``template``):
paper the 论文 module
paper_sentence one sentence of one paper
paper_sentence_reference a citation of one sentence
reference the 参考文献 module
reference_author its contributors, in print order
reference_tag the writer's labels (文献标签)
reference_tag_link which literature carries which label
``template_title_placement`` and ``template_title`` are one word apart and mean
opposite things: the first is a *placement* (this template puts this field
@@ -42,11 +46,17 @@ from app.models.reference import (
Reference,
)
from app.models.reference_author import ReferenceAuthor
from app.models.reference_tag import (
DEFAULT_TAG_COLOR,
ReferenceTag,
reference_tag_link,
)
from app.models.template import Template
from app.models.template_title_placement import TemplateTitlePlacement
from app.models.template_title import TemplateTitle
__all__ = [
"DEFAULT_TAG_COLOR",
"PAPER_STATUSES",
"STATUS_DONE",
"STATUS_DRAFT",
@@ -59,8 +69,10 @@ __all__ = [
"REFERENCE_TYPES",
"Reference",
"ReferenceAuthor",
"ReferenceTag",
"Template",
"TemplateTitlePlacement",
"TemplateTitle",
"TimestampMixin",
"reference_tag_link",
]
+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}>"
+127
View File
@@ -0,0 +1,127 @@
"""Tags on the literature (文献标签).
A tag is a label the *writer* puts on a document — 「综述」, 「方法」,
「必读」, 「待精读」 — so a library of a few hundred entries can be narrowed to
the handful that matter for the paragraph being written. It is a filing decision,
not a fact about the document, which is why it is not the same thing as
:attr:`~app.models.reference.Reference.keywords`: those are the 关键词 printed
on the article itself and belong to the citation record, while a tag belongs to
the writer and never prints. One column could not hold both, so they do not
share one.
Two tables, following the naming rule of this package (a module's name plus what
the table holds):
reference_tag one label: its name, and the colour a table paints it in
reference_tag_link which literature carries which label
Why the link is a bare link
---------------------------
A tag on a reference carries nothing of its own: no position, no mark, no text.
It is only "this label applies to this document". That is exactly the case where
``template_title_placement`` had to be a *placement* — it carries ``sort``, the
only home of display order — and here there is no such column, so the pair is
the primary key and the table is named ``_link`` for what it honestly is. A
reference tagged twice with the same tag is therefore not a duplicate row: it is
the same row, because the pair is the identity.
One label, one row
------------------
``name`` is unique. Two tags spelled 「方法」 are one tag, and the API refuses
the second with a message naming it rather than letting a library accumulate
labels that differ only by a trailing space. Nothing else about a tag is
canonical: the colour is decoration, and the note is for the writer.
Deleting a tag deletes labels, not literature
---------------------------------------------
Both foreign keys cascade, so removing a tag removes its links and leaves the
documents alone. That is the opposite of what happens to a reference a sentence
cites — a citation is a claim the paper makes, while a label is only a way of
finding the row again — and the API allows it for the same reason it refuses the
other.
"""
from typing import TYPE_CHECKING
from sqlalchemy import (
Column,
ForeignKey,
Index,
Integer,
String,
Table,
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 import Reference
#: Which literature carries which label.
#:
#: A Core ``Table`` rather than a mapped class: the pair *is* the row, so there
#: is no attribute to declare and nothing to add later without changing what the
#: table means. Both sides cascade, so deleting a reference or a tag takes its
#: links with it and never leaves a label pointing at a row that is gone.
reference_tag_link = Table(
"reference_tag_link",
Base.metadata,
Column(
"reference_id",
Integer,
ForeignKey("reference.id", ondelete="CASCADE"),
primary_key=True,
),
Column(
"tag_id",
Integer,
ForeignKey("reference_tag.id", ondelete="CASCADE"),
primary_key=True,
),
# The primary key is already the index a reference's own tags are read
# through (its leading column is ``reference_id``). The reverse question —
# "which literature carries this tag?", which is what the tag table's count
# and the by-tag filter ask — needs its own.
Index("ix_reference_tag_link_tag", "tag_id"),
)
#: The colour a new tag is given when the writer does not pick one.
DEFAULT_TAG_COLOR = "#409EFF"
class ReferenceTag(TimestampMixin, Base):
"""One label in the reference module's tag library."""
__tablename__ = "reference_tag"
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
#: The label as the writer types it. Unique: a second tag with the same
#: spelling would be the same label under another id.
name: Mapped[str] = mapped_column(String(64), nullable=False, unique=True)
#: ``#RRGGBB``, normalised on write exactly as a heading's colour is, so the
#: table can paint it without parsing. Decoration only — nothing reads it.
color: Mapped[str] = mapped_column(
String(7),
nullable=False,
default=DEFAULT_TAG_COLOR,
server_default=text("'#409EFF'"),
)
#: Free text: what the label is for, who else uses it, when to apply it.
note: Mapped[str | None] = mapped_column(String(255), nullable=True)
#: The literature carrying this label, ordered by when each tag was created
#: so the same reference always prints its labels in the same order.
references: Mapped[list["Reference"]] = relationship(
secondary=reference_tag_link,
back_populates="tags",
order_by="Reference.id",
)
def __repr__(self) -> str: # pragma: no cover - debugging aid
return f"<ReferenceTag id={self.id} name={self.name!r} color={self.color}>"