"""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 " 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) )