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
+30 -5
View File
@@ -15,6 +15,7 @@ from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
from sqlalchemy.orm import Session
from app.crud import reference as crud
from app.crud.reference_tag import UnknownTag
from app.db.session import get_db
from app.models import REFERENCE_TYPES, Reference
from app.schemas.common import BatchDeleteRequest, BatchDeleteResult, PageResult
@@ -64,6 +65,16 @@ def _assert_not_cited(db: Session, references: list[Reference]) -> None:
)
def _unknown_tag(error: UnknownTag) -> HTTPException:
"""Report an applied tag that does not exist as ``400`` naming it.
A ``400`` rather than a ``422``: the body parsed, and the offending value is
a real integer — it is the library that has no such label. The message names
the ids so the client can tell a stale picker from a typo.
"""
return HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(error))
@router.get("", response_model=PageResult[ReferenceListItem], summary="List references")
def list_references(
db: Session = Depends(get_db),
@@ -79,6 +90,10 @@ def list_references(
cited: bool | None = Query(
default=None, description="true 只看已被引用的,false 只看还没用过的"
),
tag: list[int] | None = Query(
default=None,
description="按标签过滤,可重复;给多个标签时取交集(都打了才留下)",
),
page: int = Query(default=1, ge=1),
page_size: int = Query(default=20, ge=1, le=200),
) -> PageResult[ReferenceListItem]:
@@ -89,6 +104,7 @@ def list_references(
type_=type_filter,
year=year,
cited_only=cited,
tag_ids=tag,
page=page,
page_size=page_size,
)
@@ -105,8 +121,12 @@ def create_reference(
payload: ReferenceCreate,
db: Session = Depends(get_db),
) -> ReferenceRead:
"""Add one document to the library, with its contributors in order."""
return crud.read(db, crud.create(db, payload))
"""Add one document to the library, with its contributors and its tags."""
try:
created = crud.create(db, payload)
except UnknownTag as error:
raise _unknown_tag(error) from error
return crud.read(db, created)
@router.post(
@@ -158,11 +178,16 @@ def update_reference(
) -> ReferenceRead:
"""Update any part of a reference.
``authors`` is a full replacement when present — the citation prints them in
the order sent, so there is no partial form of that list.
``authors`` and ``tag_ids`` are full replacements when present — the citation
prints the contributors in the order sent, and the tag list *is* the set of
labels on the row, so ``[]`` clears them.
"""
reference = _get_or_404(db, reference_id)
return crud.read(db, crud.update(db, reference, payload))
try:
updated = crud.update(db, reference, payload)
except UnknownTag as error:
raise _unknown_tag(error) from error
return crud.read(db, updated)
@router.delete(