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