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