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.
This commit is contained in:
@@ -0,0 +1,97 @@
|
|||||||
|
"""create reference tags (文献标签)
|
||||||
|
|
||||||
|
Two tables that hold the writer's own labels on the literature:
|
||||||
|
|
||||||
|
``reference_tag`` one label: its name, its colour, a note.
|
||||||
|
``reference_tag_link`` which literature carries which label — two foreign keys
|
||||||
|
and nothing else, so the *pair* is the primary key. A
|
||||||
|
reference tagged twice with the same label is therefore
|
||||||
|
not a duplicate row; it is the same row.
|
||||||
|
|
||||||
|
Why this is not a column on ``reference``
|
||||||
|
-----------------------------------------
|
||||||
|
``reference.keywords`` already exists and is a different fact: those are the
|
||||||
|
关键词 printed on the document, part of the citation record. A tag is the
|
||||||
|
writer's filing (「综述」, 「必读」), it never prints, one document carries
|
||||||
|
several, and the same label is on many documents. That is a second table by the
|
||||||
|
same argument that made a citation a table rather than a column.
|
||||||
|
|
||||||
|
The link table is named ``_link`` rather than ``_placement`` on purpose: unlike
|
||||||
|
``template_title_placement`` it carries no ``sort``, so there is no ordering to
|
||||||
|
own and no payload to grow into. It is a bare link, and the name says so.
|
||||||
|
|
||||||
|
Both foreign keys cascade. Deleting a tag removes its labels and leaves the
|
||||||
|
literature alone — a label is not a claim the paper makes, which is why deleting
|
||||||
|
a *cited reference* is refused at the API while deleting a tag is not.
|
||||||
|
|
||||||
|
Nothing is backfilled: the tables are new and the library starts unlabelled.
|
||||||
|
|
||||||
|
Revision ID: 063f6def01fa
|
||||||
|
Revises: e4b7c1f9a036
|
||||||
|
Create Date: 2026-09-22
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
from collections.abc import Sequence
|
||||||
|
|
||||||
|
import sqlalchemy as sa
|
||||||
|
from alembic import op
|
||||||
|
|
||||||
|
# revision identifiers, used by Alembic.
|
||||||
|
revision: str = "063f6def01fa"
|
||||||
|
down_revision: str | None = "e4b7c1f9a036"
|
||||||
|
branch_labels: str | Sequence[str] | None = None
|
||||||
|
depends_on: str | Sequence[str] | None = None
|
||||||
|
|
||||||
|
_NOW = sa.text("CURRENT_TIMESTAMP")
|
||||||
|
|
||||||
|
|
||||||
|
def upgrade() -> None:
|
||||||
|
op.create_table(
|
||||||
|
"reference_tag",
|
||||||
|
sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
|
||||||
|
sa.Column("name", sa.String(length=64), nullable=False),
|
||||||
|
sa.Column(
|
||||||
|
"color",
|
||||||
|
sa.String(length=7),
|
||||||
|
server_default=sa.text("'#409EFF'"),
|
||||||
|
nullable=False,
|
||||||
|
),
|
||||||
|
sa.Column("note", sa.String(length=255), nullable=True),
|
||||||
|
sa.Column("created_at", sa.DateTime(), server_default=_NOW, nullable=False),
|
||||||
|
sa.Column("updated_at", sa.DateTime(), server_default=_NOW, nullable=False),
|
||||||
|
sa.PrimaryKeyConstraint("id"),
|
||||||
|
# One row per label: two tags spelled the same are the same tag, and
|
||||||
|
# nothing in the UI could explain a second one.
|
||||||
|
sa.UniqueConstraint("name", name="uq_reference_tag_name"),
|
||||||
|
)
|
||||||
|
|
||||||
|
op.create_table(
|
||||||
|
"reference_tag_link",
|
||||||
|
sa.Column("reference_id", sa.Integer(), nullable=False),
|
||||||
|
sa.Column("tag_id", sa.Integer(), nullable=False),
|
||||||
|
sa.ForeignKeyConstraint(
|
||||||
|
["reference_id"], ["reference.id"], ondelete="CASCADE"
|
||||||
|
),
|
||||||
|
sa.ForeignKeyConstraint(
|
||||||
|
["tag_id"], ["reference_tag.id"], ondelete="CASCADE"
|
||||||
|
),
|
||||||
|
# The pair is the identity, so it is the key — which also means the
|
||||||
|
# table cannot hold the same label on the same document twice.
|
||||||
|
sa.PrimaryKeyConstraint("reference_id", "tag_id"),
|
||||||
|
)
|
||||||
|
# The primary key already serves "what is this document tagged with" (its
|
||||||
|
# leading column is ``reference_id``); the reverse — "what carries this
|
||||||
|
# label", which the tag table counts — needs an index of its own.
|
||||||
|
op.create_index(
|
||||||
|
"ix_reference_tag_link_tag",
|
||||||
|
"reference_tag_link",
|
||||||
|
["tag_id"],
|
||||||
|
unique=False,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def downgrade() -> None:
|
||||||
|
op.drop_index("ix_reference_tag_link_tag", table_name="reference_tag_link")
|
||||||
|
op.drop_table("reference_tag_link")
|
||||||
|
op.drop_table("reference_tag")
|
||||||
@@ -2,11 +2,19 @@
|
|||||||
|
|
||||||
from fastapi import APIRouter
|
from fastapi import APIRouter
|
||||||
|
|
||||||
from app.api.routes import health, papers, references, template_titles, templates
|
from app.api.routes import (
|
||||||
|
health,
|
||||||
|
papers,
|
||||||
|
reference_tags,
|
||||||
|
references,
|
||||||
|
template_titles,
|
||||||
|
templates,
|
||||||
|
)
|
||||||
|
|
||||||
api_router = APIRouter()
|
api_router = APIRouter()
|
||||||
api_router.include_router(health.router)
|
api_router.include_router(health.router)
|
||||||
api_router.include_router(papers.router)
|
api_router.include_router(papers.router)
|
||||||
|
api_router.include_router(reference_tags.router)
|
||||||
api_router.include_router(references.router)
|
api_router.include_router(references.router)
|
||||||
api_router.include_router(template_titles.router)
|
api_router.include_router(template_titles.router)
|
||||||
api_router.include_router(templates.router)
|
api_router.include_router(templates.router)
|
||||||
|
|||||||
@@ -0,0 +1,128 @@
|
|||||||
|
"""Reference-tag endpoints (文献标签).
|
||||||
|
|
||||||
|
The label library the reference table and the reference form draw on. It is
|
||||||
|
managed first and applied second: a reference is created *with* tags, and an id
|
||||||
|
that names a label that does not exist is refused rather than silently ignored.
|
||||||
|
|
||||||
|
Deleting a tag is **not** guarded the way deleting a field or a cited reference
|
||||||
|
is. A tag is the writer's own filing — it says "this is one of the papers I
|
||||||
|
should reread", not something the document claims — so removing it removes
|
||||||
|
labels and leaves the literature exactly where it was. The confirmation in the
|
||||||
|
UI says how many rows will lose the label, which is the honest form of that
|
||||||
|
warning.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
|
||||||
|
from sqlalchemy.orm import Session
|
||||||
|
|
||||||
|
from app.crud import reference_tag as crud
|
||||||
|
from app.crud.reference_tag import DuplicateTagName
|
||||||
|
from app.db.session import get_db
|
||||||
|
from app.models import ReferenceTag
|
||||||
|
from app.schemas.common import BatchDeleteRequest, BatchDeleteResult, PageResult
|
||||||
|
from app.schemas.reference_tag import (
|
||||||
|
ReferenceTagCreate,
|
||||||
|
ReferenceTagRead,
|
||||||
|
ReferenceTagUpdate,
|
||||||
|
)
|
||||||
|
|
||||||
|
router = APIRouter(prefix="/reference-tags", tags=["reference-tags"])
|
||||||
|
|
||||||
|
|
||||||
|
def _get_or_404(db: Session, tag_id: int) -> ReferenceTag:
|
||||||
|
tag = crud.get(db, tag_id)
|
||||||
|
if tag is None:
|
||||||
|
raise HTTPException(
|
||||||
|
status_code=status.HTTP_404_NOT_FOUND,
|
||||||
|
detail=f"标签 {tag_id} 不存在",
|
||||||
|
)
|
||||||
|
return tag
|
||||||
|
|
||||||
|
|
||||||
|
def _conflict(error: DuplicateTagName) -> HTTPException:
|
||||||
|
"""Report a taken name as ``409`` naming the label."""
|
||||||
|
return HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(error))
|
||||||
|
|
||||||
|
|
||||||
|
@router.get("", response_model=PageResult[ReferenceTagRead], summary="List tags")
|
||||||
|
def list_tags(
|
||||||
|
db: Session = Depends(get_db),
|
||||||
|
keyword: str | None = Query(default=None, description="按标签名称或备注模糊搜索"),
|
||||||
|
page: int = Query(default=1, ge=1),
|
||||||
|
page_size: int = Query(default=50, ge=1, le=500),
|
||||||
|
) -> PageResult[ReferenceTagRead]:
|
||||||
|
"""Browse the tag library, alphabetical, each with how many rows carry it."""
|
||||||
|
items, total = crud.list_tags(
|
||||||
|
db,
|
||||||
|
keyword=keyword,
|
||||||
|
page=page,
|
||||||
|
page_size=page_size,
|
||||||
|
)
|
||||||
|
return PageResult.build(items=items, total=total, page=page, page_size=page_size)
|
||||||
|
|
||||||
|
|
||||||
|
@router.post(
|
||||||
|
"",
|
||||||
|
response_model=ReferenceTagRead,
|
||||||
|
status_code=status.HTTP_201_CREATED,
|
||||||
|
summary="Create a tag",
|
||||||
|
)
|
||||||
|
def create_tag(
|
||||||
|
payload: ReferenceTagCreate,
|
||||||
|
db: Session = Depends(get_db),
|
||||||
|
) -> ReferenceTagRead:
|
||||||
|
"""Add one label to the library."""
|
||||||
|
try:
|
||||||
|
tag = crud.create(db, payload)
|
||||||
|
except DuplicateTagName as error:
|
||||||
|
raise _conflict(error) from error
|
||||||
|
return crud.read(db, tag)
|
||||||
|
|
||||||
|
|
||||||
|
@router.post(
|
||||||
|
"/batch-delete",
|
||||||
|
response_model=BatchDeleteResult,
|
||||||
|
summary="Delete several tags",
|
||||||
|
)
|
||||||
|
def batch_delete_tags(
|
||||||
|
payload: BatchDeleteRequest,
|
||||||
|
db: Session = Depends(get_db),
|
||||||
|
) -> BatchDeleteResult:
|
||||||
|
"""Delete the given tags, removing their labels from the literature."""
|
||||||
|
return BatchDeleteResult(deleted=crud.delete_many(db, payload.ids))
|
||||||
|
|
||||||
|
|
||||||
|
@router.get("/{tag_id}", response_model=ReferenceTagRead, summary="Fetch one tag")
|
||||||
|
def get_tag(tag_id: int, db: Session = Depends(get_db)) -> ReferenceTagRead:
|
||||||
|
"""Return one label, with how many references carry it."""
|
||||||
|
return crud.read(db, _get_or_404(db, tag_id))
|
||||||
|
|
||||||
|
|
||||||
|
@router.patch("/{tag_id}", response_model=ReferenceTagRead, summary="Update a tag")
|
||||||
|
def update_tag(
|
||||||
|
tag_id: int,
|
||||||
|
payload: ReferenceTagUpdate,
|
||||||
|
db: Session = Depends(get_db),
|
||||||
|
) -> ReferenceTagRead:
|
||||||
|
"""Rename or recolour a label.
|
||||||
|
|
||||||
|
Every reference carrying it follows, because a reference links to the tag
|
||||||
|
rather than storing its name.
|
||||||
|
"""
|
||||||
|
tag = _get_or_404(db, tag_id)
|
||||||
|
try:
|
||||||
|
updated = crud.update(db, tag, payload)
|
||||||
|
except DuplicateTagName as error:
|
||||||
|
raise _conflict(error) from error
|
||||||
|
return crud.read(db, updated)
|
||||||
|
|
||||||
|
|
||||||
|
@router.delete(
|
||||||
|
"/{tag_id}",
|
||||||
|
status_code=status.HTTP_204_NO_CONTENT,
|
||||||
|
summary="Delete a tag",
|
||||||
|
)
|
||||||
|
def delete_tag(tag_id: int, db: Session = Depends(get_db)) -> Response:
|
||||||
|
"""Delete a label. Its literature stays; only the labelling goes."""
|
||||||
|
crud.delete(db, _get_or_404(db, tag_id))
|
||||||
|
return Response(status_code=status.HTTP_204_NO_CONTENT)
|
||||||
@@ -15,6 +15,7 @@ from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
|
|||||||
from sqlalchemy.orm import Session
|
from sqlalchemy.orm import Session
|
||||||
|
|
||||||
from app.crud import reference as crud
|
from app.crud import reference as crud
|
||||||
|
from app.crud.reference_tag import UnknownTag
|
||||||
from app.db.session import get_db
|
from app.db.session import get_db
|
||||||
from app.models import REFERENCE_TYPES, Reference
|
from app.models import REFERENCE_TYPES, Reference
|
||||||
from app.schemas.common import BatchDeleteRequest, BatchDeleteResult, PageResult
|
from app.schemas.common import BatchDeleteRequest, BatchDeleteResult, PageResult
|
||||||
@@ -64,6 +65,16 @@ def _assert_not_cited(db: Session, references: list[Reference]) -> None:
|
|||||||
)
|
)
|
||||||
|
|
||||||
|
|
||||||
|
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")
|
@router.get("", response_model=PageResult[ReferenceListItem], summary="List references")
|
||||||
def list_references(
|
def list_references(
|
||||||
db: Session = Depends(get_db),
|
db: Session = Depends(get_db),
|
||||||
@@ -79,6 +90,10 @@ def list_references(
|
|||||||
cited: bool | None = Query(
|
cited: bool | None = Query(
|
||||||
default=None, description="true 只看已被引用的,false 只看还没用过的"
|
default=None, description="true 只看已被引用的,false 只看还没用过的"
|
||||||
),
|
),
|
||||||
|
tag: list[int] | None = Query(
|
||||||
|
default=None,
|
||||||
|
description="按标签过滤,可重复;给多个标签时取交集(都打了才留下)",
|
||||||
|
),
|
||||||
page: int = Query(default=1, ge=1),
|
page: int = Query(default=1, ge=1),
|
||||||
page_size: int = Query(default=20, ge=1, le=200),
|
page_size: int = Query(default=20, ge=1, le=200),
|
||||||
) -> PageResult[ReferenceListItem]:
|
) -> PageResult[ReferenceListItem]:
|
||||||
@@ -89,6 +104,7 @@ def list_references(
|
|||||||
type_=type_filter,
|
type_=type_filter,
|
||||||
year=year,
|
year=year,
|
||||||
cited_only=cited,
|
cited_only=cited,
|
||||||
|
tag_ids=tag,
|
||||||
page=page,
|
page=page,
|
||||||
page_size=page_size,
|
page_size=page_size,
|
||||||
)
|
)
|
||||||
@@ -105,8 +121,12 @@ def create_reference(
|
|||||||
payload: ReferenceCreate,
|
payload: ReferenceCreate,
|
||||||
db: Session = Depends(get_db),
|
db: Session = Depends(get_db),
|
||||||
) -> ReferenceRead:
|
) -> ReferenceRead:
|
||||||
"""Add one document to the library, with its contributors in order."""
|
"""Add one document to the library, with its contributors and its tags."""
|
||||||
return crud.read(db, crud.create(db, payload))
|
try:
|
||||||
|
created = crud.create(db, payload)
|
||||||
|
except UnknownTag as error:
|
||||||
|
raise _unknown_tag(error) from error
|
||||||
|
return crud.read(db, created)
|
||||||
|
|
||||||
|
|
||||||
@router.post(
|
@router.post(
|
||||||
@@ -158,11 +178,16 @@ def update_reference(
|
|||||||
) -> ReferenceRead:
|
) -> ReferenceRead:
|
||||||
"""Update any part of a reference.
|
"""Update any part of a reference.
|
||||||
|
|
||||||
``authors`` is a full replacement when present — the citation prints them in
|
``authors`` and ``tag_ids`` are full replacements when present — the citation
|
||||||
the order sent, so there is no partial form of that list.
|
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)
|
reference = _get_or_404(db, reference_id)
|
||||||
return crud.read(db, crud.update(db, reference, payload))
|
try:
|
||||||
|
updated = crud.update(db, reference, payload)
|
||||||
|
except UnknownTag as error:
|
||||||
|
raise _unknown_tag(error) from error
|
||||||
|
return crud.read(db, updated)
|
||||||
|
|
||||||
|
|
||||||
@router.delete(
|
@router.delete(
|
||||||
|
|||||||
@@ -5,6 +5,6 @@ models. They own the commit: a route calls one function and gets back either a
|
|||||||
persisted object or ``None``.
|
persisted object or ``None``.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from app.crud import paper, reference, template, template_title
|
from app.crud import paper, reference, reference_tag, template, template_title
|
||||||
|
|
||||||
__all__ = ["paper", "reference", "template", "template_title"]
|
__all__ = ["paper", "reference", "reference_tag", "template", "template_title"]
|
||||||
|
|||||||
@@ -8,6 +8,10 @@ table row never has to load the rows behind it.
|
|||||||
Writes keep the two lists (authors, citations) on their own side: authors belong
|
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
|
to the reference and are replaced wholesale, citations belong to the papers that
|
||||||
made them and are never touched from here.
|
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 collections.abc import Sequence
|
||||||
@@ -15,6 +19,7 @@ from collections.abc import Sequence
|
|||||||
from sqlalchemy import Select, func, or_, select
|
from sqlalchemy import Select, func, or_, select
|
||||||
from sqlalchemy.orm import Session
|
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.crud.filters import LIKE_ESCAPE, like_pattern
|
||||||
from app.models import (
|
from app.models import (
|
||||||
Paper,
|
Paper,
|
||||||
@@ -22,8 +27,10 @@ from app.models import (
|
|||||||
PaperSentenceReference,
|
PaperSentenceReference,
|
||||||
Reference,
|
Reference,
|
||||||
ReferenceAuthor,
|
ReferenceAuthor,
|
||||||
|
ReferenceTag,
|
||||||
TemplateTitle,
|
TemplateTitle,
|
||||||
TemplateTitlePlacement,
|
TemplateTitlePlacement,
|
||||||
|
reference_tag_link,
|
||||||
)
|
)
|
||||||
from app.schemas.reference import (
|
from app.schemas.reference import (
|
||||||
ReferenceCitationRead,
|
ReferenceCitationRead,
|
||||||
@@ -32,6 +39,7 @@ from app.schemas.reference import (
|
|||||||
ReferenceRead,
|
ReferenceRead,
|
||||||
ReferenceUpdate,
|
ReferenceUpdate,
|
||||||
)
|
)
|
||||||
|
from app.schemas.reference_tag import ReferenceTagRef
|
||||||
|
|
||||||
#: How many authors a table row prints before it cuts the line short.
|
#: How many authors a table row prints before it cuts the line short.
|
||||||
_LIST_AUTHOR_LIMIT = 3
|
_LIST_AUTHOR_LIMIT = 3
|
||||||
@@ -42,6 +50,7 @@ def _conditions(
|
|||||||
type_: str | None,
|
type_: str | None,
|
||||||
year: int | None,
|
year: int | None,
|
||||||
cited_only: bool | None,
|
cited_only: bool | None,
|
||||||
|
tag_ids: Sequence[int] | None = None,
|
||||||
) -> list:
|
) -> list:
|
||||||
"""Translate the list filters into SQLAlchemy predicates."""
|
"""Translate the list filters into SQLAlchemy predicates."""
|
||||||
conditions = []
|
conditions = []
|
||||||
@@ -73,6 +82,18 @@ def _conditions(
|
|||||||
conditions.append(_citation_count_column() > 0)
|
conditions.append(_citation_count_column() > 0)
|
||||||
if cited_only is False:
|
if cited_only is False:
|
||||||
conditions.append(_citation_count_column() == 0)
|
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
|
return conditions
|
||||||
|
|
||||||
|
|
||||||
@@ -119,11 +140,12 @@ def list_references(
|
|||||||
type_: str | None = None,
|
type_: str | None = None,
|
||||||
year: int | None = None,
|
year: int | None = None,
|
||||||
cited_only: bool | None = None,
|
cited_only: bool | None = None,
|
||||||
|
tag_ids: Sequence[int] | None = None,
|
||||||
page: int = 1,
|
page: int = 1,
|
||||||
page_size: int = 20,
|
page_size: int = 20,
|
||||||
) -> tuple[list[ReferenceListItem], int]:
|
) -> tuple[list[ReferenceListItem], int]:
|
||||||
"""Return one page of the library, plus the unpaged total."""
|
"""Return one page of the library, plus the unpaged total."""
|
||||||
conditions = _conditions(keyword, type_, year, cited_only)
|
conditions = _conditions(keyword, type_, year, cited_only, tag_ids)
|
||||||
|
|
||||||
total = db.scalar(select(func.count(Reference.id)).where(*conditions)) or 0
|
total = db.scalar(select(func.count(Reference.id)).where(*conditions)) or 0
|
||||||
|
|
||||||
@@ -147,6 +169,7 @@ def list_references(
|
|||||||
title=row.title,
|
title=row.title,
|
||||||
subtitle=row.subtitle,
|
subtitle=row.subtitle,
|
||||||
container_title=row.container_title,
|
container_title=row.container_title,
|
||||||
|
publisher=row.publisher,
|
||||||
publication_year=row.publication_year,
|
publication_year=row.publication_year,
|
||||||
volume=row.volume,
|
volume=row.volume,
|
||||||
issue=row.issue,
|
issue=row.issue,
|
||||||
@@ -154,6 +177,7 @@ def list_references(
|
|||||||
doi=row.doi,
|
doi=row.doi,
|
||||||
authors_line=authors_line(row.authors),
|
authors_line=authors_line(row.authors),
|
||||||
author_count=len(row.authors),
|
author_count=len(row.authors),
|
||||||
|
tags=[ReferenceTagRef.model_validate(tag) for tag in row.tags],
|
||||||
citation_count=counts.get(row.id, 0),
|
citation_count=counts.get(row.id, 0),
|
||||||
created_at=row.created_at,
|
created_at=row.created_at,
|
||||||
updated_at=row.updated_at,
|
updated_at=row.updated_at,
|
||||||
@@ -241,6 +265,7 @@ def read(db: Session, reference: Reference) -> ReferenceRead:
|
|||||||
for column in Reference.__table__.columns
|
for column in Reference.__table__.columns
|
||||||
},
|
},
|
||||||
"authors": reference.authors,
|
"authors": reference.authors,
|
||||||
|
"tags": reference.tags,
|
||||||
"citation_count": counts.get(reference.id, 0),
|
"citation_count": counts.get(reference.id, 0),
|
||||||
}
|
}
|
||||||
)
|
)
|
||||||
@@ -263,16 +288,28 @@ def _build_authors(
|
|||||||
|
|
||||||
|
|
||||||
def create(db: Session, data: ReferenceCreate) -> Reference:
|
def create(db: Session, data: ReferenceCreate) -> Reference:
|
||||||
"""Insert a reference together with its contributors."""
|
"""Insert a reference together with its contributors and its tags."""
|
||||||
values = data.model_dump(exclude={"authors"})
|
tags = _resolve_tags(db, data.tag_ids)
|
||||||
|
values = data.model_dump(exclude={"authors", "tag_ids"})
|
||||||
reference = Reference(**values)
|
reference = Reference(**values)
|
||||||
reference.authors = _build_authors(data.authors)
|
reference.authors = _build_authors(data.authors)
|
||||||
|
reference.tags = tags
|
||||||
db.add(reference)
|
db.add(reference)
|
||||||
db.commit()
|
db.commit()
|
||||||
db.refresh(reference)
|
db.refresh(reference)
|
||||||
return 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(
|
def update(
|
||||||
db: Session,
|
db: Session,
|
||||||
reference: Reference,
|
reference: Reference,
|
||||||
@@ -283,8 +320,14 @@ def update(
|
|||||||
``exclude_unset`` is what makes PATCH semantics work: a key the client did
|
``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
|
not send leaves the column alone, so clearing a field is an explicit
|
||||||
``null`` and omitting it is not.
|
``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.
|
||||||
"""
|
"""
|
||||||
values = data.model_dump(exclude_unset=True, exclude={"authors"})
|
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():
|
for key, value in values.items():
|
||||||
setattr(reference, key, value)
|
setattr(reference, key, value)
|
||||||
|
|
||||||
@@ -295,6 +338,12 @@ def update(
|
|||||||
db.flush()
|
db.flush()
|
||||||
reference.authors.extend(_build_authors(data.authors))
|
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.commit()
|
||||||
db.refresh(reference)
|
db.refresh(reference)
|
||||||
return reference
|
return reference
|
||||||
|
|||||||
@@ -0,0 +1,254 @@
|
|||||||
|
"""Data access for the reference tags (文献标签).
|
||||||
|
|
||||||
|
A tag library is small and is read whole — the picker in the reference form and
|
||||||
|
the rail in the shell both want every label — so the list here is paged only to
|
||||||
|
keep the shape of every other list endpoint, not because a page is expected.
|
||||||
|
|
||||||
|
Each tag carries how many references hold it. The number is what makes the table
|
||||||
|
useful ("is this label actually used?") and what the delete confirmation warns
|
||||||
|
about, and it is a grouped count over the link table rather than a loop.
|
||||||
|
|
||||||
|
Two refusals live here because they are domain rules, not HTTP ones:
|
||||||
|
|
||||||
|
* **A name is unique.** Two tags spelled the same would be one label under two
|
||||||
|
ids, and nothing in the UI could explain the difference.
|
||||||
|
* **A tag must exist before it is applied.** Applying one is a write to the link
|
||||||
|
table, and the layer that knows a label is missing is this one — so it says so
|
||||||
|
by name, in the same way the reference side names a citation to literature the
|
||||||
|
library does not have.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from collections.abc import Sequence
|
||||||
|
|
||||||
|
from sqlalchemy import Select, func, or_, select
|
||||||
|
from sqlalchemy.exc import IntegrityError
|
||||||
|
from sqlalchemy.orm import Session
|
||||||
|
|
||||||
|
from app.crud.filters import LIKE_ESCAPE, like_pattern
|
||||||
|
from app.models import ReferenceTag, reference_tag_link
|
||||||
|
from app.schemas.reference_tag import (
|
||||||
|
ReferenceTagCreate,
|
||||||
|
ReferenceTagRead,
|
||||||
|
ReferenceTagUpdate,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
class DuplicateTagName(ValueError):
|
||||||
|
"""A write asked for a tag name that is already taken."""
|
||||||
|
|
||||||
|
def __init__(self, name: str) -> None:
|
||||||
|
self.name = name
|
||||||
|
super().__init__(f"标签「{name}」已存在")
|
||||||
|
|
||||||
|
|
||||||
|
class UnknownTag(ValueError):
|
||||||
|
"""A write named a tag the library does not have."""
|
||||||
|
|
||||||
|
def __init__(self, missing: Sequence[int]) -> None:
|
||||||
|
self.missing = list(missing)
|
||||||
|
joined = "、".join(str(tag_id) for tag_id in self.missing)
|
||||||
|
super().__init__(f"标签不存在:{joined}")
|
||||||
|
|
||||||
|
|
||||||
|
def _conditions(keyword: str | None) -> list:
|
||||||
|
"""Translate the list filters into SQLAlchemy predicates."""
|
||||||
|
conditions = []
|
||||||
|
if keyword:
|
||||||
|
pattern = like_pattern(keyword)
|
||||||
|
conditions.append(
|
||||||
|
or_(
|
||||||
|
ReferenceTag.name.like(pattern, escape=LIKE_ESCAPE),
|
||||||
|
ReferenceTag.note.like(pattern, escape=LIKE_ESCAPE),
|
||||||
|
)
|
||||||
|
)
|
||||||
|
return conditions
|
||||||
|
|
||||||
|
|
||||||
|
def _ordered(stmt: Select) -> Select:
|
||||||
|
"""Alphabetical, then by insertion order for a stable tie-break.
|
||||||
|
|
||||||
|
A tag library is scanned by name — the writer looks for 「方法」 where they
|
||||||
|
expect it — which is the opposite of the reference list, where the newest
|
||||||
|
publication leads.
|
||||||
|
"""
|
||||||
|
return stmt.order_by(ReferenceTag.name.asc(), ReferenceTag.id.asc())
|
||||||
|
|
||||||
|
|
||||||
|
def reference_counts(db: Session, tag_ids: Sequence[int]) -> dict[int, int]:
|
||||||
|
"""How many references carry each tag.
|
||||||
|
|
||||||
|
``COUNT`` over the link table, grouped — the number of *links*, which is the
|
||||||
|
number of references because the pair is the primary key.
|
||||||
|
"""
|
||||||
|
wanted = list({tag_id for tag_id in tag_ids})
|
||||||
|
if not wanted:
|
||||||
|
return {}
|
||||||
|
stmt = (
|
||||||
|
select(reference_tag_link.c.tag_id, func.count(reference_tag_link.c.reference_id))
|
||||||
|
.where(reference_tag_link.c.tag_id.in_(wanted))
|
||||||
|
.group_by(reference_tag_link.c.tag_id)
|
||||||
|
)
|
||||||
|
return {tag_id: count for tag_id, count in db.execute(stmt).all()}
|
||||||
|
|
||||||
|
|
||||||
|
def read(db: Session, tag: ReferenceTag) -> ReferenceTagRead:
|
||||||
|
"""Build the payload for one tag, count included."""
|
||||||
|
counts = reference_counts(db, [tag.id])
|
||||||
|
return ReferenceTagRead.model_validate(
|
||||||
|
{
|
||||||
|
"id": tag.id,
|
||||||
|
"name": tag.name,
|
||||||
|
"color": tag.color,
|
||||||
|
"note": tag.note,
|
||||||
|
"reference_count": counts.get(tag.id, 0),
|
||||||
|
"created_at": tag.created_at,
|
||||||
|
"updated_at": tag.updated_at,
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def list_tags(
|
||||||
|
db: Session,
|
||||||
|
*,
|
||||||
|
keyword: str | None = None,
|
||||||
|
page: int = 1,
|
||||||
|
page_size: int = 50,
|
||||||
|
) -> tuple[list[ReferenceTagRead], int]:
|
||||||
|
"""Return one page of the tag library, plus the unpaged total."""
|
||||||
|
conditions = _conditions(keyword)
|
||||||
|
|
||||||
|
total = db.scalar(select(func.count(ReferenceTag.id)).where(*conditions)) or 0
|
||||||
|
|
||||||
|
stmt = _ordered(
|
||||||
|
select(ReferenceTag)
|
||||||
|
.where(*conditions)
|
||||||
|
.offset((page - 1) * page_size)
|
||||||
|
.limit(page_size)
|
||||||
|
)
|
||||||
|
rows = list(db.scalars(stmt).all())
|
||||||
|
counts = reference_counts(db, [row.id for row in rows])
|
||||||
|
|
||||||
|
items = [
|
||||||
|
ReferenceTagRead.model_validate(
|
||||||
|
{
|
||||||
|
"id": row.id,
|
||||||
|
"name": row.name,
|
||||||
|
"color": row.color,
|
||||||
|
"note": row.note,
|
||||||
|
"reference_count": counts.get(row.id, 0),
|
||||||
|
"created_at": row.created_at,
|
||||||
|
"updated_at": row.updated_at,
|
||||||
|
}
|
||||||
|
)
|
||||||
|
for row in rows
|
||||||
|
]
|
||||||
|
return items, total
|
||||||
|
|
||||||
|
|
||||||
|
def get(db: Session, tag_id: int) -> ReferenceTag | None:
|
||||||
|
"""Return one tag, or ``None``."""
|
||||||
|
return db.get(ReferenceTag, tag_id)
|
||||||
|
|
||||||
|
|
||||||
|
def get_many(db: Session, tag_ids: Sequence[int]) -> list[ReferenceTag]:
|
||||||
|
"""Return every tag whose id is in ``tag_ids`` (missing ids ignored)."""
|
||||||
|
if not tag_ids:
|
||||||
|
return []
|
||||||
|
stmt = select(ReferenceTag).where(ReferenceTag.id.in_(list(tag_ids)))
|
||||||
|
return list(db.scalars(stmt).all())
|
||||||
|
|
||||||
|
|
||||||
|
def by_name(db: Session, name: str) -> ReferenceTag | None:
|
||||||
|
"""Return the tag with this exact name, or ``None``.
|
||||||
|
|
||||||
|
Used by the create/rename guard, and by nothing else — a lookup by id is
|
||||||
|
what the rest of the application does.
|
||||||
|
"""
|
||||||
|
return db.scalar(select(ReferenceTag).where(ReferenceTag.name == name))
|
||||||
|
|
||||||
|
|
||||||
|
def missing_ids(db: Session, tag_ids: Sequence[int]) -> list[int]:
|
||||||
|
"""Which of ``tag_ids`` are not in the library, sorted."""
|
||||||
|
wanted = set(tag_ids)
|
||||||
|
if not wanted:
|
||||||
|
return []
|
||||||
|
found = set(
|
||||||
|
db.scalars(select(ReferenceTag.id).where(ReferenceTag.id.in_(wanted))).all()
|
||||||
|
)
|
||||||
|
return sorted(wanted - found)
|
||||||
|
|
||||||
|
|
||||||
|
def assert_exist(db: Session, tag_ids: Sequence[int]) -> None:
|
||||||
|
"""Refuse a write that applies tags the library does not have."""
|
||||||
|
missing = missing_ids(db, tag_ids)
|
||||||
|
if missing:
|
||||||
|
raise UnknownTag(missing)
|
||||||
|
|
||||||
|
|
||||||
|
def _assert_name_free(db: Session, name: str, *, except_id: int | None = None) -> None:
|
||||||
|
"""Refuse a name another tag already holds.
|
||||||
|
|
||||||
|
Checked before the insert so the failure is a message naming the label
|
||||||
|
rather than a raw unique-constraint error from the driver. The constraint
|
||||||
|
stays as the authority; this is the explanation.
|
||||||
|
"""
|
||||||
|
existing = by_name(db, name)
|
||||||
|
if existing is not None and existing.id != except_id:
|
||||||
|
raise DuplicateTagName(name)
|
||||||
|
|
||||||
|
|
||||||
|
def create(db: Session, data: ReferenceTagCreate) -> ReferenceTag:
|
||||||
|
"""Insert a tag."""
|
||||||
|
_assert_name_free(db, data.name)
|
||||||
|
tag = ReferenceTag(**data.model_dump())
|
||||||
|
db.add(tag)
|
||||||
|
try:
|
||||||
|
db.commit()
|
||||||
|
except IntegrityError as error: # pragma: no cover - lost race only
|
||||||
|
db.rollback()
|
||||||
|
raise DuplicateTagName(data.name) from error
|
||||||
|
db.refresh(tag)
|
||||||
|
return tag
|
||||||
|
|
||||||
|
|
||||||
|
def update(db: Session, tag: ReferenceTag, data: ReferenceTagUpdate) -> ReferenceTag:
|
||||||
|
"""Apply a partial update.
|
||||||
|
|
||||||
|
Renaming is visible everywhere the label is used, because a reference links
|
||||||
|
to the tag rather than storing its name — the same reason renaming a heading
|
||||||
|
updates every template that places it.
|
||||||
|
"""
|
||||||
|
values = data.model_dump(exclude_unset=True)
|
||||||
|
name = values.get("name")
|
||||||
|
if name is not None and name != tag.name:
|
||||||
|
_assert_name_free(db, name, except_id=tag.id)
|
||||||
|
|
||||||
|
for key, value in values.items():
|
||||||
|
setattr(tag, key, value)
|
||||||
|
try:
|
||||||
|
db.commit()
|
||||||
|
except IntegrityError as error: # pragma: no cover - lost race only
|
||||||
|
db.rollback()
|
||||||
|
raise DuplicateTagName(name or tag.name) from error
|
||||||
|
db.refresh(tag)
|
||||||
|
return tag
|
||||||
|
|
||||||
|
|
||||||
|
def delete(db: Session, tag: ReferenceTag) -> None:
|
||||||
|
"""Delete a tag.
|
||||||
|
|
||||||
|
Its links go with it — both sides cascade — so the literature keeps its
|
||||||
|
place in the library and only loses the label. Callers do not need to check
|
||||||
|
usage first: unlike a citation, a label is not a claim the paper makes.
|
||||||
|
"""
|
||||||
|
db.delete(tag)
|
||||||
|
db.commit()
|
||||||
|
|
||||||
|
|
||||||
|
def delete_many(db: Session, tag_ids: Sequence[int]) -> int:
|
||||||
|
"""Delete several tags, returning how many actually existed."""
|
||||||
|
tags = get_many(db, tag_ids)
|
||||||
|
for tag in tags:
|
||||||
|
db.delete(tag)
|
||||||
|
db.commit()
|
||||||
|
return len(tags)
|
||||||
@@ -19,6 +19,10 @@ after its table (``Template`` -> ``template``):
|
|||||||
paper the 论文 module
|
paper the 论文 module
|
||||||
paper_sentence one sentence of one paper
|
paper_sentence one sentence of one paper
|
||||||
paper_sentence_reference a citation of one sentence
|
paper_sentence_reference a citation of one sentence
|
||||||
|
reference the 参考文献 module
|
||||||
|
reference_author its contributors, in print order
|
||||||
|
reference_tag the writer's labels (文献标签)
|
||||||
|
reference_tag_link which literature carries which label
|
||||||
|
|
||||||
``template_title_placement`` and ``template_title`` are one word apart and mean
|
``template_title_placement`` and ``template_title`` are one word apart and mean
|
||||||
opposite things: the first is a *placement* (this template puts this field
|
opposite things: the first is a *placement* (this template puts this field
|
||||||
@@ -42,11 +46,17 @@ from app.models.reference import (
|
|||||||
Reference,
|
Reference,
|
||||||
)
|
)
|
||||||
from app.models.reference_author import ReferenceAuthor
|
from app.models.reference_author import ReferenceAuthor
|
||||||
|
from app.models.reference_tag import (
|
||||||
|
DEFAULT_TAG_COLOR,
|
||||||
|
ReferenceTag,
|
||||||
|
reference_tag_link,
|
||||||
|
)
|
||||||
from app.models.template import Template
|
from app.models.template import Template
|
||||||
from app.models.template_title_placement import TemplateTitlePlacement
|
from app.models.template_title_placement import TemplateTitlePlacement
|
||||||
from app.models.template_title import TemplateTitle
|
from app.models.template_title import TemplateTitle
|
||||||
|
|
||||||
__all__ = [
|
__all__ = [
|
||||||
|
"DEFAULT_TAG_COLOR",
|
||||||
"PAPER_STATUSES",
|
"PAPER_STATUSES",
|
||||||
"STATUS_DONE",
|
"STATUS_DONE",
|
||||||
"STATUS_DRAFT",
|
"STATUS_DRAFT",
|
||||||
@@ -59,8 +69,10 @@ __all__ = [
|
|||||||
"REFERENCE_TYPES",
|
"REFERENCE_TYPES",
|
||||||
"Reference",
|
"Reference",
|
||||||
"ReferenceAuthor",
|
"ReferenceAuthor",
|
||||||
|
"ReferenceTag",
|
||||||
"Template",
|
"Template",
|
||||||
"TemplateTitlePlacement",
|
"TemplateTitlePlacement",
|
||||||
"TemplateTitle",
|
"TemplateTitle",
|
||||||
"TimestampMixin",
|
"TimestampMixin",
|
||||||
|
"reference_tag_link",
|
||||||
]
|
]
|
||||||
|
|||||||
@@ -32,6 +32,14 @@ holds. Formats disagree about names anyway — 「张三」, ``Zhang San``,
|
|||||||
``Zhang, S.`` are the same person in three styles — so the printed form and the
|
``Zhang, S.`` are the same person in three styles — so the printed form and the
|
||||||
two halves are stored separately and a style picks what it needs.
|
two halves are stored separately and a style picks what it needs.
|
||||||
|
|
||||||
|
Labels are not columns either
|
||||||
|
-----------------------------
|
||||||
|
``keywords`` here are the 关键词 printed on the document — part of the citation
|
||||||
|
record. The writer's *own* filing of a row (「综述」, 「必读」) is a different
|
||||||
|
fact with a different lifetime, and it lives in
|
||||||
|
:mod:`app.models.reference_tag`, reachable as :attr:`Reference.tags`. A tag never
|
||||||
|
prints in a reference list, so it must not be able to reach one by accident.
|
||||||
|
|
||||||
What is deliberately missing
|
What is deliberately missing
|
||||||
----------------------------
|
----------------------------
|
||||||
The 103 CSL fields include roles this project will never print (narrator,
|
The 103 CSL fields include roles this project will never print (narrator,
|
||||||
@@ -51,6 +59,7 @@ from app.models.mixins import TimestampMixin
|
|||||||
|
|
||||||
if TYPE_CHECKING: # pragma: no cover - typing only
|
if TYPE_CHECKING: # pragma: no cover - typing only
|
||||||
from app.models.reference_author import ReferenceAuthor
|
from app.models.reference_author import ReferenceAuthor
|
||||||
|
from app.models.reference_tag import ReferenceTag
|
||||||
|
|
||||||
#: Document types this library holds, with the marker each format uses for it.
|
#: Document types this library holds, with the marker each format uses for it.
|
||||||
#:
|
#:
|
||||||
@@ -238,5 +247,16 @@ class Reference(TimestampMixin, Base):
|
|||||||
lazy="selectin",
|
lazy="selectin",
|
||||||
)
|
)
|
||||||
|
|
||||||
|
#: The writer's own labels (:mod:`app.models.reference_tag`). Not a column of
|
||||||
|
#: the citation: a document may carry several, the same label is on many
|
||||||
|
#: documents, and none of them prints. Loaded eagerly for the same reason the
|
||||||
|
#: contributors are — every table row shows them.
|
||||||
|
tags: Mapped[list["ReferenceTag"]] = relationship(
|
||||||
|
secondary="reference_tag_link",
|
||||||
|
back_populates="references",
|
||||||
|
order_by="ReferenceTag.id",
|
||||||
|
lazy="selectin",
|
||||||
|
)
|
||||||
|
|
||||||
def __repr__(self) -> str: # pragma: no cover - debugging aid
|
def __repr__(self) -> str: # pragma: no cover - debugging aid
|
||||||
return f"<Reference id={self.id} type={self.type} title={self.title!r}>"
|
return f"<Reference id={self.id} type={self.type} title={self.title!r}>"
|
||||||
|
|||||||
@@ -0,0 +1,127 @@
|
|||||||
|
"""Tags on the literature (文献标签).
|
||||||
|
|
||||||
|
A tag is a label the *writer* puts on a document — 「综述」, 「方法」,
|
||||||
|
「必读」, 「待精读」 — so a library of a few hundred entries can be narrowed to
|
||||||
|
the handful that matter for the paragraph being written. It is a filing decision,
|
||||||
|
not a fact about the document, which is why it is not the same thing as
|
||||||
|
:attr:`~app.models.reference.Reference.keywords`: those are the 关键词 printed
|
||||||
|
on the article itself and belong to the citation record, while a tag belongs to
|
||||||
|
the writer and never prints. One column could not hold both, so they do not
|
||||||
|
share one.
|
||||||
|
|
||||||
|
Two tables, following the naming rule of this package (a module's name plus what
|
||||||
|
the table holds):
|
||||||
|
|
||||||
|
reference_tag one label: its name, and the colour a table paints it in
|
||||||
|
reference_tag_link which literature carries which label
|
||||||
|
|
||||||
|
Why the link is a bare link
|
||||||
|
---------------------------
|
||||||
|
A tag on a reference carries nothing of its own: no position, no mark, no text.
|
||||||
|
It is only "this label applies to this document". That is exactly the case where
|
||||||
|
``template_title_placement`` had to be a *placement* — it carries ``sort``, the
|
||||||
|
only home of display order — and here there is no such column, so the pair is
|
||||||
|
the primary key and the table is named ``_link`` for what it honestly is. A
|
||||||
|
reference tagged twice with the same tag is therefore not a duplicate row: it is
|
||||||
|
the same row, because the pair is the identity.
|
||||||
|
|
||||||
|
One label, one row
|
||||||
|
------------------
|
||||||
|
``name`` is unique. Two tags spelled 「方法」 are one tag, and the API refuses
|
||||||
|
the second with a message naming it rather than letting a library accumulate
|
||||||
|
labels that differ only by a trailing space. Nothing else about a tag is
|
||||||
|
canonical: the colour is decoration, and the note is for the writer.
|
||||||
|
|
||||||
|
Deleting a tag deletes labels, not literature
|
||||||
|
---------------------------------------------
|
||||||
|
Both foreign keys cascade, so removing a tag removes its links and leaves the
|
||||||
|
documents alone. That is the opposite of what happens to a reference a sentence
|
||||||
|
cites — a citation is a claim the paper makes, while a label is only a way of
|
||||||
|
finding the row again — and the API allows it for the same reason it refuses the
|
||||||
|
other.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from typing import TYPE_CHECKING
|
||||||
|
|
||||||
|
from sqlalchemy import (
|
||||||
|
Column,
|
||||||
|
ForeignKey,
|
||||||
|
Index,
|
||||||
|
Integer,
|
||||||
|
String,
|
||||||
|
Table,
|
||||||
|
text,
|
||||||
|
)
|
||||||
|
from sqlalchemy.orm import Mapped, mapped_column, relationship
|
||||||
|
|
||||||
|
from app.db.base import Base
|
||||||
|
from app.models.mixins import TimestampMixin
|
||||||
|
|
||||||
|
if TYPE_CHECKING: # pragma: no cover - typing only
|
||||||
|
from app.models.reference import Reference
|
||||||
|
|
||||||
|
#: Which literature carries which label.
|
||||||
|
#:
|
||||||
|
#: A Core ``Table`` rather than a mapped class: the pair *is* the row, so there
|
||||||
|
#: is no attribute to declare and nothing to add later without changing what the
|
||||||
|
#: table means. Both sides cascade, so deleting a reference or a tag takes its
|
||||||
|
#: links with it and never leaves a label pointing at a row that is gone.
|
||||||
|
reference_tag_link = Table(
|
||||||
|
"reference_tag_link",
|
||||||
|
Base.metadata,
|
||||||
|
Column(
|
||||||
|
"reference_id",
|
||||||
|
Integer,
|
||||||
|
ForeignKey("reference.id", ondelete="CASCADE"),
|
||||||
|
primary_key=True,
|
||||||
|
),
|
||||||
|
Column(
|
||||||
|
"tag_id",
|
||||||
|
Integer,
|
||||||
|
ForeignKey("reference_tag.id", ondelete="CASCADE"),
|
||||||
|
primary_key=True,
|
||||||
|
),
|
||||||
|
# The primary key is already the index a reference's own tags are read
|
||||||
|
# through (its leading column is ``reference_id``). The reverse question —
|
||||||
|
# "which literature carries this tag?", which is what the tag table's count
|
||||||
|
# and the by-tag filter ask — needs its own.
|
||||||
|
Index("ix_reference_tag_link_tag", "tag_id"),
|
||||||
|
)
|
||||||
|
|
||||||
|
#: The colour a new tag is given when the writer does not pick one.
|
||||||
|
DEFAULT_TAG_COLOR = "#409EFF"
|
||||||
|
|
||||||
|
|
||||||
|
class ReferenceTag(TimestampMixin, Base):
|
||||||
|
"""One label in the reference module's tag library."""
|
||||||
|
|
||||||
|
__tablename__ = "reference_tag"
|
||||||
|
|
||||||
|
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
|
||||||
|
|
||||||
|
#: The label as the writer types it. Unique: a second tag with the same
|
||||||
|
#: spelling would be the same label under another id.
|
||||||
|
name: Mapped[str] = mapped_column(String(64), nullable=False, unique=True)
|
||||||
|
|
||||||
|
#: ``#RRGGBB``, normalised on write exactly as a heading's colour is, so the
|
||||||
|
#: table can paint it without parsing. Decoration only — nothing reads it.
|
||||||
|
color: Mapped[str] = mapped_column(
|
||||||
|
String(7),
|
||||||
|
nullable=False,
|
||||||
|
default=DEFAULT_TAG_COLOR,
|
||||||
|
server_default=text("'#409EFF'"),
|
||||||
|
)
|
||||||
|
|
||||||
|
#: Free text: what the label is for, who else uses it, when to apply it.
|
||||||
|
note: Mapped[str | None] = mapped_column(String(255), nullable=True)
|
||||||
|
|
||||||
|
#: The literature carrying this label, ordered by when each tag was created
|
||||||
|
#: so the same reference always prints its labels in the same order.
|
||||||
|
references: Mapped[list["Reference"]] = relationship(
|
||||||
|
secondary=reference_tag_link,
|
||||||
|
back_populates="tags",
|
||||||
|
order_by="Reference.id",
|
||||||
|
)
|
||||||
|
|
||||||
|
def __repr__(self) -> str: # pragma: no cover - debugging aid
|
||||||
|
return f"<ReferenceTag id={self.id} name={self.name!r} color={self.color}>"
|
||||||
@@ -33,6 +33,12 @@ from app.schemas.reference import (
|
|||||||
ReferenceUpdate,
|
ReferenceUpdate,
|
||||||
normalize_doi,
|
normalize_doi,
|
||||||
)
|
)
|
||||||
|
from app.schemas.reference_tag import (
|
||||||
|
ReferenceTagCreate,
|
||||||
|
ReferenceTagRead,
|
||||||
|
ReferenceTagRef,
|
||||||
|
ReferenceTagUpdate,
|
||||||
|
)
|
||||||
from app.schemas.template import (
|
from app.schemas.template import (
|
||||||
TemplateCreate,
|
TemplateCreate,
|
||||||
TemplateListItem,
|
TemplateListItem,
|
||||||
@@ -56,6 +62,10 @@ __all__ = [
|
|||||||
"ReferenceCreate",
|
"ReferenceCreate",
|
||||||
"ReferenceListItem",
|
"ReferenceListItem",
|
||||||
"ReferenceRead",
|
"ReferenceRead",
|
||||||
|
"ReferenceTagCreate",
|
||||||
|
"ReferenceTagRead",
|
||||||
|
"ReferenceTagRef",
|
||||||
|
"ReferenceTagUpdate",
|
||||||
"ReferenceUpdate",
|
"ReferenceUpdate",
|
||||||
"normalize_doi",
|
"normalize_doi",
|
||||||
"CitationInput",
|
"CitationInput",
|
||||||
|
|||||||
@@ -23,6 +23,7 @@ from app.models.reference import (
|
|||||||
REFERENCE_LANGUAGES,
|
REFERENCE_LANGUAGES,
|
||||||
REFERENCE_TYPES,
|
REFERENCE_TYPES,
|
||||||
)
|
)
|
||||||
|
from app.schemas.reference_tag import ReferenceTagRef
|
||||||
|
|
||||||
#: Prefixes people paste along with a DOI. Stripped on write so the column has
|
#: Prefixes people paste along with a DOI. Stripped on write so the column has
|
||||||
#: one spelling, and so a citation builder never has to test for them.
|
#: one spelling, and so a citation builder never has to test for them.
|
||||||
@@ -141,6 +142,10 @@ class ReferenceBase(BaseModel):
|
|||||||
citation_key: str | None = Field(default=None, max_length=64)
|
citation_key: str | None = Field(default=None, max_length=64)
|
||||||
language: str | None = Field(default=None, max_length=16)
|
language: str | None = Field(default=None, max_length=16)
|
||||||
authors: list[ReferenceAuthorInput] = Field(default_factory=list)
|
authors: list[ReferenceAuthorInput] = Field(default_factory=list)
|
||||||
|
#: The tags to apply, by id. Tags are made first and applied second, so this
|
||||||
|
#: names labels that already exist rather than carrying spellings that could
|
||||||
|
#: invent new ones. Unknown ids are refused by name.
|
||||||
|
tag_ids: list[int] = Field(default_factory=list)
|
||||||
|
|
||||||
@field_validator("title")
|
@field_validator("title")
|
||||||
@classmethod
|
@classmethod
|
||||||
@@ -269,6 +274,10 @@ class ReferenceUpdate(BaseModel):
|
|||||||
citation_key: str | None = Field(default=None, max_length=64)
|
citation_key: str | None = Field(default=None, max_length=64)
|
||||||
language: str | None = Field(default=None, max_length=16)
|
language: str | None = Field(default=None, max_length=16)
|
||||||
authors: list[ReferenceAuthorInput] | None = None
|
authors: list[ReferenceAuthorInput] | None = None
|
||||||
|
#: Full replacement when present, like ``authors``: the list is the set of
|
||||||
|
#: labels on the row, so sending it means "these and no others" and ``[]``
|
||||||
|
#: clears every label. Omitting the key leaves the labels alone.
|
||||||
|
tag_ids: list[int] | None = None
|
||||||
|
|
||||||
@field_validator("title")
|
@field_validator("title")
|
||||||
@classmethod
|
@classmethod
|
||||||
@@ -312,6 +321,9 @@ class ReferenceListItem(BaseModel):
|
|||||||
title: str
|
title: str
|
||||||
subtitle: str | None
|
subtitle: str | None
|
||||||
container_title: str | None
|
container_title: str | None
|
||||||
|
#: 出版者. Carried on the row because a book, a thesis and a report have no
|
||||||
|
#: container to show and the publisher *is* their "where".
|
||||||
|
publisher: str | None
|
||||||
publication_year: int | None
|
publication_year: int | None
|
||||||
volume: str | None
|
volume: str | None
|
||||||
issue: str | None
|
issue: str | None
|
||||||
@@ -321,6 +333,9 @@ class ReferenceListItem(BaseModel):
|
|||||||
#: rows behind it.
|
#: rows behind it.
|
||||||
authors_line: str
|
authors_line: str
|
||||||
author_count: int
|
author_count: int
|
||||||
|
#: The labels the writer put on it, ready to paint. Loading them here rather
|
||||||
|
#: than per row is what keeps a page of the library one query for the tags.
|
||||||
|
tags: list[ReferenceTagRef] = Field(default_factory=list)
|
||||||
#: How many sentences cite it. Drives the refusal message on delete, and
|
#: How many sentences cite it. Drives the refusal message on delete, and
|
||||||
#: tells the writer at a glance what is already used.
|
#: tells the writer at a glance what is already used.
|
||||||
citation_count: int
|
citation_count: int
|
||||||
@@ -370,6 +385,7 @@ class ReferenceRead(BaseModel):
|
|||||||
citation_key: str | None
|
citation_key: str | None
|
||||||
language: str | None
|
language: str | None
|
||||||
authors: list[ReferenceAuthorRead]
|
authors: list[ReferenceAuthorRead]
|
||||||
|
tags: list[ReferenceTagRef] = Field(default_factory=list)
|
||||||
citation_count: int
|
citation_count: int
|
||||||
created_at: datetime
|
created_at: datetime
|
||||||
updated_at: datetime
|
updated_at: datetime
|
||||||
|
|||||||
@@ -0,0 +1,123 @@
|
|||||||
|
"""Request/response schemas for the reference tags (文献标签).
|
||||||
|
|
||||||
|
The tables and the reasoning behind them are documented on
|
||||||
|
:mod:`app.models.reference_tag`; this module is the wire format:
|
||||||
|
|
||||||
|
* A tag is **made first and applied second**. ``ReferenceCreate.tag_ids`` names
|
||||||
|
existing tags rather than carrying their names, so a typo cannot silently
|
||||||
|
invent a label and two clients tagging the same document cannot create two
|
||||||
|
spellings of it.
|
||||||
|
* Colours are canonicalised the same way a heading's are — :func:`normalize_hex_color`
|
||||||
|
accepts ``rgb(r, g, b)``, ``#abc`` and bare ``aabbcc`` — so the column has one
|
||||||
|
comparable spelling.
|
||||||
|
* A tag's ``reference_count`` is derived, never sent.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from datetime import datetime
|
||||||
|
|
||||||
|
from pydantic import BaseModel, ConfigDict, Field, field_validator
|
||||||
|
|
||||||
|
from app.models.reference_tag import DEFAULT_TAG_COLOR
|
||||||
|
from app.schemas.common import normalize_hex_color
|
||||||
|
|
||||||
|
|
||||||
|
class ReferenceTagBase(BaseModel):
|
||||||
|
"""The parts of a tag the writer sets."""
|
||||||
|
|
||||||
|
name: str = Field(min_length=1, max_length=64)
|
||||||
|
#: Accepted in any spelling the normaliser understands — ``rgb(64, 158, 255)``
|
||||||
|
#: is 17 characters — and stored as the canonical 7, so the bound here is on
|
||||||
|
#: what may *arrive*, not on what the column holds.
|
||||||
|
color: str = Field(default=DEFAULT_TAG_COLOR, max_length=32)
|
||||||
|
note: str | None = Field(default=None, max_length=255)
|
||||||
|
|
||||||
|
@field_validator("name")
|
||||||
|
@classmethod
|
||||||
|
def _require_name(cls, value: str) -> str:
|
||||||
|
text = value.strip()
|
||||||
|
if not text:
|
||||||
|
raise ValueError("标签名称不能为空")
|
||||||
|
# Inner runs collapse too: " 综述 " and "综述" are one label, and a
|
||||||
|
# name with a trailing space in it would be a second one.
|
||||||
|
return " ".join(text.split())
|
||||||
|
|
||||||
|
@field_validator("color")
|
||||||
|
@classmethod
|
||||||
|
def _canonical_colour(cls, value: str) -> str:
|
||||||
|
# Raises with its own message when the spelling is not a colour, which
|
||||||
|
# pydantic turns into a field error naming this field.
|
||||||
|
return normalize_hex_color(value)
|
||||||
|
|
||||||
|
@field_validator("note")
|
||||||
|
@classmethod
|
||||||
|
def _blank_to_none(cls, value: str | None) -> str | None:
|
||||||
|
if value is None:
|
||||||
|
return None
|
||||||
|
return value.strip() or None
|
||||||
|
|
||||||
|
|
||||||
|
class ReferenceTagCreate(ReferenceTagBase):
|
||||||
|
"""Payload for ``POST /reference-tags``."""
|
||||||
|
|
||||||
|
|
||||||
|
class ReferenceTagUpdate(BaseModel):
|
||||||
|
"""Payload for ``PATCH /reference-tags/{id}`` — every part optional."""
|
||||||
|
|
||||||
|
name: str | None = Field(default=None, min_length=1, max_length=64)
|
||||||
|
color: str | None = Field(default=None, max_length=32)
|
||||||
|
note: str | None = Field(default=None, max_length=255)
|
||||||
|
|
||||||
|
@field_validator("name")
|
||||||
|
@classmethod
|
||||||
|
def _require_name(cls, value: str | None) -> str | None:
|
||||||
|
if value is None:
|
||||||
|
return None
|
||||||
|
text = " ".join(value.split())
|
||||||
|
if not text:
|
||||||
|
raise ValueError("标签名称不能为空")
|
||||||
|
return text
|
||||||
|
|
||||||
|
@field_validator("color")
|
||||||
|
@classmethod
|
||||||
|
def _canonical_colour(cls, value: str | None) -> str | None:
|
||||||
|
if value is None:
|
||||||
|
return None
|
||||||
|
return normalize_hex_color(value)
|
||||||
|
|
||||||
|
|
||||||
|
class ReferenceTagRead(BaseModel):
|
||||||
|
"""A stored tag, with how much literature carries it."""
|
||||||
|
|
||||||
|
model_config = ConfigDict(from_attributes=True)
|
||||||
|
|
||||||
|
id: int
|
||||||
|
name: str
|
||||||
|
color: str
|
||||||
|
note: str | None
|
||||||
|
#: How many references carry this label. Computed on read; it is what the
|
||||||
|
#: tag table shows and what the delete confirmation warns about.
|
||||||
|
reference_count: int = 0
|
||||||
|
created_at: datetime
|
||||||
|
updated_at: datetime
|
||||||
|
|
||||||
|
|
||||||
|
class ReferenceTagRef(BaseModel):
|
||||||
|
"""A tag as it appears on a reference — the label, not its usage count.
|
||||||
|
|
||||||
|
The library table paints one of these per label, so it carries exactly what
|
||||||
|
a chip needs and nothing that would have to be loaded per row.
|
||||||
|
"""
|
||||||
|
|
||||||
|
model_config = ConfigDict(from_attributes=True)
|
||||||
|
|
||||||
|
id: int
|
||||||
|
name: str
|
||||||
|
color: str
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
"ReferenceTagCreate",
|
||||||
|
"ReferenceTagRead",
|
||||||
|
"ReferenceTagRef",
|
||||||
|
"ReferenceTagUpdate",
|
||||||
|
]
|
||||||
@@ -4,11 +4,17 @@ Run it while the backend is up::
|
|||||||
|
|
||||||
.venv/bin/python scripts/smoke_references.py
|
.venv/bin/python scripts/smoke_references.py
|
||||||
|
|
||||||
It walks the whole loop the library exists for — add literature, find it again
|
It walks the whole loop the library exists for — make the labels, add
|
||||||
by author and by type, link a sentence to it, look the citation up from the
|
literature and tag it, find it again by author, by type and by tag, link a
|
||||||
reference side, be refused when deleting something in use, then clean up — and
|
sentence to it, look the citation up from the reference side, be refused when
|
||||||
exits non-zero on the first failed expectation. Everything it creates is
|
deleting something in use, then clean up — and exits non-zero on the first
|
||||||
deleted, including the throwaway paper it cites from.
|
failed expectation. Everything it creates is deleted, including the throwaway
|
||||||
|
paper it cites from.
|
||||||
|
|
||||||
|
The order of the first two steps is the point of the tag library rather than an
|
||||||
|
accident of the script: **tags are made first and applied second**. A reference
|
||||||
|
is created *with* tag ids, never with tag names, so a typo cannot invent a label
|
||||||
|
— which is what step 4 checks.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
@@ -60,9 +66,44 @@ def check(label: str, condition: bool, detail: str = "") -> None:
|
|||||||
def main() -> int:
|
def main() -> int:
|
||||||
created_references: list[int] = []
|
created_references: list[int] = []
|
||||||
created_papers: list[int] = []
|
created_papers: list[int] = []
|
||||||
|
created_tags: list[int] = []
|
||||||
|
|
||||||
try:
|
try:
|
||||||
print("1. add an article with four authors")
|
print("1. the labels come first: create two tags")
|
||||||
|
survey = call(
|
||||||
|
"POST",
|
||||||
|
"/reference-tags",
|
||||||
|
{"name": " 综述 ", "color": "rgb(64, 158, 255)", "note": "综述性文献"},
|
||||||
|
expect=201,
|
||||||
|
)
|
||||||
|
created_tags.append(survey["id"])
|
||||||
|
check("a name is trimmed to one spelling", survey["name"] == "综述", survey["name"])
|
||||||
|
check(
|
||||||
|
"a colour is canonicalised",
|
||||||
|
survey["color"] == "#409EFF",
|
||||||
|
survey["color"],
|
||||||
|
)
|
||||||
|
check("nothing carries it yet", survey["reference_count"] == 0)
|
||||||
|
|
||||||
|
must_read = call(
|
||||||
|
"POST",
|
||||||
|
"/reference-tags",
|
||||||
|
{"name": "必读", "color": "#f56c6c"},
|
||||||
|
expect=201,
|
||||||
|
)
|
||||||
|
created_tags.append(must_read["id"])
|
||||||
|
check("the second tag is stored", must_read["name"] == "必读")
|
||||||
|
|
||||||
|
print("2. a tag name is unique, and only a real colour is accepted")
|
||||||
|
duplicate = call(
|
||||||
|
"POST", "/reference-tags", {"name": "综述"}, expect=409
|
||||||
|
)
|
||||||
|
check("the refusal names the label", "综述" in duplicate["detail"], duplicate["detail"])
|
||||||
|
call("POST", "/reference-tags", {"name": "怪颜色", "color": "blue"}, expect=422)
|
||||||
|
call("POST", "/reference-tags", {"name": " "}, expect=422)
|
||||||
|
check("a blank name and a non-colour are refused", True)
|
||||||
|
|
||||||
|
print("3. add an article with four authors and both tags")
|
||||||
article = call(
|
article = call(
|
||||||
"POST",
|
"POST",
|
||||||
"/references",
|
"/references",
|
||||||
@@ -81,6 +122,7 @@ def main() -> int:
|
|||||||
"doi": "https://doi.org/10.1016/j.techfore.2024.123456",
|
"doi": "https://doi.org/10.1016/j.techfore.2024.123456",
|
||||||
"language": "zh",
|
"language": "zh",
|
||||||
"keywords": "技术演化, 惯性, 冲量",
|
"keywords": "技术演化, 惯性, 冲量",
|
||||||
|
"tag_ids": [survey["id"], must_read["id"]],
|
||||||
"authors": [
|
"authors": [
|
||||||
{"name": "张三", "family_name": "张", "given_name": "三"},
|
{"name": "张三", "family_name": "张", "given_name": "三"},
|
||||||
{"name": "李四"},
|
{"name": "李四"},
|
||||||
@@ -107,8 +149,24 @@ def main() -> int:
|
|||||||
check("partial date kept as sent", article["publication_year"] == 2024 and article["publication_month"] == 5)
|
check("partial date kept as sent", article["publication_year"] == 2024 and article["publication_month"] == 5)
|
||||||
check("no day invented", article["publication_day"] is None)
|
check("no day invented", article["publication_day"] is None)
|
||||||
check("not cited yet", article["citation_count"] == 0)
|
check("not cited yet", article["citation_count"] == 0)
|
||||||
|
check(
|
||||||
|
"both tags are on the row",
|
||||||
|
sorted(tag["name"] for tag in article["tags"]) == ["必读", "综述"],
|
||||||
|
str(article["tags"]),
|
||||||
|
)
|
||||||
|
|
||||||
print("2. add a patent, which needs a country and a number")
|
print("4. a tag that does not exist is refused by name, not invented")
|
||||||
|
missing_tag = call(
|
||||||
|
"POST",
|
||||||
|
"/references",
|
||||||
|
{"title": "引用了不存在的标签", "type": "book", "tag_ids": [999999]},
|
||||||
|
expect=400,
|
||||||
|
)
|
||||||
|
check("the refusal names the id", "999999" in missing_tag["detail"], missing_tag["detail"])
|
||||||
|
orphan = call("GET", "/references?keyword=引用了不存在的标签")
|
||||||
|
check("nothing was stored half-labelled", orphan["total"] == 0, str(orphan["total"]))
|
||||||
|
|
||||||
|
print("5. add a patent, which needs a country and a number")
|
||||||
patent = call(
|
patent = call(
|
||||||
"POST",
|
"POST",
|
||||||
"/references",
|
"/references",
|
||||||
@@ -118,14 +176,20 @@ def main() -> int:
|
|||||||
"patent_country": "中国",
|
"patent_country": "中国",
|
||||||
"patent_number": "CN114000000A",
|
"patent_number": "CN114000000A",
|
||||||
"publication_year": 2023,
|
"publication_year": 2023,
|
||||||
|
"tag_ids": [must_read["id"]],
|
||||||
"authors": [{"name": "张三"}],
|
"authors": [{"name": "张三"}],
|
||||||
},
|
},
|
||||||
expect=201,
|
expect=201,
|
||||||
)
|
)
|
||||||
created_references.append(patent["id"])
|
created_references.append(patent["id"])
|
||||||
check("patent stored", patent["type"] == "patent" and patent["patent_number"] == "CN114000000A")
|
check("patent stored", patent["type"] == "patent" and patent["patent_number"] == "CN114000000A")
|
||||||
|
check(
|
||||||
|
"tagging works on create for more than one entry",
|
||||||
|
[tag["name"] for tag in patent["tags"]] == ["必读"],
|
||||||
|
str(patent["tags"]),
|
||||||
|
)
|
||||||
|
|
||||||
print("3. a webpage without a URL is refused")
|
print("6. a webpage without a URL is refused")
|
||||||
call(
|
call(
|
||||||
"POST",
|
"POST",
|
||||||
"/references",
|
"/references",
|
||||||
@@ -134,20 +198,21 @@ def main() -> int:
|
|||||||
)
|
)
|
||||||
check("web page without URL refused", True)
|
check("web page without URL refused", True)
|
||||||
|
|
||||||
print("4. a bad type, a phantom citation target and a missing title are refused")
|
print("7. a bad type and a missing title are refused")
|
||||||
call("POST", "/references", {"type": "blog-post", "title": "x"}, expect=422)
|
call("POST", "/references", {"type": "blog-post", "title": "x"}, expect=422)
|
||||||
call("POST", "/references", {"title": " "}, expect=422)
|
call("POST", "/references", {"title": " "}, expect=422)
|
||||||
call(
|
call(
|
||||||
"POST",
|
"POST",
|
||||||
"/references",
|
"/references",
|
||||||
{"title": "引用了不存在的文献", "authors": [{"name": "甲"}], "type": "book"},
|
{"title": "没有标签的书", "authors": [{"name": "甲"}], "type": "book"},
|
||||||
expect=201,
|
expect=201,
|
||||||
)
|
)
|
||||||
probe = call("GET", "/references?keyword=引用了不存在")
|
probe = call("GET", "/references?keyword=没有标签的书")
|
||||||
created_references.append(probe["items"][0]["id"])
|
created_references.append(probe["items"][0]["id"])
|
||||||
check("a book needs nothing else", probe["total"] == 1)
|
check("a book needs nothing else", probe["total"] == 1)
|
||||||
|
check("and may carry no tags at all", probe["items"][0]["tags"] == [])
|
||||||
|
|
||||||
print("5. find it again: by author, by type, by year")
|
print("8. find it again: by author, by type, by year, by tag")
|
||||||
by_author = call("GET", "/references?keyword=Wang")
|
by_author = call("GET", "/references?keyword=Wang")
|
||||||
check("search matches an author name", by_author["total"] == 1, str(by_author["total"]))
|
check("search matches an author name", by_author["total"] == 1, str(by_author["total"]))
|
||||||
check(
|
check(
|
||||||
@@ -162,12 +227,52 @@ def main() -> int:
|
|||||||
uncited = call("GET", "/references?cited=false")
|
uncited = call("GET", "/references?cited=false")
|
||||||
check("filter by not-yet-cited", uncited["total"] == len(created_references))
|
check("filter by not-yet-cited", uncited["total"] == len(created_references))
|
||||||
|
|
||||||
print("6. edit it: replace the contributor list, change a field")
|
by_tag = call("GET", f"/references?tag={must_read['id']}")
|
||||||
|
check("filter by tag", by_tag["total"] == 2, str(by_tag["total"]))
|
||||||
|
both = call(
|
||||||
|
"GET",
|
||||||
|
f"/references?tag={survey['id']}&tag={must_read['id']}",
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"two tags narrow to the rows carrying both",
|
||||||
|
both["total"] == 1 and both["items"][0]["id"] == article["id"],
|
||||||
|
str(both["total"]),
|
||||||
|
)
|
||||||
|
|
||||||
|
print("9. the tag table counts what carries each label")
|
||||||
|
tags = call("GET", "/reference-tags")
|
||||||
|
counts = {tag["name"]: tag["reference_count"] for tag in tags["items"]}
|
||||||
|
check("two labels in the library", tags["total"] == 2, str(tags["total"]))
|
||||||
|
check("the shared label counts two rows", counts["必读"] == 2, str(counts))
|
||||||
|
check("the other counts one", counts["综述"] == 1, str(counts))
|
||||||
|
found = call("GET", "/reference-tags?keyword=综述")
|
||||||
|
check("tags are searchable by name", found["total"] == 1, str(found["total"]))
|
||||||
|
|
||||||
|
print("10. renaming a label follows it everywhere it is used")
|
||||||
|
renamed = call(
|
||||||
|
"PATCH",
|
||||||
|
f"/reference-tags/{survey['id']}",
|
||||||
|
{"name": "综述文章", "note": "综述与述评"},
|
||||||
|
)
|
||||||
|
check("the label is renamed", renamed["name"] == "综述文章")
|
||||||
|
after = call("GET", f"/references/{article['id']}")
|
||||||
|
check(
|
||||||
|
"the reference prints the new name",
|
||||||
|
sorted(tag["name"] for tag in after["tags"]) == ["必读", "综述文章"],
|
||||||
|
str(after["tags"]),
|
||||||
|
)
|
||||||
|
taken = call(
|
||||||
|
"PATCH", f"/reference-tags/{survey['id']}", {"name": "必读"}, expect=409
|
||||||
|
)
|
||||||
|
check("renaming onto a taken name is refused", "必读" in taken["detail"], taken["detail"])
|
||||||
|
|
||||||
|
print("11. edit it: replace the contributor list, a field and its tags")
|
||||||
updated = call(
|
updated = call(
|
||||||
"PATCH",
|
"PATCH",
|
||||||
f"/references/{article['id']}",
|
f"/references/{article['id']}",
|
||||||
{
|
{
|
||||||
"pages": "122-145",
|
"pages": "122-145",
|
||||||
|
"tag_ids": [must_read["id"]],
|
||||||
"authors": [
|
"authors": [
|
||||||
{"name": "张三", "family_name": "张", "given_name": "三"},
|
{"name": "张三", "family_name": "张", "given_name": "三"},
|
||||||
{"name": "李四"},
|
{"name": "李四"},
|
||||||
@@ -176,9 +281,21 @@ def main() -> int:
|
|||||||
)
|
)
|
||||||
check("pages updated", updated["pages"] == "122-145")
|
check("pages updated", updated["pages"] == "122-145")
|
||||||
check("author list replaced wholesale", len(updated["authors"]) == 2)
|
check("author list replaced wholesale", len(updated["authors"]) == 2)
|
||||||
|
check(
|
||||||
|
"tag list replaced wholesale too",
|
||||||
|
[tag["name"] for tag in updated["tags"]] == ["必读"],
|
||||||
|
str(updated["tags"]),
|
||||||
|
)
|
||||||
check("untouched fields kept", updated["container_title"] == "Technological Forecasting and Social Change")
|
check("untouched fields kept", updated["container_title"] == "Technological Forecasting and Social Change")
|
||||||
|
|
||||||
print("7. cite it from a sentence")
|
cleared = call("PATCH", f"/references/{patent['id']}", {"tag_ids": None})
|
||||||
|
check(
|
||||||
|
"omitting tags leaves them alone",
|
||||||
|
[tag["name"] for tag in cleared["tags"]] == ["必读"],
|
||||||
|
str(cleared["tags"]),
|
||||||
|
)
|
||||||
|
|
||||||
|
print("12. cite it from a sentence")
|
||||||
templates = call("GET", "/templates?page_size=1")["items"]
|
templates = call("GET", "/templates?page_size=1")["items"]
|
||||||
paper = call(
|
paper = call(
|
||||||
"POST",
|
"POST",
|
||||||
@@ -214,7 +331,7 @@ def main() -> int:
|
|||||||
)
|
)
|
||||||
check("a citation to nothing is refused by name", "999999" in missing["detail"], missing["detail"])
|
check("a citation to nothing is refused by name", "999999" in missing["detail"], missing["detail"])
|
||||||
|
|
||||||
print("8. the reverse lookup: which sentences use this article?")
|
print("13. the reverse lookup: which sentences use this article?")
|
||||||
citations = call("GET", f"/references/{article['id']}/citations")
|
citations = call("GET", f"/references/{article['id']}/citations")
|
||||||
check("one citation found", len(citations) == 1, str(len(citations)))
|
check("one citation found", len(citations) == 1, str(len(citations)))
|
||||||
check("it names the sentence", "技术惯性约束" in citations[0]["sentence_content"])
|
check("it names the sentence", "技术惯性约束" in citations[0]["sentence_content"])
|
||||||
@@ -224,21 +341,42 @@ def main() -> int:
|
|||||||
cited = call("GET", "/references?cited=true")
|
cited = call("GET", "/references?cited=true")
|
||||||
check("the cited filter now finds it", cited["total"] == 1, str(cited["total"]))
|
check("the cited filter now finds it", cited["total"] == 1, str(cited["total"]))
|
||||||
|
|
||||||
print("9. a cited reference cannot be deleted; an uncited one can")
|
print("14. a cited reference cannot be deleted; an uncited one can")
|
||||||
conflict = call("DELETE", f"/references/{article['id']}", expect=409)
|
conflict = call("DELETE", f"/references/{article['id']}", expect=409)
|
||||||
check("refusal explains itself", "正被论文引用" in conflict["detail"], conflict["detail"])
|
check("refusal explains itself", "正被论文引用" in conflict["detail"], conflict["detail"])
|
||||||
call("DELETE", f"/references/{patent['id']}", expect=204)
|
call("DELETE", f"/references/{patent['id']}", expect=204)
|
||||||
created_references.remove(patent["id"])
|
created_references.remove(patent["id"])
|
||||||
check("an uncited reference deletes cleanly", True)
|
check("an uncited reference deletes cleanly", True)
|
||||||
|
|
||||||
print("10. clean up")
|
print("15. deleting a tag unlabels the literature instead of deleting it")
|
||||||
|
call("DELETE", f"/reference-tags/{must_read['id']}", expect=204)
|
||||||
|
created_tags.remove(must_read["id"])
|
||||||
|
survivor = call("GET", f"/references/{article['id']}")
|
||||||
|
check("the reference is still there", survivor["title"] == article["title"])
|
||||||
|
check("and has lost that label", survivor["tags"] == [], str(survivor["tags"]))
|
||||||
|
left = call("GET", f"/references?tag={survey['id']}")
|
||||||
|
check(
|
||||||
|
"the other label no longer matches anything",
|
||||||
|
left["total"] == 0,
|
||||||
|
str(left["total"]),
|
||||||
|
)
|
||||||
|
|
||||||
|
print("16. clean up")
|
||||||
call("DELETE", f"/papers/{paper['id']}", expect=204)
|
call("DELETE", f"/papers/{paper['id']}", expect=204)
|
||||||
created_papers.clear()
|
created_papers.clear()
|
||||||
for reference_id in created_references:
|
for reference_id in created_references:
|
||||||
call("DELETE", f"/references/{reference_id}", expect=204)
|
call("DELETE", f"/references/{reference_id}", expect=204)
|
||||||
created_references.clear()
|
created_references.clear()
|
||||||
|
for tag_id in created_tags:
|
||||||
|
call("DELETE", f"/reference-tags/{tag_id}", expect=204)
|
||||||
|
created_tags.clear()
|
||||||
remaining = call("GET", "/references")
|
remaining = call("GET", "/references")
|
||||||
check("nothing of ours is left", remaining["total"] == 0, str(remaining["total"]))
|
check("nothing of ours is left", remaining["total"] == 0, str(remaining["total"]))
|
||||||
|
check(
|
||||||
|
"and no labels either",
|
||||||
|
call("GET", "/reference-tags")["total"] == 0,
|
||||||
|
str(call("GET", "/reference-tags")["total"]),
|
||||||
|
)
|
||||||
|
|
||||||
print(f"\nall {_checks} checks passed")
|
print(f"\nall {_checks} checks passed")
|
||||||
return 0
|
return 0
|
||||||
@@ -254,6 +392,12 @@ def main() -> int:
|
|||||||
print(f"cleaned up reference {reference_id}")
|
print(f"cleaned up reference {reference_id}")
|
||||||
except Exception as error: # noqa: BLE001
|
except Exception as error: # noqa: BLE001
|
||||||
print(f"cleanup of reference {reference_id} failed: {error}", file=sys.stderr)
|
print(f"cleanup of reference {reference_id} failed: {error}", file=sys.stderr)
|
||||||
|
for tag_id in created_tags:
|
||||||
|
try:
|
||||||
|
call("DELETE", f"/reference-tags/{tag_id}", expect=204)
|
||||||
|
print(f"cleaned up tag {tag_id}")
|
||||||
|
except Exception as error: # noqa: BLE001
|
||||||
|
print(f"cleanup of tag {tag_id} failed: {error}", file=sys.stderr)
|
||||||
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
if __name__ == "__main__":
|
||||||
|
|||||||
Reference in New Issue
Block a user