Files
govin 6020310b3f 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.
2026-09-22 17:55:15 +08:00

425 lines
15 KiB
Python

"""Data access for the reference library (参考文献).
The list endpoint answers the question a library is opened to answer — "what do
I have, and what is already cited?" — in one query: each row carries its printed
author line and how many sentences cite it, both as correlated subqueries, so a
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
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,
PaperSentence,
PaperSentenceReference,
Reference,
ReferenceAuthor,
ReferenceTag,
TemplateTitle,
TemplateTitlePlacement,
reference_tag_link,
)
from app.schemas.reference import (
ReferenceCitationRead,
ReferenceCreate,
ReferenceListItem,
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
def _conditions(
keyword: str | None,
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 = []
if keyword:
pattern = like_pattern(keyword)
# The author search is an EXISTS rather than a join: joining would
# duplicate a reference with four authors into four rows.
conditions.append(
or_(
Reference.title.like(pattern, escape=LIKE_ESCAPE),
Reference.subtitle.like(pattern, escape=LIKE_ESCAPE),
Reference.container_title.like(pattern, escape=LIKE_ESCAPE),
Reference.doi.like(pattern, escape=LIKE_ESCAPE),
Reference.keywords.like(pattern, escape=LIKE_ESCAPE),
Reference.note.like(pattern, escape=LIKE_ESCAPE),
select(ReferenceAuthor.id)
.where(
ReferenceAuthor.reference_id == Reference.id,
ReferenceAuthor.name.like(pattern, escape=LIKE_ESCAPE),
)
.exists(),
)
)
if type_:
conditions.append(Reference.type == type_)
if year is not None:
conditions.append(Reference.publication_year == year)
if cited_only is True:
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
def _citation_count_column():
"""Correlated count of the sentences that cite this reference."""
return (
select(func.count(PaperSentenceReference.id))
.where(PaperSentenceReference.reference_id == Reference.id)
.correlate(Reference)
.scalar_subquery()
)
def _ordered(stmt: Select) -> Select:
"""Newest publication first, then most recently edited.
A library is browsed by "what did I read about this", so the year leads and
the edit time breaks ties — a reference added today to an older paper still
surfaces if its year is the newest.
"""
return stmt.order_by(
Reference.publication_year.desc(),
Reference.updated_at.desc(),
Reference.id.desc(),
)
def authors_line(authors: Sequence[ReferenceAuthor]) -> str:
"""The printed author line, joined for a table row.
Truncated for display only — the stored list is never cut — because a
fifteen-author row would push every other column off the screen.
"""
names = [author.name for author in authors]
if len(names) > _LIST_AUTHOR_LIMIT:
return ", ".join(names[:_LIST_AUTHOR_LIMIT]) + f" 等 {len(names)} 人"
return ", ".join(names)
def list_references(
db: Session,
*,
keyword: str | None = None,
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, tag_ids)
total = db.scalar(select(func.count(Reference.id)).where(*conditions)) or 0
stmt = _ordered(
select(Reference)
.where(*conditions)
.offset((page - 1) * page_size)
.limit(page_size)
)
rows = list(db.scalars(stmt).all())
# One query for the citation counts of the whole page, rather than one per
# row: the count is a correlated subquery in the list, but here the ids are
# already known and a grouped count is cheaper.
counts = citation_counts(db, [row.id for row in rows])
items = [
ReferenceListItem(
id=row.id,
type=row.type,
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,
pages=row.pages,
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,
)
for row in rows
]
return items, total
def citation_counts(db: Session, reference_ids: Sequence[int]) -> dict[int, int]:
"""How many sentences cite each reference."""
wanted = list({reference_id for reference_id in reference_ids})
if not wanted:
return {}
stmt = (
select(PaperSentenceReference.reference_id, func.count(PaperSentenceReference.id))
.where(PaperSentenceReference.reference_id.in_(wanted))
.group_by(PaperSentenceReference.reference_id)
)
return {reference_id: count for reference_id, count in db.execute(stmt).all()}
def get(db: Session, reference_id: int) -> Reference | None:
"""Return one reference with its authors loaded, or ``None``."""
return db.get(Reference, reference_id)
def get_many(db: Session, reference_ids: Sequence[int]) -> list[Reference]:
"""Return every reference whose id is in ``reference_ids``."""
if not reference_ids:
return []
return list(
db.scalars(select(Reference).where(Reference.id.in_(list(reference_ids)))).all()
)
class UnknownReference(ValueError):
"""A write named literature the library does not have.
A domain error rather than an HTTP one: the same refusal has to reach a
REST client as ``400`` and a model through the MCP tools as a readable tool
error, and the layer that knows what went wrong is this one. Each caller
translates it into its own vocabulary.
"""
def __init__(self, missing: Sequence[int]) -> None:
self.missing = list(missing)
joined = "、".join(str(reference_id) for reference_id in self.missing)
super().__init__(f"参考文献不存在:{joined}")
def assert_exist(db: Session, reference_ids: Sequence[int]) -> None:
"""Refuse a write that cites literature the library does not have.
Called from the paper side before it stores a citation, so the failure is a
message naming the ids rather than a foreign-key violation from the driver.
"""
missing = missing_ids(db, reference_ids)
if missing:
raise UnknownReference(missing)
def missing_ids(db: Session, reference_ids: Sequence[int]) -> list[int]:
"""Which of ``reference_ids`` are not in the library.
Returning the offenders rather than a boolean lets the API name them, which
is the difference between a usable error and "invalid request". A citation
is rejected against this list, so a sentence cannot point at literature that
does not exist.
"""
wanted = set(reference_ids)
if not wanted:
return []
found = set(db.scalars(select(Reference.id).where(Reference.id.in_(wanted))).all())
return sorted(wanted - found)
def read(db: Session, reference: Reference) -> ReferenceRead:
"""Build the detail payload for one reference."""
counts = citation_counts(db, [reference.id])
return ReferenceRead.model_validate(
{
**{
column.name: getattr(reference, column.name)
for column in Reference.__table__.columns
},
"authors": reference.authors,
"tags": reference.tags,
"citation_count": counts.get(reference.id, 0),
}
)
def _build_authors(
items: Sequence,
) -> list[ReferenceAuthor]:
"""Materialise the client's contributor list, numbering it from 1."""
return [
ReferenceAuthor(
name=item.name,
family_name=item.family_name,
given_name=item.given_name,
role=item.role,
sort=item.sort if item.sort is not None else index,
)
for index, item in enumerate(items, start=1)
]
def create(db: Session, data: ReferenceCreate) -> Reference:
"""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,
data: ReferenceUpdate,
) -> Reference:
"""Apply a partial 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.
"""
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)
if data.authors is not None:
# delete-orphan removes the dropped rows on flush; the ORM cascade is
# what cleans them up, whether or not the database would.
reference.authors.clear()
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
def delete(db: Session, reference: Reference) -> None:
"""Delete a reference. Callers must check :func:`citation_counts` first."""
db.delete(reference)
db.commit()
def delete_many(db: Session, reference_ids: Sequence[int]) -> int:
"""Delete several references, returning how many actually existed."""
references = get_many(db, reference_ids)
for reference in references:
db.delete(reference)
db.commit()
return len(references)
def list_citations(
db: Session, reference: Reference
) -> list[ReferenceCitationRead]:
"""Every sentence that cites this reference, with its place in the paper.
The paragraph heading is resolved through the paper's template, so the
answer reads as "in 3.1 Problem Formulation of <paper>" rather than as a
position number only the database understands.
"""
stmt = (
select(PaperSentenceReference, PaperSentence, Paper)
.join(PaperSentence, PaperSentence.id == PaperSentenceReference.sentence_id)
.join(Paper, Paper.id == PaperSentence.paper_id)
.where(PaperSentenceReference.reference_id == reference.id)
.order_by(Paper.id.asc(), PaperSentence.paper_template_filed_sort, PaperSentence.sort)
)
results: list[ReferenceCitationRead] = []
for citation, sentence, paper in db.execute(stmt).all():
results.append(
ReferenceCitationRead(
citation_id=citation.id,
sentence_id=sentence.id,
sentence_content=sentence.content,
quote=citation.quote,
paper_id=paper.id,
paper_title=paper.title,
paper_template_filed_sort=sentence.paper_template_filed_sort,
paragraph_name=_paragraph_name(
db, paper.template_id, sentence.paper_template_filed_sort
),
)
)
return results
def _paragraph_name(db: Session, template_id: int | None, position: int) -> str | None:
"""The heading the template puts at ``position``, or ``None``.
``None`` rather than a placeholder: the document renderer decides how to
print a position the template does not define (it shows 未设定), and this
should not invent a second answer.
"""
if template_id is None:
return None
return db.scalar(
select(TemplateTitle.name)
.join(
TemplateTitlePlacement,
TemplateTitlePlacement.title_id == TemplateTitle.id,
)
.where(
TemplateTitlePlacement.template_id == template_id,
TemplateTitlePlacement.sort == position,
)
.order_by(TemplateTitlePlacement.sort.asc(), TemplateTitlePlacement.id.asc())
.limit(1)
)