Files
paper-doc/backend/app/models/paper_sentence.py
T
govin e8e129221c frontend: centre the display formula, and let one be set left or right
Display formulas were sitting against the left margin with only their number at
the right, and the cause was a rule I had written myself: the paragraph's
stylesheet set `text-align: left` on `.katex`, which is the very element KaTeX
centres a display formula in. A well-meant attempt to keep a formula from being
justified apart had quietly overridden the centring, and it applied to every
formula in every paper — measured on a paragraph of known width, the formula's
midpoint sat 607px left of centre.

The override is gone; the rule carries only a font size now, and a comment says
why nothing about alignment belongs there.

`paper_sentence.formula_align` then adds the choice the writer asked for: a
display formula can be `center` (the default, and what a paper wants almost
always), `left` or `right`. It is per sentence rather than a template-field
setting — one paragraph legitimately mixes a centred equation with a
right-aligned continuation, and a field describes a heading, not a formula — and
the paragraph editor offers it only on rows that contain display maths, since
only those have a line of their own. The equation number is untouched: `\tag{1}`
prints against the right margin in all three cases, as every numbered style
does.

Measured in the browser on a 1276px paragraph: centred puts the formula 596px
from each edge, left puts it at 0, right puts it at 1225, and the tag is at the
right in every case. 56 paper checks (2 new: the round trip and the refusal of
an alignment the renderer does not know), 61 reference checks, 99 MCP checks,
`vue-tsc` and the build all pass.
2026-09-23 13:14:52 +08:00

136 lines
5.7 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_title_placement``. 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_title_placement_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 Boolean, ForeignKey, Index, Integer, String, Text, text
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.db.base import Base
from app.models.mixins import TimestampMixin
#: How a display formula may be set on its line. ``center`` is what a paper
#: wants almost always, and the default for every existing row.
FORMULA_ALIGNMENTS: tuple[str, ...] = ("left", "center", "right")
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="")
#: Print a line break before this sentence.
#:
#: A paragraph is its sentences concatenated, which is right for prose and
#: wrong for what else a paper puts inside one: a display formula, a list of
#: items, an author line. The break is a flag rather than a newline in
#: ``content`` for two reasons — content folds its whitespace so a sentence
#: really is one line, and a break hidden in a string is a break the writer
#: cannot see or remove.
line_break_before: Mapped[bool] = mapped_column(
Boolean,
nullable=False,
default=False,
server_default=text("0"),
)
#: How a display formula in this sentence sits on its line: one of
#: :data:`FORMULA_ALIGNMENTS`. Meaningless for a sentence with no display
#: maths, and it never moves the equation number — ``\tag{1}`` is at the
#: right margin whatever this says, as every numbered style prints it.
formula_align: Mapped[str] = mapped_column(
String(8),
nullable=False,
default="center",
server_default=text("'center'"),
)
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}>"
)