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:
@@ -19,6 +19,10 @@ after its table (``Template`` -> ``template``):
|
||||
paper the 论文 module
|
||||
paper_sentence one sentence of one paper
|
||||
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
|
||||
opposite things: the first is a *placement* (this template puts this field
|
||||
@@ -42,11 +46,17 @@ from app.models.reference import (
|
||||
Reference,
|
||||
)
|
||||
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_title_placement import TemplateTitlePlacement
|
||||
from app.models.template_title import TemplateTitle
|
||||
|
||||
__all__ = [
|
||||
"DEFAULT_TAG_COLOR",
|
||||
"PAPER_STATUSES",
|
||||
"STATUS_DONE",
|
||||
"STATUS_DRAFT",
|
||||
@@ -59,8 +69,10 @@ __all__ = [
|
||||
"REFERENCE_TYPES",
|
||||
"Reference",
|
||||
"ReferenceAuthor",
|
||||
"ReferenceTag",
|
||||
"Template",
|
||||
"TemplateTitlePlacement",
|
||||
"TemplateTitle",
|
||||
"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
|
||||
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
|
||||
----------------------------
|
||||
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
|
||||
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.
|
||||
#:
|
||||
@@ -238,5 +247,16 @@ class Reference(TimestampMixin, Base):
|
||||
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
|
||||
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}>"
|
||||
Reference in New Issue
Block a user