backend: add the reference library (参考文献)

One table per document the writer has read, and one for its contributors:

    reference          id, type, title, subtitle, title_translated,
                       container_title, volume, issue, pages, publisher,
                       publisher_place, event_*, publication_year/month/day,
                       accessed_date, doi, isbn, issn, url, patent_*,
                       standard_number, report_number, arxiv_id, abstract,
                       keywords, note, citation_key, language
    reference_author   reference_id, sort, name, family_name, given_name, role

The field set is the intersection of the formats a paper has to survive, taken
from the CSL JSON schema (103 fields, 45 types — what Zotero, Mendeley and
Pandoc exchange) against GB/T 7714-2015, BibTeX and RIS. The mapping is on
`app.models.reference` rather than in a commit message, because the next person
to add a column needs it more than this one does. Three decisions worth naming:

* **Partial dates.** Year, month and day are separate nullable integers, which
  is CSL's `issued`: a book has a year, a newspaper article a day, a patent its
  公告日期, and nothing invents the rest.
* **Contributors are rows, not a column.** A citation prints an ordered list
  with 编 / 译 marks, and styles rewrite names (「张三」 / "Zhang, S." /
  "S. Zhang"), so the printed form and its two halves are stored separately —
  display reads `name`, a reformatting style reads the halves, and an
  institutional author has neither.
* **`volume` / `issue` / `pages` are strings.** Journals print `12(Suppl.)`,
  `S1` and `e12345`, and a citation reproduces what is printed.

The library is global: the same article is cited from several papers, so the
entry cannot belong to one of them. The citation stays on the paper side in
`paper_sentence_reference`, which now carries a real foreign key to `reference`
(`ON DELETE RESTRICT`) — the column had been a loose integer waiting for this
table. A sentence may quote several documents and a document may be quoted by
many sentences, which is why the relation is a table and not a column on
`paper_sentence`.

Refusals are raised once, in the data layer, as `UnknownReference`, and
translated where each caller speaks: `400` with the offending ids for REST (one
exception handler, no route carries the check), a readable tool error for MCP
(one wrapper in the tool registry). Neither entry point can skip it, so the
foreign key never has to be the thing that complains.

API: `/references` CRUD plus batch delete, and `/references/{id}/citations` for
the reverse lookup — "where have I used this article?" — which is what tells a
writer whether an entry is safe to delete.

