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
+2 -2
View File
@@ -5,6 +5,6 @@ models. They own the commit: a route calls one function and gets back either a
persisted object or ``None``.
"""
from app.crud import paper, reference, template, template_title
from app.crud import paper, reference, reference_tag, template, template_title
__all__ = ["paper", "reference", "template", "template_title"]
__all__ = ["paper", "reference", "reference_tag", "template", "template_title"]
+53 -4
View File
@@ -8,6 +8,10 @@ table row never has to load the rows behind it.
Writes keep the two lists (authors, citations) on their own side: authors belong
to the reference and are replaced wholesale, citations belong to the papers that
made them and are never touched from here.
Tags are the third list and follow the same rule as authors — sent as ids, stored
as links, replaced wholesale — except that the ids must already exist: a tag is
made first and applied second, so a typo cannot invent a label.
"""
from collections.abc import Sequence
@@ -15,6 +19,7 @@ from collections.abc import Sequence
from sqlalchemy import Select, func, or_, select
from sqlalchemy.orm import Session
from app.crud import reference_tag as tag_crud
from app.crud.filters import LIKE_ESCAPE, like_pattern
from app.models import (
Paper,
@@ -22,8 +27,10 @@ from app.models import (
PaperSentenceReference,
Reference,
ReferenceAuthor,
ReferenceTag,
TemplateTitle,
TemplateTitlePlacement,
reference_tag_link,
)
from app.schemas.reference import (
ReferenceCitationRead,
@@ -32,6 +39,7 @@ from app.schemas.reference import (
ReferenceRead,
ReferenceUpdate,
)
from app.schemas.reference_tag import ReferenceTagRef
#: How many authors a table row prints before it cuts the line short.
_LIST_AUTHOR_LIMIT = 3
@@ -42,6 +50,7 @@ def _conditions(
type_: str | None,
year: int | None,
cited_only: bool | None,
tag_ids: Sequence[int] | None = None,
) -> list:
"""Translate the list filters into SQLAlchemy predicates."""
conditions = []
@@ -73,6 +82,18 @@ def _conditions(
conditions.append(_citation_count_column() > 0)
if cited_only is False:
conditions.append(_citation_count_column() == 0)
# One EXISTS per tag rather than an IN over the link table: IN would ask
# "carries at least one of these", while repeated filters read as a
# narrowing — 「方法」 plus 「必读」 means both labels are on the row.
for tag_id in dict.fromkeys(tag_ids or ()):
conditions.append(
select(reference_tag_link.c.reference_id)
.where(
reference_tag_link.c.reference_id == Reference.id,
reference_tag_link.c.tag_id == tag_id,
)
.exists()
)
return conditions
@@ -119,11 +140,12 @@ def list_references(
type_: str | None = None,
year: int | None = None,
cited_only: bool | None = None,
tag_ids: Sequence[int] | None = None,
page: int = 1,
page_size: int = 20,
) -> tuple[list[ReferenceListItem], int]:
"""Return one page of the library, plus the unpaged total."""
conditions = _conditions(keyword, type_, year, cited_only)
conditions = _conditions(keyword, type_, year, cited_only, tag_ids)
total = db.scalar(select(func.count(Reference.id)).where(*conditions)) or 0
@@ -147,6 +169,7 @@ def list_references(
title=row.title,
subtitle=row.subtitle,
container_title=row.container_title,
publisher=row.publisher,
publication_year=row.publication_year,
volume=row.volume,
issue=row.issue,
@@ -154,6 +177,7 @@ def list_references(
doi=row.doi,
authors_line=authors_line(row.authors),
author_count=len(row.authors),
tags=[ReferenceTagRef.model_validate(tag) for tag in row.tags],
citation_count=counts.get(row.id, 0),
created_at=row.created_at,
updated_at=row.updated_at,
@@ -241,6 +265,7 @@ def read(db: Session, reference: Reference) -> ReferenceRead:
for column in Reference.__table__.columns
},
"authors": reference.authors,
"tags": reference.tags,
"citation_count": counts.get(reference.id, 0),
}
)
@@ -263,16 +288,28 @@ def _build_authors(
def create(db: Session, data: ReferenceCreate) -> Reference:
"""Insert a reference together with its contributors."""
values = data.model_dump(exclude={"authors"})
"""Insert a reference together with its contributors and its tags."""
tags = _resolve_tags(db, data.tag_ids)
values = data.model_dump(exclude={"authors", "tag_ids"})
reference = Reference(**values)
reference.authors = _build_authors(data.authors)
reference.tags = tags
db.add(reference)
db.commit()
db.refresh(reference)
return reference
def _resolve_tags(db: Session, tag_ids: Sequence[int]) -> list[ReferenceTag]:
"""Load the tags to apply, refusing ids the library does not have.
Nothing is written before this returns, so a reference naming a tag that
does not exist is rejected whole rather than stored half-labelled.
"""
tag_crud.assert_exist(db, tag_ids)
return tag_crud.get_many(db, tag_ids)
def update(
db: Session,
reference: Reference,
@@ -283,8 +320,14 @@ def update(
``exclude_unset`` is what makes PATCH semantics work: a key the client did
not send leaves the column alone, so clearing a field is an explicit
``null`` and omitting it is not.
``authors`` and ``tag_ids`` are full replacements when present — the first
because a citation prints the list in the order sent, the second because the
list *is* the set of labels on the row.
"""
values = data.model_dump(exclude_unset=True, exclude={"authors"})
tags = _resolve_tags(db, data.tag_ids) if data.tag_ids is not None else None
values = data.model_dump(exclude_unset=True, exclude={"authors", "tag_ids"})
for key, value in values.items():
setattr(reference, key, value)
@@ -295,6 +338,12 @@ def update(
db.flush()
reference.authors.extend(_build_authors(data.authors))
if tags is not None:
# Assigning to a secondary relationship rewrites the link rows: the ones
# that stayed are untouched, the new ones are inserted, the dropped ones
# deleted. An empty list therefore clears every label.
reference.tags = tags
db.commit()
db.refresh(reference)
return reference
+254
View File
@@ -0,0 +1,254 @@
"""Data access for the reference tags (文献标签).
A tag library is small and is read whole — the picker in the reference form and
the rail in the shell both want every label — so the list here is paged only to
keep the shape of every other list endpoint, not because a page is expected.
Each tag carries how many references hold it. The number is what makes the table
useful ("is this label actually used?") and what the delete confirmation warns
about, and it is a grouped count over the link table rather than a loop.
Two refusals live here because they are domain rules, not HTTP ones:
* **A name is unique.** Two tags spelled the same would be one label under two
ids, and nothing in the UI could explain the difference.
* **A tag must exist before it is applied.** Applying one is a write to the link
table, and the layer that knows a label is missing is this one — so it says so
by name, in the same way the reference side names a citation to literature the
library does not have.
"""
from collections.abc import Sequence
from sqlalchemy import Select, func, or_, select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.orm import Session
from app.crud.filters import LIKE_ESCAPE, like_pattern
from app.models import ReferenceTag, reference_tag_link
from app.schemas.reference_tag import (
ReferenceTagCreate,
ReferenceTagRead,
ReferenceTagUpdate,
)
class DuplicateTagName(ValueError):
"""A write asked for a tag name that is already taken."""
def __init__(self, name: str) -> None:
self.name = name
super().__init__(f"标签「{name}」已存在")
class UnknownTag(ValueError):
"""A write named a tag the library does not have."""
def __init__(self, missing: Sequence[int]) -> None:
self.missing = list(missing)
joined = "、".join(str(tag_id) for tag_id in self.missing)
super().__init__(f"标签不存在:{joined}")
def _conditions(keyword: str | None) -> list:
"""Translate the list filters into SQLAlchemy predicates."""
conditions = []
if keyword:
pattern = like_pattern(keyword)
conditions.append(
or_(
ReferenceTag.name.like(pattern, escape=LIKE_ESCAPE),
ReferenceTag.note.like(pattern, escape=LIKE_ESCAPE),
)
)
return conditions
def _ordered(stmt: Select) -> Select:
"""Alphabetical, then by insertion order for a stable tie-break.
A tag library is scanned by name — the writer looks for 「方法」 where they
expect it — which is the opposite of the reference list, where the newest
publication leads.
"""
return stmt.order_by(ReferenceTag.name.asc(), ReferenceTag.id.asc())
def reference_counts(db: Session, tag_ids: Sequence[int]) -> dict[int, int]:
"""How many references carry each tag.
``COUNT`` over the link table, grouped — the number of *links*, which is the
number of references because the pair is the primary key.
"""
wanted = list({tag_id for tag_id in tag_ids})
if not wanted:
return {}
stmt = (
select(reference_tag_link.c.tag_id, func.count(reference_tag_link.c.reference_id))
.where(reference_tag_link.c.tag_id.in_(wanted))
.group_by(reference_tag_link.c.tag_id)
)
return {tag_id: count for tag_id, count in db.execute(stmt).all()}
def read(db: Session, tag: ReferenceTag) -> ReferenceTagRead:
"""Build the payload for one tag, count included."""
counts = reference_counts(db, [tag.id])
return ReferenceTagRead.model_validate(
{
"id": tag.id,
"name": tag.name,
"color": tag.color,
"note": tag.note,
"reference_count": counts.get(tag.id, 0),
"created_at": tag.created_at,
"updated_at": tag.updated_at,
}
)
def list_tags(
db: Session,
*,
keyword: str | None = None,
page: int = 1,
page_size: int = 50,
) -> tuple[list[ReferenceTagRead], int]:
"""Return one page of the tag library, plus the unpaged total."""
conditions = _conditions(keyword)
total = db.scalar(select(func.count(ReferenceTag.id)).where(*conditions)) or 0
stmt = _ordered(
select(ReferenceTag)
.where(*conditions)
.offset((page - 1) * page_size)
.limit(page_size)
)
rows = list(db.scalars(stmt).all())
counts = reference_counts(db, [row.id for row in rows])
items = [
ReferenceTagRead.model_validate(
{
"id": row.id,
"name": row.name,
"color": row.color,
"note": row.note,
"reference_count": counts.get(row.id, 0),
"created_at": row.created_at,
"updated_at": row.updated_at,
}
)
for row in rows
]
return items, total
def get(db: Session, tag_id: int) -> ReferenceTag | None:
"""Return one tag, or ``None``."""
return db.get(ReferenceTag, tag_id)
def get_many(db: Session, tag_ids: Sequence[int]) -> list[ReferenceTag]:
"""Return every tag whose id is in ``tag_ids`` (missing ids ignored)."""
if not tag_ids:
return []
stmt = select(ReferenceTag).where(ReferenceTag.id.in_(list(tag_ids)))
return list(db.scalars(stmt).all())
def by_name(db: Session, name: str) -> ReferenceTag | None:
"""Return the tag with this exact name, or ``None``.
Used by the create/rename guard, and by nothing else — a lookup by id is
what the rest of the application does.
"""
return db.scalar(select(ReferenceTag).where(ReferenceTag.name == name))
def missing_ids(db: Session, tag_ids: Sequence[int]) -> list[int]:
"""Which of ``tag_ids`` are not in the library, sorted."""
wanted = set(tag_ids)
if not wanted:
return []
found = set(
db.scalars(select(ReferenceTag.id).where(ReferenceTag.id.in_(wanted))).all()
)
return sorted(wanted - found)
def assert_exist(db: Session, tag_ids: Sequence[int]) -> None:
"""Refuse a write that applies tags the library does not have."""
missing = missing_ids(db, tag_ids)
if missing:
raise UnknownTag(missing)
def _assert_name_free(db: Session, name: str, *, except_id: int | None = None) -> None:
"""Refuse a name another tag already holds.
Checked before the insert so the failure is a message naming the label
rather than a raw unique-constraint error from the driver. The constraint
stays as the authority; this is the explanation.
"""
existing = by_name(db, name)
if existing is not None and existing.id != except_id:
raise DuplicateTagName(name)
def create(db: Session, data: ReferenceTagCreate) -> ReferenceTag:
"""Insert a tag."""
_assert_name_free(db, data.name)
tag = ReferenceTag(**data.model_dump())
db.add(tag)
try:
db.commit()
except IntegrityError as error: # pragma: no cover - lost race only
db.rollback()
raise DuplicateTagName(data.name) from error
db.refresh(tag)
return tag
def update(db: Session, tag: ReferenceTag, data: ReferenceTagUpdate) -> ReferenceTag:
"""Apply a partial update.
Renaming is visible everywhere the label is used, because a reference links
to the tag rather than storing its name — the same reason renaming a heading
updates every template that places it.
"""
values = data.model_dump(exclude_unset=True)
name = values.get("name")
if name is not None and name != tag.name:
_assert_name_free(db, name, except_id=tag.id)
for key, value in values.items():
setattr(tag, key, value)
try:
db.commit()
except IntegrityError as error: # pragma: no cover - lost race only
db.rollback()
raise DuplicateTagName(name or tag.name) from error
db.refresh(tag)
return tag
def delete(db: Session, tag: ReferenceTag) -> None:
"""Delete a tag.
Its links go with it — both sides cascade — so the literature keeps its
place in the library and only loses the label. Callers do not need to check
usage first: unlike a citation, a label is not a claim the paper makes.
"""
db.delete(tag)
db.commit()
def delete_many(db: Session, tag_ids: Sequence[int]) -> int:
"""Delete several tags, returning how many actually existed."""
tags = get_many(db, tag_ids)
for tag in tags:
db.delete(tag)
db.commit()
return len(tags)