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:
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user