Verified: 29 new checks in `scripts/smoke_references.py` (partial dates, DOI
normalisation, author order and roles, search by author/type/year/cited, the
citation round trip, 400 on a phantom id, 409 on a cited entry), the paper
suite's 45 and the MCP suite's 47 still pass. The MCP suite now cites a real
entry instead of a phantom id, which is what an agent has to do now.
This commit is contained in:
2026-09-22 17:13:32 +08:00
parent 103b5544ba
commit d7bb777264
18 changed files with 1966 additions and 16 deletions
+2 -1
View File
@@ -2,10 +2,11 @@
from fastapi import APIRouter
from app.api.routes import health, papers, template_titles, templates
from app.api.routes import health, papers, references, template_titles, templates
api_router = APIRouter()
api_router.include_router(health.router)
api_router.include_router(papers.router)
api_router.include_router(references.router)
api_router.include_router(template_titles.router)
api_router.include_router(templates.router)
+1
View File
@@ -246,6 +246,7 @@ def replace_paragraph(
stale copy.
"""
paper = _get_or_404(db, paper_id)
crud.replace_paragraph(db, paper, field_sort, payload)
return crud.build_document(db, paper)
+178
View File
@@ -0,0 +1,178 @@
"""Reference-library endpoints (参考文献).
The library is global and reusable: an article is added once and then cited
from any number of sentences in any number of papers. That is why deleting one
is guarded — the citation rows are the only thing tying a paper's 参考文献 list
to the literature, and dropping a cited reference would quietly empty those
citations rather than tidy up the library.
The reverse lookup lives here too: ``GET /references/{id}/citations`` answers
"which of my sentences use this?", which is the question a library exists to
answer once the writing has started.
"""
from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
from sqlalchemy.orm import Session
from app.crud import reference as crud
from app.db.session import get_db
from app.models import REFERENCE_TYPES, Reference
from app.schemas.common import BatchDeleteRequest, BatchDeleteResult, PageResult
from app.schemas.reference import (
ReferenceCitationRead,
ReferenceCreate,
ReferenceListItem,
ReferenceRead,
ReferenceUpdate,
)
router = APIRouter(prefix="/references", tags=["references"])
def _get_or_404(db: Session, reference_id: int) -> Reference:
reference = crud.get(db, reference_id)
if reference is None:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=f"参考文献 {reference_id} 不存在",
)
return reference
def _assert_not_cited(db: Session, references: list[Reference]) -> None:
"""Refuse the delete while any sentence cites the reference.
All offenders are reported at once rather than one per attempt, so a batch
delete does not turn into trial and error. The message says what to do about
it, because "in use" without a next step is a dead end.
"""
counts = crud.citation_counts(db, [reference.id for reference in references])
if not counts:
return
titles = {reference.id: reference.title for reference in references}
blockers = "、".join(
f"“{titles.get(reference_id, reference_id)}”({count} 处引用)"
for reference_id, count in sorted(counts.items())
)
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail=(
"以下文献正被论文引用,请先在段落里移除对应引用:"
+ blockers
),
)
@router.get("", response_model=PageResult[ReferenceListItem], summary="List references")
def list_references(
db: Session = Depends(get_db),
keyword: str | None = Query(
default=None, description="按题名、刊名、作者、DOI、关键词或备注模糊搜索"
),
type_filter: str | None = Query(
default=None,
alias="type",
description="按文献类型过滤:" + " / ".join(REFERENCE_TYPES),
),
year: int | None = Query(default=None, ge=1, le=2999, description="按出版年过滤"),
cited: bool | None = Query(
default=None, description="true 只看已被引用的,false 只看还没用过的"
),
page: int = Query(default=1, ge=1),
page_size: int = Query(default=20, ge=1, le=200),
) -> PageResult[ReferenceListItem]:
"""Browse the library, newest publication first."""
items, total = crud.list_references(
db,
keyword=keyword,
type_=type_filter,
year=year,
cited_only=cited,
page=page,
page_size=page_size,
)
return PageResult.build(items=items, total=total, page=page, page_size=page_size)
@router.post(
"",
response_model=ReferenceRead,
status_code=status.HTTP_201_CREATED,
summary="Add a reference",
)
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))
@router.post(
"/batch-delete",
response_model=BatchDeleteResult,
summary="Delete several references",
)
def batch_delete_references(
payload: BatchDeleteRequest,
db: Session = Depends(get_db),
) -> BatchDeleteResult:
"""Delete the given references, refusing wholesale if any is cited."""
references = crud.get_many(db, payload.ids)
_assert_not_cited(db, references)
return BatchDeleteResult(deleted=crud.delete_many(db, payload.ids))
@router.get("/{reference_id}", response_model=ReferenceRead, summary="Fetch one reference")
def get_reference(reference_id: int, db: Session = Depends(get_db)) -> ReferenceRead:
"""Return one reference, with its contributors and citation count."""
return crud.read(db, _get_or_404(db, reference_id))
@router.get(
"/{reference_id}/citations",
response_model=list[ReferenceCitationRead],
summary="Which sentences cite this reference",
)
def list_reference_citations(
reference_id: int, db: Session = Depends(get_db)
) -> list[ReferenceCitationRead]:
"""Return every sentence that cites this reference, with its paragraph.
This is the direction the paper side cannot answer: a sentence knows which
articles it quotes, but only the library can say where an article has been
used — which is what tells the writer whether it is safe to delete, and
where to look when a citation has to change.
"""
return crud.list_citations(db, _get_or_404(db, reference_id))
@router.patch(
"/{reference_id}", response_model=ReferenceRead, summary="Update a reference"
)
def update_reference(
reference_id: int,
payload: ReferenceUpdate,
db: Session = Depends(get_db),
) -> 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.
"""
reference = _get_or_404(db, reference_id)
return crud.read(db, crud.update(db, reference, payload))
@router.delete(
"/{reference_id}",
status_code=status.HTTP_204_NO_CONTENT,
summary="Delete a reference",
)
def delete_reference(reference_id: int, db: Session = Depends(get_db)) -> Response:
"""Delete a reference no sentence cites."""
reference = _get_or_404(db, reference_id)
_assert_not_cited(db, [reference])
crud.delete(db, reference)
return Response(status_code=status.HTTP_204_NO_CONTENT)