6020310b3f
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.
204 lines
7.2 KiB
Python
204 lines
7.2 KiB
Python
"""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.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
|
|
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
|
|
),
|
|
)
|
|
|
|
|
|
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),
|
|
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 只看还没用过的"
|
|
),
|
|
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]:
|
|
"""Browse the library, newest publication first."""
|
|
items, total = crud.list_references(
|
|
db,
|
|
keyword=keyword,
|
|
type_=type_filter,
|
|
year=year,
|
|
cited_only=cited,
|
|
tag_ids=tag,
|
|
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 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(
|
|
"/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`` 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)
|
|
try:
|
|
updated = crud.update(db, reference, payload)
|
|
except UnknownTag as error:
|
|
raise _unknown_tag(error) from error
|
|
return crud.read(db, updated)
|
|
|
|
|
|
@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)
|