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
+16
View File
@@ -23,6 +23,7 @@ from app.models.reference import (
REFERENCE_LANGUAGES,
REFERENCE_TYPES,
)
from app.schemas.reference_tag import ReferenceTagRef
#: Prefixes people paste along with a DOI. Stripped on write so the column has
#: one spelling, and so a citation builder never has to test for them.
@@ -141,6 +142,10 @@ class ReferenceBase(BaseModel):
citation_key: str | None = Field(default=None, max_length=64)
language: str | None = Field(default=None, max_length=16)
authors: list[ReferenceAuthorInput] = Field(default_factory=list)
#: The tags to apply, by id. Tags are made first and applied second, so this
#: names labels that already exist rather than carrying spellings that could
#: invent new ones. Unknown ids are refused by name.
tag_ids: list[int] = Field(default_factory=list)
@field_validator("title")
@classmethod
@@ -269,6 +274,10 @@ class ReferenceUpdate(BaseModel):
citation_key: str | None = Field(default=None, max_length=64)
language: str | None = Field(default=None, max_length=16)
authors: list[ReferenceAuthorInput] | None = None
#: Full replacement when present, like ``authors``: the list is the set of
#: labels on the row, so sending it means "these and no others" and ``[]``
#: clears every label. Omitting the key leaves the labels alone.
tag_ids: list[int] | None = None
@field_validator("title")
@classmethod
@@ -312,6 +321,9 @@ class ReferenceListItem(BaseModel):
title: str
subtitle: str | None
container_title: str | None
#: 出版者. Carried on the row because a book, a thesis and a report have no
#: container to show and the publisher *is* their "where".
publisher: str | None
publication_year: int | None
volume: str | None
issue: str | None
@@ -321,6 +333,9 @@ class ReferenceListItem(BaseModel):
#: rows behind it.
authors_line: str
author_count: int
#: The labels the writer put on it, ready to paint. Loading them here rather
#: than per row is what keeps a page of the library one query for the tags.
tags: list[ReferenceTagRef] = Field(default_factory=list)
#: How many sentences cite it. Drives the refusal message on delete, and
#: tells the writer at a glance what is already used.
citation_count: int
@@ -370,6 +385,7 @@ class ReferenceRead(BaseModel):
citation_key: str | None
language: str | None
authors: list[ReferenceAuthorRead]
tags: list[ReferenceTagRef] = Field(default_factory=list)
citation_count: int
created_at: datetime
updated_at: datetime