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
@@ -0,0 +1,97 @@
"""create reference tags (文献标签)
Two tables that hold the writer's own labels on the literature:
``reference_tag`` one label: its name, its colour, a note.
``reference_tag_link`` which literature carries which label — two foreign keys
and nothing else, so the *pair* is the primary key. A
reference tagged twice with the same label is therefore
not a duplicate row; it is the same row.
Why this is not a column on ``reference``
-----------------------------------------
``reference.keywords`` already exists and is a different fact: those are the
关键词 printed on the document, part of the citation record. A tag is the
writer's filing (「综述」, 「必读」), it never prints, one document carries
several, and the same label is on many documents. That is a second table by the
same argument that made a citation a table rather than a column.
The link table is named ``_link`` rather than ``_placement`` on purpose: unlike
``template_title_placement`` it carries no ``sort``, so there is no ordering to
own and no payload to grow into. It is a bare link, and the name says so.
Both foreign keys cascade. Deleting a tag removes its labels and leaves the
literature alone — a label is not a claim the paper makes, which is why deleting
a *cited reference* is refused at the API while deleting a tag is not.
Nothing is backfilled: the tables are new and the library starts unlabelled.
Revision ID: 063f6def01fa
Revises: e4b7c1f9a036
Create Date: 2026-09-22
"""
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
# revision identifiers, used by Alembic.
revision: str = "063f6def01fa"
down_revision: str | None = "e4b7c1f9a036"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
_NOW = sa.text("CURRENT_TIMESTAMP")
def upgrade() -> None:
op.create_table(
"reference_tag",
sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
sa.Column("name", sa.String(length=64), nullable=False),
sa.Column(
"color",
sa.String(length=7),
server_default=sa.text("'#409EFF'"),
nullable=False,
),
sa.Column("note", sa.String(length=255), nullable=True),
sa.Column("created_at", sa.DateTime(), server_default=_NOW, nullable=False),
sa.Column("updated_at", sa.DateTime(), server_default=_NOW, nullable=False),
sa.PrimaryKeyConstraint("id"),
# One row per label: two tags spelled the same are the same tag, and
# nothing in the UI could explain a second one.
sa.UniqueConstraint("name", name="uq_reference_tag_name"),
)
op.create_table(
"reference_tag_link",
sa.Column("reference_id", sa.Integer(), nullable=False),
sa.Column("tag_id", sa.Integer(), nullable=False),
sa.ForeignKeyConstraint(
["reference_id"], ["reference.id"], ondelete="CASCADE"
),
sa.ForeignKeyConstraint(
["tag_id"], ["reference_tag.id"], ondelete="CASCADE"
),
# The pair is the identity, so it is the key — which also means the
# table cannot hold the same label on the same document twice.
sa.PrimaryKeyConstraint("reference_id", "tag_id"),
)
# The primary key already serves "what is this document tagged with" (its
# leading column is ``reference_id``); the reverse — "what carries this
# label", which the tag table counts — needs an index of its own.
op.create_index(
"ix_reference_tag_link_tag",
"reference_tag_link",
["tag_id"],
unique=False,
)
def downgrade() -> None:
op.drop_index("ix_reference_tag_link_tag", table_name="reference_tag_link")
op.drop_table("reference_tag_link")
op.drop_table("reference_tag")