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:
@@ -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")
|
||||
Reference in New Issue
Block a user