govin
a5f884f440
Two tables were named after the concept they came from rather than the module
they belong to, so the schema read as if the template tables were part of the
paper module. Renamed (data preserved, `RENAME TABLE` moves rows in place):
paper_template -> template the 模板 module
section_field -> template_field_library the 字段库 the 模板 module owns
The paper tables and `template_field` already followed the rule. The rename
carries through everything that named a module:
models Template, TemplateField, TemplateFieldLibrary
schemas Template*, TemplateFieldLibrary*
crud app/crud/template.py, app/crud/template_field_library.py
API /template-field-library (was /section-fields); handlers are now
named after library entries, which removes the ambiguity with
TemplateField — a placement, a different thing entirely
client src/api/templateFieldLibrary.ts
`paper_template_filed_sort` is deliberately untouched: it is a column of the
paper module, spelled as the feature was specified.
TiDB v8.5 with tidb_enable_foreign_key on — as this cluster runs — enforces
foreign keys rather than ignoring them, so the docs' "TiDB does not enforce
foreign keys" was wrong. Corrected, with what actually follows from it: the
rename was rehearsed (RENAME TABLE carries a referencing constraint along), the
API keeps checking first so a violation names the row instead of surfacing a
driver error, and the ORM cascades stay so behaviour does not depend on a
cluster setting.
Revision f27a1c6d9e04 verified both ways; 40 smoke checks, type-check and build
all pass.
106 lines
4.4 KiB
Python
106 lines
4.4 KiB
Python
"""Paper sentences (论文句子表) — the actual writing.
|
|
|
|
One row is one sentence of one paper. The two columns that place it are the
|
|
whole design:
|
|
|
|
``paper_template_filed_sort``
|
|
The ``sort`` of the template placement this sentence belongs to — *not* a
|
|
foreign key to ``template_field``. It is deliberately the position rather
|
|
than the row id, because the position is the only thing two templates can
|
|
meaningfully have in common. Swap the paper's template and this sentence
|
|
lands on whatever the new template puts at that position, with no per
|
|
sentence editing. (The name keeps the spelling the feature was specified
|
|
with; it reads ``template_field_sort``.)
|
|
|
|
``sort``
|
|
Where this sentence sits *inside* that paragraph. A paragraph is reassembled
|
|
by reading its rows in ascending ``sort``, which is why the column is
|
|
required and why the API never leaves it to chance. Values are sparse-
|
|
friendly — 10, 20, 30 leaves room to insert — and ties are legal, broken by
|
|
``id`` so the order is always total and stable.
|
|
|
|
``template_id`` records the template the sentence was *written against*. It is
|
|
provenance, not a lookup key: rendering never filters on it, which is exactly
|
|
why sentences survive a template switch. It is nullable because deleting an old
|
|
template clears it rather than leaving a dangling reference behind.
|
|
|
|
Position in the paper is therefore not stored anywhere as a whole; the document
|
|
is assembled on read from the paper's template plus these rows. See
|
|
:func:`app.crud.paper.build_document`.
|
|
"""
|
|
|
|
from typing import TYPE_CHECKING
|
|
|
|
from sqlalchemy import ForeignKey, Index, Integer, 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.paper import Paper
|
|
from app.models.paper_sentence_reference import PaperSentenceReference
|
|
from app.models.template import Template
|
|
|
|
|
|
class PaperSentence(TimestampMixin, Base):
|
|
"""One sentence, at one position, inside one paragraph of one paper."""
|
|
|
|
__tablename__ = "paper_sentence"
|
|
|
|
__table_args__ = (
|
|
# The document query is "every sentence of this paper, in paragraph then
|
|
# sentence order", so one composite index covers filter and sort both.
|
|
Index(
|
|
"ix_paper_sentence_paper_paragraph_sort",
|
|
"paper_id",
|
|
"paper_template_filed_sort",
|
|
"sort",
|
|
),
|
|
Index("ix_paper_sentence_template_id", "template_id"),
|
|
)
|
|
|
|
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
|
|
|
|
paper_id: Mapped[int] = mapped_column(
|
|
ForeignKey("paper.id", ondelete="CASCADE"),
|
|
nullable=False,
|
|
)
|
|
|
|
#: The template this sentence was written against — provenance only. Reads
|
|
#: never filter on it; see the module docstring.
|
|
template_id: Mapped[int | None] = mapped_column(
|
|
ForeignKey("template.id", ondelete="SET NULL"),
|
|
nullable=True,
|
|
)
|
|
|
|
#: Which paragraph, expressed as the template placement's ``sort``.
|
|
#: Required: a sentence with no paragraph has nowhere to be rendered.
|
|
paper_template_filed_sort: Mapped[int] = mapped_column(Integer, nullable=False)
|
|
|
|
#: This sentence's position inside that paragraph. Ascending, ties broken
|
|
#: by ``id``. Required for the same reason.
|
|
sort: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
|
|
|
|
#: The sentence itself. May be empty: an empty sentence is a legitimate
|
|
#: placeholder and renders as a blank line rather than disappearing.
|
|
content: Mapped[str] = mapped_column(Text, nullable=False, default="")
|
|
|
|
paper: Mapped["Paper"] = relationship(back_populates="sentences")
|
|
|
|
#: References quoted by this sentence, in citation order. Eager-loaded
|
|
#: because the document render always needs them, and one query per
|
|
#: sentence would be the difference between two queries and two hundred.
|
|
citations: Mapped[list["PaperSentenceReference"]] = relationship(
|
|
back_populates="sentence",
|
|
cascade="all, delete-orphan",
|
|
order_by="PaperSentenceReference.sort, PaperSentenceReference.id",
|
|
lazy="selectin",
|
|
)
|
|
|
|
def __repr__(self) -> str: # pragma: no cover - debugging aid
|
|
return (
|
|
f"<PaperSentence id={self.id} paper_id={self.paper_id} "
|
|
f"paragraph={self.paper_template_filed_sort} sort={self.sort}>"
|
|
)
|