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
+9 -1
View File
@@ -2,11 +2,19 @@
from fastapi import APIRouter
from app.api.routes import health, papers, references, template_titles, templates
from app.api.routes import (
health,
papers,
reference_tags,
references,
template_titles,
templates,
)
api_router = APIRouter()
api_router.include_router(health.router)
api_router.include_router(papers.router)
api_router.include_router(reference_tags.router)
api_router.include_router(references.router)
api_router.include_router(template_titles.router)
api_router.include_router(templates.router)
+128
View File
@@ -0,0 +1,128 @@
"""Reference-tag endpoints (文献标签).
The label library the reference table and the reference form draw on. It is
managed first and applied second: a reference is created *with* tags, and an id
that names a label that does not exist is refused rather than silently ignored.
Deleting a tag is **not** guarded the way deleting a field or a cited reference
is. A tag is the writer's own filing — it says "this is one of the papers I
should reread", not something the document claims — so removing it removes
labels and leaves the literature exactly where it was. The confirmation in the
UI says how many rows will lose the label, which is the honest form of that
warning.
"""
from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
from sqlalchemy.orm import Session
from app.crud import reference_tag as crud
from app.crud.reference_tag import DuplicateTagName
from app.db.session import get_db
from app.models import ReferenceTag
from app.schemas.common import BatchDeleteRequest, BatchDeleteResult, PageResult
from app.schemas.reference_tag import (
ReferenceTagCreate,
ReferenceTagRead,
ReferenceTagUpdate,
)
router = APIRouter(prefix="/reference-tags", tags=["reference-tags"])
def _get_or_404(db: Session, tag_id: int) -> ReferenceTag:
tag = crud.get(db, tag_id)
if tag is None:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=f"标签 {tag_id} 不存在",
)
return tag
def _conflict(error: DuplicateTagName) -> HTTPException:
"""Report a taken name as ``409`` naming the label."""
return HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(error))
@router.get("", response_model=PageResult[ReferenceTagRead], summary="List tags")
def list_tags(
db: Session = Depends(get_db),
keyword: str | None = Query(default=None, description="按标签名称或备注模糊搜索"),
page: int = Query(default=1, ge=1),
page_size: int = Query(default=50, ge=1, le=500),
) -> PageResult[ReferenceTagRead]:
"""Browse the tag library, alphabetical, each with how many rows carry it."""
items, total = crud.list_tags(
db,
keyword=keyword,
page=page,
page_size=page_size,
)
return PageResult.build(items=items, total=total, page=page, page_size=page_size)
@router.post(
"",
response_model=ReferenceTagRead,
status_code=status.HTTP_201_CREATED,
summary="Create a tag",
)
def create_tag(
payload: ReferenceTagCreate,
db: Session = Depends(get_db),
) -> ReferenceTagRead:
"""Add one label to the library."""
try:
tag = crud.create(db, payload)
except DuplicateTagName as error:
raise _conflict(error) from error
return crud.read(db, tag)
@router.post(
"/batch-delete",
response_model=BatchDeleteResult,
summary="Delete several tags",
)
def batch_delete_tags(
payload: BatchDeleteRequest,
db: Session = Depends(get_db),
) -> BatchDeleteResult:
"""Delete the given tags, removing their labels from the literature."""
return BatchDeleteResult(deleted=crud.delete_many(db, payload.ids))
@router.get("/{tag_id}", response_model=ReferenceTagRead, summary="Fetch one tag")
def get_tag(tag_id: int, db: Session = Depends(get_db)) -> ReferenceTagRead:
"""Return one label, with how many references carry it."""
return crud.read(db, _get_or_404(db, tag_id))
@router.patch("/{tag_id}", response_model=ReferenceTagRead, summary="Update a tag")
def update_tag(
tag_id: int,
payload: ReferenceTagUpdate,
db: Session = Depends(get_db),
) -> ReferenceTagRead:
"""Rename or recolour a label.
Every reference carrying it follows, because a reference links to the tag
rather than storing its name.
"""
tag = _get_or_404(db, tag_id)
try:
updated = crud.update(db, tag, payload)
except DuplicateTagName as error:
raise _conflict(error) from error
return crud.read(db, updated)
@router.delete(
"/{tag_id}",
status_code=status.HTTP_204_NO_CONTENT,
summary="Delete a tag",
)
def delete_tag(tag_id: int, db: Session = Depends(get_db)) -> Response:
"""Delete a label. Its literature stays; only the labelling goes."""
crud.delete(db, _get_or_404(db, tag_id))
return Response(status_code=status.HTTP_204_NO_CONTENT)
+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(
+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)
+12
View File
@@ -19,6 +19,10 @@ after its table (``Template`` -> ``template``):
paper the 论文 module
paper_sentence one sentence of one paper
paper_sentence_reference a citation of one sentence
reference the 参考文献 module
reference_author its contributors, in print order
reference_tag the writer's labels (文献标签)
reference_tag_link which literature carries which label
``template_title_placement`` and ``template_title`` are one word apart and mean
opposite things: the first is a *placement* (this template puts this field
@@ -42,11 +46,17 @@ from app.models.reference import (
Reference,
)
from app.models.reference_author import ReferenceAuthor
from app.models.reference_tag import (
DEFAULT_TAG_COLOR,
ReferenceTag,
reference_tag_link,
)
from app.models.template import Template
from app.models.template_title_placement import TemplateTitlePlacement
from app.models.template_title import TemplateTitle
__all__ = [
"DEFAULT_TAG_COLOR",
"PAPER_STATUSES",
"STATUS_DONE",
"STATUS_DRAFT",
@@ -59,8 +69,10 @@ __all__ = [
"REFERENCE_TYPES",
"Reference",
"ReferenceAuthor",
"ReferenceTag",
"Template",
"TemplateTitlePlacement",
"TemplateTitle",
"TimestampMixin",
"reference_tag_link",
]
+20
View File
@@ -32,6 +32,14 @@ holds. Formats disagree about names anyway — 「张三」, ``Zhang San``,
``Zhang, S.`` are the same person in three styles — so the printed form and the
two halves are stored separately and a style picks what it needs.
Labels are not columns either
-----------------------------
``keywords`` here are the 关键词 printed on the document — part of the citation
record. The writer's *own* filing of a row (「综述」, 「必读」) is a different
fact with a different lifetime, and it lives in
:mod:`app.models.reference_tag`, reachable as :attr:`Reference.tags`. A tag never
prints in a reference list, so it must not be able to reach one by accident.
What is deliberately missing
----------------------------
The 103 CSL fields include roles this project will never print (narrator,
@@ -51,6 +59,7 @@ from app.models.mixins import TimestampMixin
if TYPE_CHECKING: # pragma: no cover - typing only
from app.models.reference_author import ReferenceAuthor
from app.models.reference_tag import ReferenceTag
#: Document types this library holds, with the marker each format uses for it.
#:
@@ -238,5 +247,16 @@ class Reference(TimestampMixin, Base):
lazy="selectin",
)
#: The writer's own labels (:mod:`app.models.reference_tag`). Not a column of
#: the citation: a document may carry several, the same label is on many
#: documents, and none of them prints. Loaded eagerly for the same reason the
#: contributors are — every table row shows them.
tags: Mapped[list["ReferenceTag"]] = relationship(
secondary="reference_tag_link",
back_populates="references",
order_by="ReferenceTag.id",
lazy="selectin",
)
def __repr__(self) -> str: # pragma: no cover - debugging aid
return f"<Reference id={self.id} type={self.type} title={self.title!r}>"
+127
View File
@@ -0,0 +1,127 @@
"""Tags on the literature (文献标签).
A tag is a label the *writer* puts on a document — 「综述」, 「方法」,
「必读」, 「待精读」 — so a library of a few hundred entries can be narrowed to
the handful that matter for the paragraph being written. It is a filing decision,
not a fact about the document, which is why it is not the same thing as
:attr:`~app.models.reference.Reference.keywords`: those are the 关键词 printed
on the article itself and belong to the citation record, while a tag belongs to
the writer and never prints. One column could not hold both, so they do not
share one.
Two tables, following the naming rule of this package (a module's name plus what
the table holds):
reference_tag one label: its name, and the colour a table paints it in
reference_tag_link which literature carries which label
Why the link is a bare link
---------------------------
A tag on a reference carries nothing of its own: no position, no mark, no text.
It is only "this label applies to this document". That is exactly the case where
``template_title_placement`` had to be a *placement* — it carries ``sort``, the
only home of display order — and here there is no such column, so the pair is
the primary key and the table is named ``_link`` for what it honestly is. A
reference tagged twice with the same tag is therefore not a duplicate row: it is
the same row, because the pair is the identity.
One label, one row
------------------
``name`` is unique. Two tags spelled 「方法」 are one tag, and the API refuses
the second with a message naming it rather than letting a library accumulate
labels that differ only by a trailing space. Nothing else about a tag is
canonical: the colour is decoration, and the note is for the writer.
Deleting a tag deletes labels, not literature
---------------------------------------------
Both foreign keys cascade, so removing a tag removes its links and leaves the
documents alone. That is the opposite of what happens to a reference a sentence
cites — a citation is a claim the paper makes, while a label is only a way of
finding the row again — and the API allows it for the same reason it refuses the
other.
"""
from typing import TYPE_CHECKING
from sqlalchemy import (
Column,
ForeignKey,
Index,
Integer,
String,
Table,
text,
)
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.db.base import Base
from app.models.mixins import TimestampMixin
if TYPE_CHECKING: # pragma: no cover - typing only
from app.models.reference import Reference
#: Which literature carries which label.
#:
#: A Core ``Table`` rather than a mapped class: the pair *is* the row, so there
#: is no attribute to declare and nothing to add later without changing what the
#: table means. Both sides cascade, so deleting a reference or a tag takes its
#: links with it and never leaves a label pointing at a row that is gone.
reference_tag_link = Table(
"reference_tag_link",
Base.metadata,
Column(
"reference_id",
Integer,
ForeignKey("reference.id", ondelete="CASCADE"),
primary_key=True,
),
Column(
"tag_id",
Integer,
ForeignKey("reference_tag.id", ondelete="CASCADE"),
primary_key=True,
),
# The primary key is already the index a reference's own tags are read
# through (its leading column is ``reference_id``). The reverse question —
# "which literature carries this tag?", which is what the tag table's count
# and the by-tag filter ask — needs its own.
Index("ix_reference_tag_link_tag", "tag_id"),
)
#: The colour a new tag is given when the writer does not pick one.
DEFAULT_TAG_COLOR = "#409EFF"
class ReferenceTag(TimestampMixin, Base):
"""One label in the reference module's tag library."""
__tablename__ = "reference_tag"
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
#: The label as the writer types it. Unique: a second tag with the same
#: spelling would be the same label under another id.
name: Mapped[str] = mapped_column(String(64), nullable=False, unique=True)
#: ``#RRGGBB``, normalised on write exactly as a heading's colour is, so the
#: table can paint it without parsing. Decoration only — nothing reads it.
color: Mapped[str] = mapped_column(
String(7),
nullable=False,
default=DEFAULT_TAG_COLOR,
server_default=text("'#409EFF'"),
)
#: Free text: what the label is for, who else uses it, when to apply it.
note: Mapped[str | None] = mapped_column(String(255), nullable=True)
#: The literature carrying this label, ordered by when each tag was created
#: so the same reference always prints its labels in the same order.
references: Mapped[list["Reference"]] = relationship(
secondary=reference_tag_link,
back_populates="tags",
order_by="Reference.id",
)
def __repr__(self) -> str: # pragma: no cover - debugging aid
return f"<ReferenceTag id={self.id} name={self.name!r} color={self.color}>"
+10
View File
@@ -33,6 +33,12 @@ from app.schemas.reference import (
ReferenceUpdate,
normalize_doi,
)
from app.schemas.reference_tag import (
ReferenceTagCreate,
ReferenceTagRead,
ReferenceTagRef,
ReferenceTagUpdate,
)
from app.schemas.template import (
TemplateCreate,
TemplateListItem,
@@ -56,6 +62,10 @@ __all__ = [
"ReferenceCreate",
"ReferenceListItem",
"ReferenceRead",
"ReferenceTagCreate",
"ReferenceTagRead",
"ReferenceTagRef",
"ReferenceTagUpdate",
"ReferenceUpdate",
"normalize_doi",
"CitationInput",
+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
+123
View File
@@ -0,0 +1,123 @@
"""Request/response schemas for the reference tags (文献标签).
The tables and the reasoning behind them are documented on
:mod:`app.models.reference_tag`; this module is the wire format:
* A tag is **made first and applied second**. ``ReferenceCreate.tag_ids`` names
existing tags rather than carrying their names, so a typo cannot silently
invent a label and two clients tagging the same document cannot create two
spellings of it.
* Colours are canonicalised the same way a heading's are — :func:`normalize_hex_color`
accepts ``rgb(r, g, b)``, ``#abc`` and bare ``aabbcc`` — so the column has one
comparable spelling.
* A tag's ``reference_count`` is derived, never sent.
"""
from datetime import datetime
from pydantic import BaseModel, ConfigDict, Field, field_validator
from app.models.reference_tag import DEFAULT_TAG_COLOR
from app.schemas.common import normalize_hex_color
class ReferenceTagBase(BaseModel):
"""The parts of a tag the writer sets."""
name: str = Field(min_length=1, max_length=64)
#: Accepted in any spelling the normaliser understands — ``rgb(64, 158, 255)``
#: is 17 characters — and stored as the canonical 7, so the bound here is on
#: what may *arrive*, not on what the column holds.
color: str = Field(default=DEFAULT_TAG_COLOR, max_length=32)
note: str | None = Field(default=None, max_length=255)
@field_validator("name")
@classmethod
def _require_name(cls, value: str) -> str:
text = value.strip()
if not text:
raise ValueError("标签名称不能为空")
# Inner runs collapse too: " 综述 " and "综述" are one label, and a
# name with a trailing space in it would be a second one.
return " ".join(text.split())
@field_validator("color")
@classmethod
def _canonical_colour(cls, value: str) -> str:
# Raises with its own message when the spelling is not a colour, which
# pydantic turns into a field error naming this field.
return normalize_hex_color(value)
@field_validator("note")
@classmethod
def _blank_to_none(cls, value: str | None) -> str | None:
if value is None:
return None
return value.strip() or None
class ReferenceTagCreate(ReferenceTagBase):
"""Payload for ``POST /reference-tags``."""
class ReferenceTagUpdate(BaseModel):
"""Payload for ``PATCH /reference-tags/{id}`` — every part optional."""
name: str | None = Field(default=None, min_length=1, max_length=64)
color: str | None = Field(default=None, max_length=32)
note: str | None = Field(default=None, max_length=255)
@field_validator("name")
@classmethod
def _require_name(cls, value: str | None) -> str | None:
if value is None:
return None
text = " ".join(value.split())
if not text:
raise ValueError("标签名称不能为空")
return text
@field_validator("color")
@classmethod
def _canonical_colour(cls, value: str | None) -> str | None:
if value is None:
return None
return normalize_hex_color(value)
class ReferenceTagRead(BaseModel):
"""A stored tag, with how much literature carries it."""
model_config = ConfigDict(from_attributes=True)
id: int
name: str
color: str
note: str | None
#: How many references carry this label. Computed on read; it is what the
#: tag table shows and what the delete confirmation warns about.
reference_count: int = 0
created_at: datetime
updated_at: datetime
class ReferenceTagRef(BaseModel):
"""A tag as it appears on a reference — the label, not its usage count.
The library table paints one of these per label, so it carries exactly what
a chip needs and nothing that would have to be loaded per row.
"""
model_config = ConfigDict(from_attributes=True)
id: int
name: str
color: str
__all__ = [
"ReferenceTagCreate",
"ReferenceTagRead",
"ReferenceTagRef",
"ReferenceTagUpdate",
]