refactor: call a heading a title, and its use a placement

`template_field_library` and `template_field` were one word apart and meant
opposite kinds of thing — a catalogue of rows versus one row — and neither name
said what a row actually is. Every row of the library is a **heading**: a piece
of text like 「1. Introduction」 with a level and typography, which is what the
reader sees at the top of a paragraph; and every row of the join table is that
heading *placed* in a template, `sort` included.

    template_field_library  -> template_title
    template_field          -> template_title_placement
    field_id (the column)   -> title_id
    TemplateFieldLibrary    -> TemplateTitle
    TemplateField           -> TemplateTitlePlacement

The join table keeps its own name rather than becoming `_link`, because it is
not a bare link: it carries `sort`, the only place display order is stored, and
it deliberately allows the same title twice in one template. `_link` would
describe two foreign keys and hide the column the ordering rule rests on.

Carried through every level, because a half-renamed layer is how the confusing
pair got there in the first place: HTTP paths (`/template-field-library` ->
`/template-titles`), the template payload (`fields`/`field_id` ->
`placements`/`title_id`, and `field_count` -> `placement_count`), the Pydantic
schemas, the CRUD modules, the seed script, the frontend API module and types,
and `docs/OVERVIEW.md`, which now states the naming rules outright.

Two deliberate exceptions:

* `paper_template_filed_sort` is untouched — it is a column of the paper module
  and is spelled as the feature was specified.
* The MCP tools keep their agent-facing names (`field_list`, `field_ids`, and
  the `fields`/`field_id` keys in their responses). Agents already call them by
  those names; the storage names they read underneath have changed.

The migration renames in place (data preserved: 4 templates, 45 titles, 63
placements) and is written to tolerate a database where part of it already ran,
which is not hypothetical — the first attempt renamed the tables and then failed
on the column, because Alembic's MySQL dialect wants an explicit type for
`alter_column` and will not rename a column without one. TiDB carries the
foreign key along with both the renamed table and the renamed column, rehearsed
against the cluster first, and it stays enforced.

Verified: seed re-runs clean, the paper smoke test's 45 checks and the MCP
smoke test's 47 pass, `vue-tsc` and the build are clean, and the UI was driven
in a headless browser through the template list, its preview drawer, the title
library page, the template form (which now posts `placements` with `title_id`)
and the paper document with no console errors.
This commit is contained in:
2026-09-22 16:55:02 +08:00
parent 3732e36e64
commit 199e328b48
40 changed files with 837 additions and 663 deletions
@@ -0,0 +1,122 @@
"""rename the template tables and columns to the title vocabulary
Three names described the same thing by different words, so the schema read as
if it held four concepts:
template_field_library the catalogue of reusable headings (字段库)
template_field one heading placed in one template, with its sort
``template_field`` is one word away from ``template_field_library`` and means
the opposite kind of thing — a row versus the catalogue of rows — and neither
name says what a row actually is. Every row of the library is a **heading**: a
piece of text like 「1. Introduction」 with a level and typography, which is what
the reader sees at the top of a paragraph. So the library becomes
``template_title`` and the placement becomes ``template_title_placement``, and
the placement's reference to the library becomes ``title_id``. The name now says
which is the catalogue and which is a placement, which is the distinction the
old pair hid.
template_title one reusable heading (字段库)
template_title_placement that heading placed in a template, with `sort`
Nothing else moves: ``template`` keeps its name, and every row in every table is
preserved. ``RENAME TABLE`` moves the data in place, and TiDB carries a
referencing foreign key along with both a renamed table and a renamed column
(rehearsed against the cluster before this revision was written), so the
constraint in ``template_title_placement`` follows without a drop/recreate step
and stays enforced.
Revision ID: b19e4d7a3c58
Revises: a83f5c21d7b6
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 = "b19e4d7a3c58"
down_revision: str | None = "a83f5c21d7b6"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
#: (old, new) index names on the placement table. They embed the table name and
#: the column name, so both renames have to reach them or the schema ends up
#: with indexes named after tables that no longer exist.
_INDEXES = (
("ix_template_field_field_id", "ix_template_title_placement_title_id"),
("ix_template_field_template_sort", "ix_template_title_placement_template_sort"),
)
#: Index names that already say the new thing, so a rerun leaves them alone.
_NEW_INDEXES = {new for _, new in _INDEXES}
def upgrade() -> None:
"""Rename in place, tolerating a database where part of it already ran.
Each step is guarded by what the database actually holds, rather than
assuming a clean start. That is not decoration: the first attempt at this
revision renamed the two tables and then failed on the column, because
Alembic's MySQL dialect wants an explicit type for ``alter_column`` and
won't rename a column without one. A migration that re-runs is the only way
to finish a database left in that state, and it costs three dict lookups to
be able to.
"""
bind = op.get_bind()
inspector = sa.inspect(bind)
tables = set(inspector.get_table_names())
if "template_field_library" in tables:
op.rename_table("template_field_library", "template_title")
if "template_field" in tables:
op.rename_table("template_field", "template_title_placement")
columns = {
column["name"]
for column in inspector.get_columns("template_title_placement")
}
if "field_id" in columns:
# Raw SQL rather than ``op.alter_column``: TiDB supports
# ``RENAME COLUMN`` directly, and the Alembic spelling goes through
# ``CHANGE COLUMN``, which demands the current type be repeated.
op.execute(
"ALTER TABLE template_title_placement RENAME COLUMN field_id TO title_id"
)
indexes = {index["name"] for index in inspector.get_indexes("template_title_placement")}
for old, new in _INDEXES:
if old in indexes and new not in indexes:
op.execute(
f"ALTER TABLE template_title_placement RENAME INDEX {old} TO {new}"
)
def downgrade() -> None:
bind = op.get_bind()
inspector = sa.inspect(bind)
indexes = {
index["name"]
for index in inspector.get_indexes("template_title_placement")
}
for old, new in _INDEXES:
if new in indexes and old not in indexes:
op.execute(
f"ALTER TABLE template_title_placement RENAME INDEX {new} TO {old}"
)
columns = {
column["name"]
for column in inspector.get_columns("template_title_placement")
}
if "title_id" in columns:
op.execute(
"ALTER TABLE template_title_placement RENAME COLUMN title_id TO field_id"
)
op.rename_table("template_title_placement", "template_field")
op.rename_table("template_title", "template_field_library")
+2 -2
View File
@@ -2,10 +2,10 @@
from fastapi import APIRouter from fastapi import APIRouter
from app.api.routes import health, papers, template_field_library, templates from app.api.routes import health, papers, 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(template_field_library.router) api_router.include_router(template_titles.router)
api_router.include_router(templates.router) api_router.include_router(templates.router)
@@ -1,157 +0,0 @@
"""Template-field library endpoints (字段管理).
The library is global and reusable: a field exists once and is then placed into
any number of templates. That is why deleting a field is guarded — the join
table is the only thing keeping a template's outline intact, and silently
dropping a live heading from every template would be data loss, not cleanup.
"""
from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
from sqlalchemy.orm import Session
from app.crud import template_field_library as crud
from app.db.session import get_db
from app.models import TemplateFieldLibrary
from app.schemas.common import BatchDeleteRequest, BatchDeleteResult, PageResult
from app.schemas.template_field_library import (
TemplateFieldLibraryCreate,
TemplateFieldLibraryRead,
TemplateFieldLibraryUpdate,
)
router = APIRouter(prefix="/template-field-library", tags=["template-field-library"])
def _get_or_404(db: Session, field_id: int) -> TemplateFieldLibrary:
field = crud.get(db, field_id)
if field is None:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=f"字段 {field_id} 不存在",
)
return field
def _assert_unused(db: Session, fields: list[TemplateFieldLibrary]) -> None:
"""Refuse the delete if any field is still placed in a template.
All offenders are reported at once rather than one per attempt, so a batch
delete does not turn into trial and error.
"""
counts = crud.usage_counts(db, [field.id for field in fields])
if not counts:
return
by_id = {field.id: field.name for field in fields}
blockers = "、".join(
f"“{by_id.get(field_id, field_id)}”({count} 个模板)"
for field_id, count in sorted(counts.items())
)
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail=f"以下字段正被模板使用,请先在模板中移除:{blockers}",
)
@router.get(
"",
response_model=PageResult[TemplateFieldLibraryRead],
summary="List the field library",
)
def list_library_entries(
db: Session = Depends(get_db),
keyword: str | None = Query(default=None, description="按字段名称模糊搜索"),
level: int | None = Query(default=None, ge=1, le=9, description="按字段等级过滤"),
page: int = Query(default=1, ge=1),
page_size: int = Query(default=20, ge=1, le=500),
) -> PageResult[TemplateFieldLibraryRead]:
"""Browse the field library, grouped by level then creation order."""
rows, total = crud.list_fields(
db,
keyword=keyword,
level=level,
page=page,
page_size=page_size,
)
return PageResult.build(
items=[TemplateFieldLibraryRead.model_validate(row) for row in rows],
total=total,
page=page,
page_size=page_size,
)
@router.post(
"",
response_model=TemplateFieldLibraryRead,
status_code=status.HTTP_201_CREATED,
summary="Create a library entry",
)
def create_library_entry(
payload: TemplateFieldLibraryCreate,
db: Session = Depends(get_db),
) -> TemplateFieldLibraryRead:
"""Add a heading to the library, with its typography."""
return TemplateFieldLibraryRead.model_validate(crud.create(db, payload))
@router.post(
"/batch-delete",
response_model=BatchDeleteResult,
summary="Delete several library entries",
)
def batch_delete_library_entries(
payload: BatchDeleteRequest,
db: Session = Depends(get_db),
) -> BatchDeleteResult:
"""Delete the given fields, refusing wholesale if any is still in use."""
fields = crud.get_many(db, payload.ids)
_assert_unused(db, fields)
for field in fields:
crud.delete(db, field)
return BatchDeleteResult(deleted=len(fields))
@router.get(
"/{field_id}",
response_model=TemplateFieldLibraryRead,
summary="Fetch one library entry",
)
def get_library_entry(
field_id: int, db: Session = Depends(get_db)
) -> TemplateFieldLibraryRead:
"""Return a single library entry."""
return TemplateFieldLibraryRead.model_validate(_get_or_404(db, field_id))
@router.patch(
"/{field_id}",
response_model=TemplateFieldLibraryRead,
summary="Update one library entry",
)
def update_library_entry(
field_id: int,
payload: TemplateFieldLibraryUpdate,
db: Session = Depends(get_db),
) -> TemplateFieldLibraryRead:
"""Rename or restyle a library entry.
The change is visible in every template that places the field, because
templates store a reference rather than a copy.
"""
field = _get_or_404(db, field_id)
return TemplateFieldLibraryRead.model_validate(crud.update(db, field, payload))
@router.delete(
"/{field_id}",
status_code=status.HTTP_204_NO_CONTENT,
summary="Delete one library entry",
)
def delete_library_entry(field_id: int, db: Session = Depends(get_db)) -> Response:
"""Delete a library entry no template places."""
field = _get_or_404(db, field_id)
_assert_unused(db, [field])
crud.delete(db, field)
return Response(status_code=status.HTTP_204_NO_CONTENT)
+157
View File
@@ -0,0 +1,157 @@
"""Template-title library endpoints (字段管理).
The library is global and reusable: a title exists once and is then placed into
any number of templates. That is why deleting one is guarded — the join table
is the only thing keeping a template's outline intact, and silently dropping a
live heading from every template would be data loss, not cleanup.
"""
from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
from sqlalchemy.orm import Session
from app.crud import template_title as crud
from app.db.session import get_db
from app.models import TemplateTitle
from app.schemas.common import BatchDeleteRequest, BatchDeleteResult, PageResult
from app.schemas.template_title import (
TemplateTitleCreate,
TemplateTitleRead,
TemplateTitleUpdate,
)
router = APIRouter(prefix="/template-titles", tags=["template-titles"])
def _get_or_404(db: Session, title_id: int) -> TemplateTitle:
title = crud.get(db, title_id)
if title is None:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=f"标题 {title_id} 不存在",
)
return title
def _assert_unused(db: Session, titles: list[TemplateTitle]) -> None:
"""Refuse the delete if any title is still placed in a template.
All offenders are reported at once rather than one per attempt, so a batch
delete does not turn into trial and error.
"""
counts = crud.usage_counts(db, [title.id for title in titles])
if not counts:
return
by_id = {title.id: title.name for title in titles}
blockers = "、".join(
f"“{by_id.get(title_id, title_id)}”({count} 个模板)"
for title_id, count in sorted(counts.items())
)
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail=f"以下标题正被模板使用,请先在模板中移除:{blockers}",
)
@router.get(
"",
response_model=PageResult[TemplateTitleRead],
summary="List the title library",
)
def list_titles(
db: Session = Depends(get_db),
keyword: str | None = Query(default=None, description="按字段名称模糊搜索"),
level: int | None = Query(default=None, ge=1, le=9, description="按字段等级过滤"),
page: int = Query(default=1, ge=1),
page_size: int = Query(default=20, ge=1, le=500),
) -> PageResult[TemplateTitleRead]:
"""Browse the title library, grouped by level then creation order."""
rows, total = crud.list_titles(
db,
keyword=keyword,
level=level,
page=page,
page_size=page_size,
)
return PageResult.build(
items=[TemplateTitleRead.model_validate(row) for row in rows],
total=total,
page=page,
page_size=page_size,
)
@router.post(
"",
response_model=TemplateTitleRead,
status_code=status.HTTP_201_CREATED,
summary="Create a library entry",
)
def create_title(
payload: TemplateTitleCreate,
db: Session = Depends(get_db),
) -> TemplateTitleRead:
"""Add a heading to the library, with its typography."""
return TemplateTitleRead.model_validate(crud.create(db, payload))
@router.post(
"/batch-delete",
response_model=BatchDeleteResult,
summary="Delete several library entries",
)
def batch_delete_titles(
payload: BatchDeleteRequest,
db: Session = Depends(get_db),
) -> BatchDeleteResult:
"""Delete the given titles, refusing wholesale if any is still in use."""
titles = crud.get_many(db, payload.ids)
_assert_unused(db, titles)
for title in titles:
crud.delete(db, title)
return BatchDeleteResult(deleted=len(titles))
@router.get(
"/{title_id}",
response_model=TemplateTitleRead,
summary="Fetch one library entry",
)
def get_title(
title_id: int, db: Session = Depends(get_db)
) -> TemplateTitleRead:
"""Return a single library entry."""
return TemplateTitleRead.model_validate(_get_or_404(db, title_id))
@router.patch(
"/{title_id}",
response_model=TemplateTitleRead,
summary="Update one library entry",
)
def update_title(
title_id: int,
payload: TemplateTitleUpdate,
db: Session = Depends(get_db),
) -> TemplateTitleRead:
"""Rename or restyle a library entry.
The change is visible in every template that places the title, because
templates store a reference rather than a copy.
"""
title = _get_or_404(db, title_id)
return TemplateTitleRead.model_validate(crud.update(db, title, payload))
@router.delete(
"/{title_id}",
status_code=status.HTTP_204_NO_CONTENT,
summary="Delete one library entry",
)
def delete_title(title_id: int, db: Session = Depends(get_db)) -> Response:
"""Delete a library entry no template places."""
title = _get_or_404(db, title_id)
_assert_unused(db, [title])
crud.delete(db, title)
return Response(status_code=status.HTTP_204_NO_CONTENT)
+19 -19
View File
@@ -1,14 +1,14 @@
"""Paper-template endpoints (模板管理). """Paper-template endpoints (模板管理).
A template is created from two pieces of free text plus a free selection of A template is created from two pieces of free text plus a free selection of
library fields. Nothing constrains the selection: the same field may be picked library titles. Nothing constrains the selection: the same title may be picked
twice, the picks may arrive in any order, and the only thing that decides how twice, the picks may arrive in any order, and the only thing that decides how
the outline reads is ``sort``. the outline reads is ``sort``.
A template that a paper is written against is also *structure* for that paper, A template that a paper is written against is also *structure* for that paper,
not only configuration: deleting it would leave the paper with nothing to not only configuration: deleting it would leave the paper with nothing to
render. That delete is therefore refused, with the same 409 the field library render. That delete is therefore refused, with the same 409 the title library
uses for a field still placed in a template. uses for a title still placed in a template.
""" """
from fastapi import APIRouter, Depends, HTTPException, Query, Response, status from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
@@ -73,19 +73,19 @@ def _assert_not_used_by_papers(db: Session, template_ids: list[int]) -> None:
) )
def _assert_fields_exist(db: Session, field_ids: list[int]) -> None: def _assert_titles_exist(db: Session, title_ids: list[int]) -> None:
"""Reject a selection that references fields the library does not have. """Reject a selection that references titles the library does not have.
Checked in Python rather than by a foreign key because TiDB parses but does Checked in Python rather than by a foreign key because TiDB parses but does
not enforce ``FOREIGN KEY``, so an unchecked write would happily leave a not enforce ``FOREIGN KEY``, so an unchecked write would happily leave a
template pointing at nothing. template pointing at nothing.
""" """
missing = crud.missing_field_ids(db, field_ids) missing = crud.missing_title_ids(db, title_ids)
if missing: if missing:
joined = "、".join(str(field_id) for field_id in missing) joined = "、".join(str(title_id) for title_id in missing)
raise HTTPException( raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST, status_code=status.HTTP_400_BAD_REQUEST,
detail=f"字段不存在:{joined}", detail=f"标题不存在:{joined}",
) )
@@ -117,15 +117,15 @@ def create_template(
payload: TemplateCreate, payload: TemplateCreate,
db: Session = Depends(get_db), db: Session = Depends(get_db),
) -> TemplateRead: ) -> TemplateRead:
"""Create a template from a name, an abstract, and a field selection.""" """Create a template from a name, an abstract, and a title selection."""
_assert_name_free(db, payload.name) _assert_name_free(db, payload.name)
_assert_fields_exist(db, [item.field_id for item in payload.fields]) _assert_titles_exist(db, [item.title_id for item in payload.placements])
template = crud.create( template = crud.create(
db, db,
name=payload.name, name=payload.name,
abstract=payload.abstract, abstract=payload.abstract,
fields=payload.fields, placements=payload.placements,
) )
return TemplateRead.from_model(template) return TemplateRead.from_model(template)
@@ -150,7 +150,7 @@ def batch_delete_templates(
summary="Fetch one paper template with its outline", summary="Fetch one paper template with its outline",
) )
def get_template(template_id: int, db: Session = Depends(get_db)) -> TemplateRead: def get_template(template_id: int, db: Session = Depends(get_db)) -> TemplateRead:
"""Return a template; ``fields`` arrives already ordered by ``sort``.""" """Return a template; ``placements`` arrives already ordered by ``sort``."""
return TemplateRead.from_model(_get_or_404(db, template_id)) return TemplateRead.from_model(_get_or_404(db, template_id))
@@ -164,27 +164,27 @@ def update_template(
payload: TemplateUpdate, payload: TemplateUpdate,
db: Session = Depends(get_db), db: Session = Depends(get_db),
) -> TemplateRead: ) -> TemplateRead:
"""Update the name, the abstract, the field selection, or any combination. """Update the name, the abstract, the title selection, or any combination.
``fields`` is a full replacement when present. Omitting it leaves the ``placements`` is a full replacement when present. Omitting it leaves the
outline untouched; sending ``[]`` clears it. outline untouched; sending ``[]`` clears it.
""" """
template = _get_or_404(db, template_id) template = _get_or_404(db, template_id)
if payload.name is not None: if payload.name is not None:
_assert_name_free(db, payload.name, exclude_id=template_id) _assert_name_free(db, payload.name, exclude_id=template_id)
if payload.fields is not None: if payload.placements is not None:
_assert_fields_exist(db, [item.field_id for item in payload.fields]) _assert_titles_exist(db, [item.title_id for item in payload.placements])
updated = crud.update( updated = crud.update(
db, db,
template, template,
name=payload.name, name=payload.name,
abstract=payload.abstract, abstract=payload.abstract,
# Both "field omitted" and "field set to null" arrive as None; only # Both "key omitted" and "key set to null" arrive as None; only
# model_fields_set records which one the client actually sent. # model_fields_set records which one the client actually sent.
abstract_provided="abstract" in payload.model_fields_set, abstract_provided="abstract" in payload.model_fields_set,
fields=payload.fields, placements=payload.placements,
) )
return TemplateRead.from_model(updated) return TemplateRead.from_model(updated)
@@ -195,7 +195,7 @@ def update_template(
summary="Delete a paper template", summary="Delete a paper template",
) )
def delete_template(template_id: int, db: Session = Depends(get_db)) -> Response: def delete_template(template_id: int, db: Session = Depends(get_db)) -> Response:
"""Delete a template. Library fields it referenced are left alone. """Delete a template. Library titles it referenced are left alone.
Refused while a paper is written against the template: the outline is the Refused while a paper is written against the template: the outline is the
paper's structure, and removing it would empty the paper rather than tidy paper's structure, and removing it would empty the paper rather than tidy
+2 -2
View File
@@ -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, template, template_field_library from app.crud import paper, template, template_title
__all__ = ["paper", "template", "template_field_library"] __all__ = ["paper", "template", "template_title"]
+16 -16
View File
@@ -37,7 +37,7 @@ from app.models import (
PaperSentence, PaperSentence,
PaperSentenceReference, PaperSentenceReference,
Template, Template,
TemplateField, TemplateTitlePlacement,
) )
from app.schemas.paper import ( from app.schemas.paper import (
CitationInput, CitationInput,
@@ -112,8 +112,8 @@ def _template_paragraph_count_column():
is one paragraph, not two. A paper with no template counts 0. is one paragraph, not two. A paper with no template counts 0.
""" """
return ( return (
select(func.count(func.distinct(TemplateField.sort))) select(func.count(func.distinct(TemplateTitlePlacement.sort)))
.where(TemplateField.template_id == Paper.template_id) .where(TemplateTitlePlacement.template_id == Paper.template_id)
.correlate(Paper) .correlate(Paper)
.scalar_subquery() .scalar_subquery()
) )
@@ -219,7 +219,7 @@ def read(paper: Paper) -> PaperRead:
sentence_count=len(paper.sentences), sentence_count=len(paper.sentences),
paragraph_count=len({s.paper_template_filed_sort for s in paper.sentences}), paragraph_count=len({s.paper_template_filed_sort for s in paper.sentences}),
template_paragraph_count=( template_paragraph_count=(
len({placement.sort for placement in paper.template.items}) len({placement.sort for placement in paper.template.placements})
if paper.template is not None if paper.template is not None
else 0 else 0
), ),
@@ -301,15 +301,15 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead:
# ``sort, id`` — is the one that renders the heading. The reader is told, # ``sort, id`` — is the one that renders the heading. The reader is told,
# because two fields sharing a position is far more often a mistake than a # because two fields sharing a position is far more often a mistake than a
# plan. # plan.
placement_by_sort: dict[int, TemplateField] = {} placement_by_sort: dict[int, TemplateTitlePlacement] = {}
tied: dict[int, list[str]] = defaultdict(list) tied: dict[int, list[str]] = defaultdict(list)
for item in paper.template.items if paper.template is not None else []: for item in paper.template.placements if paper.template is not None else []:
if item.sort in placement_by_sort: if item.sort in placement_by_sort:
tied[item.sort].append(item.field.name) tied[item.sort].append(item.title.name)
else: else:
placement_by_sort[item.sort] = item placement_by_sort[item.sort] = item
for sort, names in sorted(tied.items()): for sort, names in sorted(tied.items()):
head = placement_by_sort[sort].field.name head = placement_by_sort[sort].title.name
warnings.append( warnings.append(
f"模板在第 {sort} 段放了多个字段({head}、{'、'.join(names)})," f"模板在第 {sort} 段放了多个字段({head}、{'、'.join(names)}),"
"正文按第一条显示。" "正文按第一条显示。"
@@ -322,7 +322,7 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead:
if paper.template is None and paper.sentences: if paper.template is None and paper.sentences:
warnings.append("这篇论文还没有选择模板,段落没有对应标题,全部按未设定显示。") warnings.append("这篇论文还没有选择模板,段落没有对应标题,全部按未设定显示。")
if paper.template is not None and not paper.template.items: if paper.template is not None and not paper.template.placements:
warnings.append("所用模板还没有任何段落字段,论文暂时没有结构。") warnings.append("所用模板还没有任何段落字段,论文暂时没有结构。")
# --- 3. the union, in ascending position order -------------------------- # --- 3. the union, in ascending position order --------------------------
@@ -334,7 +334,7 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead:
for position in positions: for position in positions:
placement = placement_by_sort.get(position) placement = placement_by_sort.get(position)
field = placement.field if placement is not None else None title = placement.title if placement is not None else None
# Re-sorted rather than trusted: the relationship already orders rows, # Re-sorted rather than trusted: the relationship already orders rows,
# but ordering is a contract of this response, so it is stated here too. # but ordering is a contract of this response, so it is stated here too.
@@ -352,12 +352,12 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead:
paragraph = ParagraphRead( paragraph = ParagraphRead(
paper_template_filed_sort=position, paper_template_filed_sort=position,
template_field_id=placement.id if placement is not None else None, placement_id=placement.id if placement is not None else None,
field_id=field.id if field is not None else None, title_id=title.id if title is not None else None,
name=field.name if field is not None else None, name=title.name if title is not None else None,
level=field.level if field is not None else 1, level=title.level if title is not None else 1,
font_size=float(field.font_size) if field is not None else None, font_size=float(title.font_size) if title is not None else None,
font_color=field.font_color if field is not None else None, font_color=title.font_color if title is not None else None,
matched=placement is not None, matched=placement is not None,
sentences=sentences, sentences=sentences,
) )
+33 -29
View File
@@ -1,4 +1,4 @@
"""Data access for templates and their ordered field selections.""" """Data access for templates and their ordered title selections."""
from collections.abc import Sequence from collections.abc import Sequence
@@ -6,8 +6,8 @@ from sqlalchemy import func, or_, select
from sqlalchemy.orm import Session from sqlalchemy.orm import Session
from app.crud.filters import LIKE_ESCAPE, like_pattern from app.crud.filters import LIKE_ESCAPE, like_pattern
from app.models import Template, TemplateFieldLibrary, TemplateField from app.models import Template, TemplateTitle, TemplateTitlePlacement
from app.schemas.template import TemplateListItem, TemplateFieldInput from app.schemas.template import TemplateListItem, TemplateTitlePlacementInput
def _conditions(keyword: str | None) -> list: def _conditions(keyword: str | None) -> list:
@@ -23,11 +23,11 @@ def _conditions(keyword: str | None) -> list:
] ]
def _field_count_column(): def _placement_count_column():
"""A correlated ``COUNT`` of the template's placement rows.""" """A correlated ``COUNT`` of the template's placement rows."""
return ( return (
select(func.count(TemplateField.id)) select(func.count(TemplateTitlePlacement.id))
.where(TemplateField.template_id == Template.id) .where(TemplateTitlePlacement.template_id == Template.id)
.correlate(Template) .correlate(Template)
.scalar_subquery() .scalar_subquery()
) )
@@ -40,7 +40,7 @@ def list_templates(
page: int = 1, page: int = 1,
page_size: int = 20, page_size: int = 20,
) -> tuple[list[TemplateListItem], int]: ) -> tuple[list[TemplateListItem], int]:
"""Return one page of templates with their field counts, plus the total. """Return one page of templates with their placement counts, plus the total.
The outline itself is left out: a table row needs the count, not the rows. The outline itself is left out: a table row needs the count, not the rows.
Recently edited templates come first, since that is what a user returns to. Recently edited templates come first, since that is what a user returns to.
@@ -52,7 +52,7 @@ def list_templates(
) or 0 ) or 0
stmt = ( stmt = (
select(Template, _field_count_column().label("field_count")) select(Template, _placement_count_column().label("placement_count"))
.where(*conditions) .where(*conditions)
.order_by(Template.updated_at.desc(), Template.id.desc()) .order_by(Template.updated_at.desc(), Template.id.desc())
.offset((page - 1) * page_size) .offset((page - 1) * page_size)
@@ -64,11 +64,11 @@ def list_templates(
id=template.id, id=template.id,
name=template.name, name=template.name,
abstract=template.abstract, abstract=template.abstract,
field_count=field_count, placement_count=placement_count,
created_at=template.created_at, created_at=template.created_at,
updated_at=template.updated_at, updated_at=template.updated_at,
) )
for template, field_count in db.execute(stmt).all() for template, placement_count in db.execute(stmt).all()
] ]
return items, total return items, total
@@ -76,9 +76,9 @@ def list_templates(
def get(db: Session, template_id: int) -> Template | None: def get(db: Session, template_id: int) -> Template | None:
"""Return one template with its outline already loaded, or ``None``. """Return one template with its outline already loaded, or ``None``.
``items`` (ordered by ``sort``) and each item's ``field`` are both ``placements`` (ordered by ``sort``) and each placement's ``title`` are
configured for eager loading on the relationships, so this is a fixed both configured for eager loading on the relationships, so this is a fixed
number of queries rather than one per field. number of queries rather than one per title.
""" """
return db.get(Template, template_id) return db.get(Template, template_id)
@@ -91,24 +91,29 @@ def name_taken(db: Session, name: str, *, exclude_id: int | None = None) -> bool
return bool(db.scalar(stmt)) return bool(db.scalar(stmt))
def missing_field_ids(db: Session, field_ids: Sequence[int]) -> list[int]: def missing_title_ids(db: Session, title_ids: Sequence[int]) -> list[int]:
"""Which of ``field_ids`` do not exist in the field library. """Which of ``title_ids`` do not exist in the title library.
Returning the offenders rather than a boolean lets the API name them, which Returning the offenders rather than a boolean lets the API name them, which
is the difference between a usable error and "invalid request". is the difference between a usable error and "invalid request".
""" """
wanted = set(field_ids) wanted = set(title_ids)
if not wanted: if not wanted:
return [] return []
found = set( found = set(
db.scalars(select(TemplateFieldLibrary.id).where(TemplateFieldLibrary.id.in_(wanted))).all() db.scalars(select(TemplateTitle.id).where(TemplateTitle.id.in_(wanted))).all()
) )
return sorted(wanted - found) return sorted(wanted - found)
def _build_items(fields: Sequence[TemplateFieldInput]) -> list[TemplateField]: def _build_placements(
placements: Sequence[TemplateTitlePlacementInput],
) -> list[TemplateTitlePlacement]:
"""Materialise the client's selection into placement rows.""" """Materialise the client's selection into placement rows."""
return [TemplateField(field_id=item.field_id, sort=item.sort) for item in fields] return [
TemplateTitlePlacement(title_id=item.title_id, sort=item.sort)
for item in placements
]
def create( def create(
@@ -116,11 +121,11 @@ def create(
*, *,
name: str, name: str,
abstract: str | None, abstract: str | None,
fields: Sequence[TemplateFieldInput], placements: Sequence[TemplateTitlePlacementInput],
) -> Template: ) -> Template:
"""Insert a template together with its ordered selection.""" """Insert a template together with its ordered selection."""
template = Template(name=name, abstract=abstract) template = Template(name=name, abstract=abstract)
template.items = _build_items(fields) template.placements = _build_placements(placements)
db.add(template) db.add(template)
db.commit() db.commit()
db.refresh(template) db.refresh(template)
@@ -134,9 +139,9 @@ def update(
name: str | None = None, name: str | None = None,
abstract: str | None = None, abstract: str | None = None,
abstract_provided: bool = False, abstract_provided: bool = False,
fields: Sequence[TemplateFieldInput] | None = None, placements: Sequence[TemplateTitlePlacementInput] | None = None,
) -> Template: ) -> Template:
"""Apply a partial update. ``fields=None`` leaves the selection untouched. """Apply a partial update. ``placements=None`` leaves the selection untouched.
``abstract_provided`` distinguishes "clear the abstract" from "leave it" — ``abstract_provided`` distinguishes "clear the abstract" from "leave it" —
both arrive as ``None`` in the payload, and only the caller knows which the both arrive as ``None`` in the payload, and only the caller knows which the
@@ -146,13 +151,12 @@ def update(
template.name = name template.name = name
if abstract_provided: if abstract_provided:
template.abstract = abstract template.abstract = abstract
if fields is not None: if placements is not None:
# delete-orphan removes the dropped rows on flush. TiDB does not # delete-orphan removes the dropped rows on flush. The ORM cascade is
# enforce ON DELETE CASCADE, so this ORM-level cascade is the only # what cleans up the join table, whether or not the database would.
# thing cleaning up the join table. template.placements.clear()
template.items.clear()
db.flush() db.flush()
template.items.extend(_build_items(fields)) template.placements.extend(_build_placements(placements))
db.commit() db.commit()
db.refresh(template) db.refresh(template)
-125
View File
@@ -1,125 +0,0 @@
"""Data access for the reusable template-field library (字段管理)."""
from collections.abc import Sequence
from sqlalchemy import Select, func, select
from sqlalchemy.orm import Session
from app.crud.filters import LIKE_ESCAPE, like_pattern
from app.models import TemplateField, TemplateFieldLibrary
from app.schemas.template_field_library import (
TemplateFieldLibraryCreate,
TemplateFieldLibraryUpdate,
)
def _conditions(keyword: str | None, level: int | None) -> list:
"""Translate the list filters into SQLAlchemy predicates."""
conditions = []
if keyword:
conditions.append(
TemplateFieldLibrary.name.like(like_pattern(keyword), escape=LIKE_ESCAPE)
)
if level is not None:
conditions.append(TemplateFieldLibrary.level == level)
return conditions
def _ordered(stmt: Select) -> Select:
"""Apply the library's canonical browse order.
Grouped by ``level`` first so the picker reads as an outline, then by
insertion order so a field stays where the user put it. Deliberately *not*
ordered by ``name``: names carry hand-written numbering ("1.", "10.",
"2."), and string ordering would scramble it.
"""
return stmt.order_by(TemplateFieldLibrary.level.asc(), TemplateFieldLibrary.id.asc())
def list_fields(
db: Session,
*,
keyword: str | None = None,
level: int | None = None,
page: int = 1,
page_size: int = 20,
) -> tuple[list[TemplateFieldLibrary], int]:
"""Return one page of the field library, plus the unpaged total."""
conditions = _conditions(keyword, level)
total = db.scalar(
select(func.count(TemplateFieldLibrary.id)).where(*conditions)
) or 0
stmt = _ordered(
select(TemplateFieldLibrary)
.where(*conditions)
.offset((page - 1) * page_size)
.limit(page_size)
)
return list(db.scalars(stmt).all()), total
def get(db: Session, field_id: int) -> TemplateFieldLibrary | None:
"""Return one field, or ``None``."""
return db.get(TemplateFieldLibrary, field_id)
def get_many(db: Session, field_ids: Sequence[int]) -> list[TemplateFieldLibrary]:
"""Return every field whose id is in ``field_ids`` (missing ids ignored)."""
if not field_ids:
return []
stmt = select(TemplateFieldLibrary).where(TemplateFieldLibrary.id.in_(list(field_ids)))
return list(db.scalars(stmt).all())
def usage_counts(db: Session, field_ids: Sequence[int]) -> dict[int, int]:
"""Count how many *distinct templates* place each field.
Drives the refusal message when a field in use is deleted. ``DISTINCT``
matters because one template may legitimately place the same field twice.
"""
if not field_ids:
return {}
stmt = (
select(
TemplateField.field_id,
func.count(func.distinct(TemplateField.template_id)),
)
.where(TemplateField.field_id.in_(list(field_ids)))
.group_by(TemplateField.field_id)
)
return {field_id: count for field_id, count in db.execute(stmt).all()}
def create(db: Session, data: TemplateFieldLibraryCreate) -> TemplateFieldLibrary:
"""Insert a field."""
field = TemplateFieldLibrary(**data.model_dump())
db.add(field)
db.commit()
db.refresh(field)
return field
def update(
db: Session,
field: TemplateFieldLibrary,
data: TemplateFieldLibraryUpdate,
) -> TemplateFieldLibrary:
"""Apply a partial update to a field.
``exclude_unset`` is what makes PATCH semantics work: a key the client did
not send leaves the column alone, while an explicit ``null`` — which the
schemas reject for every nullable-typed column here — would not.
"""
for key, value in data.model_dump(exclude_unset=True).items():
setattr(field, key, value)
db.commit()
db.refresh(field)
return field
def delete(db: Session, field: TemplateFieldLibrary) -> None:
"""Delete a field. Callers must check :func:`usage_counts` first."""
db.delete(field)
db.commit()
+125
View File
@@ -0,0 +1,125 @@
"""Data access for the reusable template-title library (字段管理)."""
from collections.abc import Sequence
from sqlalchemy import Select, func, select
from sqlalchemy.orm import Session
from app.crud.filters import LIKE_ESCAPE, like_pattern
from app.models import TemplateTitlePlacement, TemplateTitle
from app.schemas.template_title import (
TemplateTitleCreate,
TemplateTitleUpdate,
)
def _conditions(keyword: str | None, level: int | None) -> list:
"""Translate the list filters into SQLAlchemy predicates."""
conditions = []
if keyword:
conditions.append(
TemplateTitle.name.like(like_pattern(keyword), escape=LIKE_ESCAPE)
)
if level is not None:
conditions.append(TemplateTitle.level == level)
return conditions
def _ordered(stmt: Select) -> Select:
"""Apply the library's canonical browse order.
Grouped by ``level`` first so the picker reads as an outline, then by
insertion order so a title stays where the user put it. Deliberately *not*
ordered by ``name``: names carry hand-written numbering ("1.", "10.",
"2."), and string ordering would scramble it.
"""
return stmt.order_by(TemplateTitle.level.asc(), TemplateTitle.id.asc())
def list_titles(
db: Session,
*,
keyword: str | None = None,
level: int | None = None,
page: int = 1,
page_size: int = 20,
) -> tuple[list[TemplateTitle], int]:
"""Return one page of the title library, plus the unpaged total."""
conditions = _conditions(keyword, level)
total = db.scalar(
select(func.count(TemplateTitle.id)).where(*conditions)
) or 0
stmt = _ordered(
select(TemplateTitle)
.where(*conditions)
.offset((page - 1) * page_size)
.limit(page_size)
)
return list(db.scalars(stmt).all()), total
def get(db: Session, title_id: int) -> TemplateTitle | None:
"""Return one library entry, or ``None``."""
return db.get(TemplateTitle, title_id)
def get_many(db: Session, title_ids: Sequence[int]) -> list[TemplateTitle]:
"""Return every entry whose id is in ``title_ids`` (missing ids ignored)."""
if not title_ids:
return []
stmt = select(TemplateTitle).where(TemplateTitle.id.in_(list(title_ids)))
return list(db.scalars(stmt).all())
def usage_counts(db: Session, title_ids: Sequence[int]) -> dict[int, int]:
"""Count how many *distinct templates* place each title.
Drives the refusal message when a title in use is deleted. ``DISTINCT``
matters because one template may legitimately place the same title twice.
"""
if not title_ids:
return {}
stmt = (
select(
TemplateTitlePlacement.title_id,
func.count(func.distinct(TemplateTitlePlacement.template_id)),
)
.where(TemplateTitlePlacement.title_id.in_(list(title_ids)))
.group_by(TemplateTitlePlacement.title_id)
)
return {title_id: count for title_id, count in db.execute(stmt).all()}
def create(db: Session, data: TemplateTitleCreate) -> TemplateTitle:
"""Insert a library entry."""
title = TemplateTitle(**data.model_dump())
db.add(title)
db.commit()
db.refresh(title)
return title
def update(
db: Session,
title: TemplateTitle,
data: TemplateTitleUpdate,
) -> TemplateTitle:
"""Apply a partial update to a library entry.
``exclude_unset`` is what makes PATCH semantics work: a key the client did
not send leaves the column alone, while an explicit ``null`` — which the
schemas reject for every nullable-typed column here — would not.
"""
for key, value in data.model_dump(exclude_unset=True).items():
setattr(title, key, value)
db.commit()
db.refresh(title)
return title
def delete(db: Session, title: TemplateTitle) -> None:
"""Delete a library entry. Callers must check :func:`usage_counts` first."""
db.delete(title)
db.commit()
+3 -3
View File
@@ -23,7 +23,7 @@ from sqlalchemy import func, select
from app.core.config import get_settings from app.core.config import get_settings
from app.db.session import SessionLocal from app.db.session import SessionLocal
from app.mcp.server import SERVER_VERSION from app.mcp.server import SERVER_VERSION
from app.models import Paper, PaperSentence, Template, TemplateFieldLibrary from app.models import Paper, PaperSentence, Template, TemplateTitle
def run_selfcheck(server: MCPServer) -> int: def run_selfcheck(server: MCPServer) -> int:
@@ -38,8 +38,8 @@ def run_selfcheck(server: MCPServer) -> int:
"paper": db.scalar(select(func.count(Paper.id))) or 0, "paper": db.scalar(select(func.count(Paper.id))) or 0,
"template": db.scalar(select(func.count(Template.id))) or 0, "template": db.scalar(select(func.count(Template.id))) or 0,
"paper_sentence": db.scalar(select(func.count(PaperSentence.id))) or 0, "paper_sentence": db.scalar(select(func.count(PaperSentence.id))) or 0,
"template_field_library": db.scalar( "template_title": db.scalar(
select(func.count(TemplateFieldLibrary.id)) select(func.count(TemplateTitle.id))
) )
or 0, or 0,
} }
+1 -1
View File
@@ -4,7 +4,7 @@ These are tool-argument models, not domain models: they exist so the JSON
Schema a client receives is precise enough that the model gets the shape right Schema a client receives is precise enough that the model gets the shape right
the first time. Each one is converted into the project's own payload the first time. Each one is converted into the project's own payload
(:class:`~app.schemas.paper.SentenceInput`, (:class:`~app.schemas.paper.SentenceInput`,
:class:`~app.schemas.template.TemplateFieldInput`) before it reaches the CRUD :class:`~app.schemas.template.TemplateTitlePlacementInput`) before it reaches the CRUD
layer, so the validation rules stay in one place — a citation with a blank layer, so the validation rules stay in one place — a citation with a blank
quote is refused here for the same reason the REST API refuses it. quote is refused here for the same reason the REST API refuses it.
+9 -7
View File
@@ -51,7 +51,7 @@ from app.models import (
Paper, Paper,
PaperSentence, PaperSentence,
Template, Template,
TemplateFieldLibrary, TemplateTitle,
) )
from app.schemas.paper import ( from app.schemas.paper import (
CitationInput, CitationInput,
@@ -169,9 +169,9 @@ def template_or_fail(db: Session, template_id: int) -> Template:
return template return template
def field_or_fail(db: Session, field_id: int) -> TemplateFieldLibrary: def field_or_fail(db: Session, field_id: int) -> TemplateTitle:
"""Return one library field, or refuse with the id that was not found.""" """Return one library field, or refuse with the id that was not found."""
from app.crud import template_field_library as field_crud from app.crud import template_title as field_crud
field = field_crud.get(db, field_id) field = field_crud.get(db, field_id)
if field is None: if field is None:
@@ -359,14 +359,16 @@ def heading_index(paper: Paper) -> list[dict]:
return [] return []
seen: dict[int, dict] = {} seen: dict[int, dict] = {}
for placement in paper.template.items: for placement in paper.template.placements:
if placement.sort in seen: if placement.sort in seen:
continue continue
seen[placement.sort] = { seen[placement.sort] = {
"position": placement.sort, "position": placement.sort,
"heading": placement.field.name, "heading": placement.title.name,
"level": placement.field.level, "level": placement.title.level,
"field_id": placement.field_id, # Emitted as "field_id" because that is the name this interface
# uses for a library entry; the column behind it is title_id.
"field_id": placement.title_id,
} }
return [seen[position] for position in sorted(seen)] return [seen[position] for position in sorted(seen)]
+11 -11
View File
@@ -1,6 +1,6 @@
"""Field-library tools (字段库): the reusable headings templates are built from. """Field-library tools (字段库): the reusable headings templates are built from.
The library is the catalogue, and ``template_field`` is a placement in one The library is the catalogue, and ``template_title_placement`` is a placement in one
template — one word apart, opposite meanings. A field exists once and may be template — one word apart, opposite meanings. A field exists once and may be
placed by any number of templates, which is why editing a field restyles every placed by any number of templates, which is why editing a field restyles every
outline that uses it and why deleting one is refused while any template still outline that uses it and why deleting one is refused while any template still
@@ -20,13 +20,13 @@ from mcp.server.mcpserver import MCPServer
from pydantic import Field from pydantic import Field
from sqlalchemy.orm import Session from sqlalchemy.orm import Session
from app.crud import template_field_library as field_crud from app.crud import template_title as field_crud
from app.mcp import support as s from app.mcp import support as s
from app.mcp.tools.registry import mcp_tool from app.mcp.tools.registry import mcp_tool
from app.models import TemplateFieldLibrary from app.models import TemplateTitle
from app.schemas.template_field_library import ( from app.schemas.template_title import (
TemplateFieldLibraryCreate, TemplateTitleCreate,
TemplateFieldLibraryUpdate, TemplateTitleUpdate,
) )
@@ -45,7 +45,7 @@ def register(server: MCPServer) -> None:
"""列出字段库(模板能用的所有标题)。建模板前先查这里的 id。""" """列出字段库(模板能用的所有标题)。建模板前先查这里的 id。"""
page, page_size = s.page_args(page, page_size) page, page_size = s.page_args(page, page_size)
with s.session() as db: with s.session() as db:
rows, total = field_crud.list_fields( rows, total = field_crud.list_titles(
db, keyword=keyword, level=level, page=page, page_size=page_size db, keyword=keyword, level=level, page=page, page_size=page_size
) )
return s.dumps( return s.dumps(
@@ -87,7 +87,7 @@ def register(server: MCPServer) -> None:
] = "#000000", ] = "#000000",
) -> str: ) -> str:
"""往字段库加一个标题字段,可带字号颜色。""" """往字段库加一个标题字段,可带字号颜色。"""
payload = TemplateFieldLibraryCreate( payload = TemplateTitleCreate(
name=name, level=level, font_size=font_size, font_color=font_color name=name, level=level, font_size=font_size, font_color=font_color
) )
with s.session() as db: with s.session() as db:
@@ -117,7 +117,7 @@ def register(server: MCPServer) -> None:
if not values: if not values:
s.fail("没有给出任何要修改的内容") s.fail("没有给出任何要修改的内容")
payload = TemplateFieldLibraryUpdate(**values) payload = TemplateTitleUpdate(**values)
with s.session() as db: with s.session() as db:
field = s.field_or_fail(db, field_id) field = s.field_or_fail(db, field_id)
@@ -155,7 +155,7 @@ def register(server: MCPServer) -> None:
# --- helpers ----------------------------------------------------------------- # --- helpers -----------------------------------------------------------------
def _field_row(field: TemplateFieldLibrary) -> dict: def _field_row(field: TemplateTitle) -> dict:
"""One library entry as a model reads it.""" """One library entry as a model reads it."""
return { return {
"id": field.id, "id": field.id,
@@ -166,7 +166,7 @@ def _field_row(field: TemplateFieldLibrary) -> dict:
} }
def _assert_unused(db: Session, fields: list[TemplateFieldLibrary]) -> None: def _assert_unused(db: Session, fields: list[TemplateTitle]) -> None:
"""Refuse the delete while any template still places the field. """Refuse the delete while any template still places the field.
Dropping a field that is placed somewhere would silently remove a heading Dropping a field that is placed somewhere would silently remove a heading
+21 -17
View File
@@ -28,7 +28,7 @@ from app.mcp import support as s
from app.mcp.specs import FieldSpec from app.mcp.specs import FieldSpec
from app.mcp.tools.registry import mcp_tool from app.mcp.tools.registry import mcp_tool
from app.models import Template from app.models import Template
from app.schemas.template import TemplateCreate, TemplateFieldInput from app.schemas.template import TemplateCreate, TemplateTitlePlacementInput
#: Spacing between generated sorts. Ties are legal in a template and gaps are #: Spacing between generated sorts. Ties are legal in a template and gaps are
#: expected — the editor numbers a fresh selection 1..N only on request — so #: expected — the editor numbers a fresh selection 1..N only on request — so
@@ -99,16 +99,16 @@ def register(server: MCPServer) -> None:
) -> str: ) -> str:
"""新建模板:名称 + 说明 + 有序字段选择。用 field_list 先查字段 id。""" """新建模板:名称 + 说明 + 有序字段选择。用 field_list 先查字段 id。"""
selection = _selection(field_ids, fields) selection = _selection(field_ids, fields)
payload = TemplateCreate(name=name, abstract=abstract, fields=selection) payload = TemplateCreate(name=name, abstract=abstract, placements=selection)
with s.session() as db: with s.session() as db:
_assert_name_free(db, payload.name) _assert_name_free(db, payload.name)
_assert_fields_exist(db, payload.fields) _assert_titles_exist(db, payload.placements)
template = template_crud.create( template = template_crud.create(
db, db,
name=payload.name, name=payload.name,
abstract=payload.abstract, abstract=payload.abstract,
fields=payload.fields, placements=payload.placements,
) )
return s.dumps(_template_row(template)) return s.dumps(_template_row(template))
@@ -142,7 +142,7 @@ def register(server: MCPServer) -> None:
if name is not None: if name is not None:
_assert_name_free(db, name, exclude_id=template_id) _assert_name_free(db, name, exclude_id=template_id)
if selection is not None: if selection is not None:
_assert_fields_exist(db, selection) _assert_titles_exist(db, selection)
updated = template_crud.update( updated = template_crud.update(
db, db,
@@ -150,7 +150,7 @@ def register(server: MCPServer) -> None:
name=name, name=name,
abstract=abstract, abstract=abstract,
abstract_provided=clear_abstract or abstract is not None, abstract_provided=clear_abstract or abstract is not None,
fields=selection, placements=selection,
) )
return s.dumps(_template_row(updated)) return s.dumps(_template_row(updated))
@@ -177,16 +177,19 @@ def _template_row(template: Template) -> dict:
"id": template.id, "id": template.id,
"name": template.name, "name": template.name,
"abstract": template.abstract, "abstract": template.abstract,
# The keys here are this interface's own vocabulary ("fields",
# "field_id"): agents call these tools with those names, so they stay
# put while the storage layer below calls the same rows titles.
"fields": [ "fields": [
{ {
"position": item.sort, "position": item.sort,
"field_id": item.field_id, "field_id": item.title_id,
"name": item.field.name, "name": item.title.name,
"level": item.field.level, "level": item.title.level,
"font_size": float(item.field.font_size), "font_size": float(item.title.font_size),
"font_color": item.field.font_color, "font_color": item.title.font_color,
} }
for item in template.items for item in template.placements
], ],
} }
@@ -194,7 +197,7 @@ def _template_row(template: Template) -> dict:
def _selection( def _selection(
field_ids: list[int] | None, field_ids: list[int] | None,
fields: list[FieldSpec] | None, fields: list[FieldSpec] | None,
) -> list[TemplateFieldInput]: ) -> list[TemplateTitlePlacementInput]:
"""Turn either way of describing a selection into placement rows. """Turn either way of describing a selection into placement rows.
The order of ``field_ids`` is the outline order; the numbering is generated The order of ``field_ids`` is the outline order; the numbering is generated
@@ -203,11 +206,12 @@ def _selection(
""" """
if fields: if fields:
return [ return [
TemplateFieldInput(field_id=item.field_id, sort=item.sort) for item in fields TemplateTitlePlacementInput(title_id=item.field_id, sort=item.sort)
for item in fields
] ]
if field_ids: if field_ids:
return [ return [
TemplateFieldInput(field_id=field_id, sort=(index + 1) * SORT_STEP) TemplateTitlePlacementInput(title_id=field_id, sort=(index + 1) * SORT_STEP)
for index, field_id in enumerate(field_ids) for index, field_id in enumerate(field_ids)
] ]
return [] return []
@@ -218,13 +222,13 @@ def _assert_name_free(db: Session, name: str, *, exclude_id: int | None = None)
s.fail(f"模板名称“{name}”已存在") s.fail(f"模板名称“{name}”已存在")
def _assert_fields_exist(db: Session, fields: list[Any]) -> None: def _assert_titles_exist(db: Session, fields: list[Any]) -> None:
"""Reject a selection that points at fields the library does not have. """Reject a selection that points at fields the library does not have.
Checked in Python rather than by a foreign key, exactly as the REST route Checked in Python rather than by a foreign key, exactly as the REST route
does: TiDB parses but does not enforce ``FOREIGN KEY``. does: TiDB parses but does not enforce ``FOREIGN KEY``.
""" """
missing = template_crud.missing_field_ids(db, [item.field_id for item in fields]) missing = template_crud.missing_title_ids(db, [item.title_id for item in fields])
if missing: if missing:
joined = "、".join(str(field_id) for field_id in missing) joined = "、".join(str(field_id) for field_id in missing)
s.fail(f"字段不存在:{joined}(先用 field_list 查可用的字段 id)") s.fail(f"字段不存在:{joined}(先用 field_list 查可用的字段 id)")
+7 -7
View File
@@ -14,13 +14,13 @@ Every table is prefixed with the module it belongs to, and a class is named
after its table (``Template`` -> ``template``): after its table (``Template`` -> ``template``):
template the 模板 module template the 模板 module
template_field a field placed in a template, with its position template_title_placement a field placed in a template, with its position
template_field_library the 字段库 the template module draws on template_title the 字段库 the template module draws on
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
``template_field`` and ``template_field_library`` 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
here, ``sort`` included), the second is the *catalogue* it was picked from. here, ``sort`` included), the second is the *catalogue* it was picked from.
""" """
@@ -36,8 +36,8 @@ from app.models.paper import (
from app.models.paper_sentence import PaperSentence from app.models.paper_sentence import PaperSentence
from app.models.paper_sentence_reference import PaperSentenceReference from app.models.paper_sentence_reference import PaperSentenceReference
from app.models.template import Template from app.models.template import Template
from app.models.template_field import TemplateField from app.models.template_title_placement import TemplateTitlePlacement
from app.models.template_field_library import TemplateFieldLibrary from app.models.template_title import TemplateTitle
__all__ = [ __all__ = [
"PAPER_STATUSES", "PAPER_STATUSES",
@@ -48,7 +48,7 @@ __all__ = [
"PaperSentence", "PaperSentence",
"PaperSentenceReference", "PaperSentenceReference",
"Template", "Template",
"TemplateField", "TemplateTitlePlacement",
"TemplateFieldLibrary", "TemplateTitle",
"TimestampMixin", "TimestampMixin",
] ]
+1 -1
View File
@@ -9,7 +9,7 @@ A paper is a bag of metadata plus two things that are deliberately kept apart:
* its **content**, which lives in * its **content**, which lives in
:class:`~app.models.paper_sentence.PaperSentence` — one row per sentence, :class:`~app.models.paper_sentence.PaperSentence` — one row per sentence,
addressed by the paragraph's ``sort`` inside that template rather than by a addressed by the paragraph's ``sort`` inside that template rather than by a
foreign key to a ``template_field`` row. foreign key to a ``template_title_placement`` row.
That second choice is what makes the promised workflow work. Because a sentence That second choice is what makes the promised workflow work. Because a sentence
remembers "I belong at position 7", not "I belong to placement #42", swapping remembers "I belong at position 7", not "I belong to placement #42", swapping
+2 -2
View File
@@ -5,12 +5,12 @@ whole design:
``paper_template_filed_sort`` ``paper_template_filed_sort``
The ``sort`` of the template placement this sentence belongs to — *not* a The ``sort`` of the template placement this sentence belongs to — *not* a
foreign key to ``template_field``. It is deliberately the position rather 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 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 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 lands on whatever the new template puts at that position, with no per
sentence editing. (The name keeps the spelling the feature was specified sentence editing. (The name keeps the spelling the feature was specified
with; it reads ``template_field_sort``.) with; it reads ``template_title_placement_sort``.)
``sort`` ``sort``
Where this sentence sits *inside* that paragraph. A paragraph is reassembled Where this sentence sits *inside* that paragraph. A paragraph is reassembled
+8 -8
View File
@@ -1,10 +1,10 @@
"""Templates (模板表) — the outlines a paper can be written against. """Templates (模板表) — the outlines a paper can be written against.
A template is a named, ordered selection of library fields — the outline a A template is a named, ordered selection of library titles — the outline a
paper is written against. It stores no typography of its own: font size and paper is written against. It stores no typography of its own: font size and
colour are read from the referenced colour are read from the referenced
:class:`~app.models.template_field_library.TemplateFieldLibrary`, :class:`~app.models.template_title.TemplateTitle`,
so correcting a field's styling updates every template that uses it. so correcting a title's styling updates every template that uses it.
""" """
from typing import TYPE_CHECKING from typing import TYPE_CHECKING
@@ -16,11 +16,11 @@ from app.db.base import Base
from app.models.mixins import TimestampMixin 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.template_field import TemplateField from app.models.template_title_placement import TemplateTitlePlacement
class Template(TimestampMixin, Base): class Template(TimestampMixin, Base):
"""A named outline: a template name, a summary, and its ordered fields.""" """A named outline: a template name, a summary, and its ordered titles."""
__tablename__ = "template" __tablename__ = "template"
@@ -31,15 +31,15 @@ class Template(TimestampMixin, Base):
#: Free-text abstract (摘要) describing when to use this template. #: Free-text abstract (摘要) describing when to use this template.
abstract: Mapped[str | None] = mapped_column(Text, nullable=True) abstract: Mapped[str | None] = mapped_column(Text, nullable=True)
#: The template's fields, always handed to callers in display order. #: The template's placements, always handed to callers in display order.
#: #:
#: ``delete-orphan`` is doing real work here: TiDB parses but does not #: ``delete-orphan`` is doing real work here: TiDB parses but does not
#: enforce ``ON DELETE CASCADE``, so removing a template's rows in the join #: enforce ``ON DELETE CASCADE``, so removing a template's rows in the join
#: table is the ORM's job, not the database's. #: table is the ORM's job, not the database's.
items: Mapped[list["TemplateField"]] = relationship( placements: Mapped[list["TemplateTitlePlacement"]] = relationship(
back_populates="template", back_populates="template",
cascade="all, delete-orphan", cascade="all, delete-orphan",
order_by="TemplateField.sort, TemplateField.id", order_by="TemplateTitlePlacement.sort, TemplateTitlePlacement.id",
lazy="selectin", lazy="selectin",
) )
@@ -9,7 +9,7 @@ Why there is no ``parent_id``
A tree would make a field usable under exactly one parent, so a level-2 heading A tree would make a field usable under exactly one parent, so a level-2 heading
such as "Background" could not sit under both "1. Introduction" and such as "Background" could not sit under both "1. Introduction" and
"2. Related Work". Hierarchy is therefore expressed only by "2. Related Work". Hierarchy is therefore expressed only by
:attr:`TemplateFieldLibrary.level` (1, 2, 3 ...), which is a *rendering hint* — it :attr:`TemplateTitle.level` (1, 2, 3 ...), which is a *rendering hint* — it
drives indentation and numbering semantics in the UI — while a field stays drives indentation and numbering semantics in the UI — while a field stays
free to be attached to any number of templates and any number of parents free to be attached to any number of templates and any number of parents
within them. within them.
@@ -18,10 +18,10 @@ The number that the reader sees is part of :attr:`name` and is written by the
user ("1. Introduction", "0 Abstract"). Nothing derives or rewrites it. user ("1. Introduction", "0 Abstract"). Nothing derives or rewrites it.
Ordering inside a template is *not* stored here: it lives in Ordering inside a template is *not* stored here: it lives in
``template_field.sort``. This table has no ``sort`` column on purpose, so that ``template_title_placement.sort``. This table has no ``sort`` column on purpose, so that
one library field can occupy a different position in every template. one library field can occupy a different position in every template.
Naming: the table is ``template_field_library`` and one row is one entry of it Naming: the table is ``template_title`` and one row is one entry of it
— the class is named after the table, as everywhere else in this package. The — the class is named after the table, as everywhere else in this package. The
library is global, but it belongs to the 模板 module: it is the raw material a library is global, but it belongs to the 模板 module: it is the raw material a
template is built from, and it is managed from the same menu. template is built from, and it is managed from the same menu.
@@ -36,10 +36,10 @@ from app.db.base import Base
from app.models.mixins import TimestampMixin from app.models.mixins import TimestampMixin
class TemplateFieldLibrary(TimestampMixin, Base): class TemplateTitle(TimestampMixin, Base):
"""A single reusable heading, with the typography it should render in.""" """A single reusable heading, with the typography it should render in."""
__tablename__ = "template_field_library" __tablename__ = "template_title"
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True) id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
@@ -77,6 +77,6 @@ class TemplateFieldLibrary(TimestampMixin, Base):
def __repr__(self) -> str: # pragma: no cover - debugging aid def __repr__(self) -> str: # pragma: no cover - debugging aid
return ( return (
f"<TemplateFieldLibrary id={self.id} name={self.name!r} " f"<TemplateTitle id={self.id} name={self.name!r} "
f"level={self.level} color={self.font_color}>" f"level={self.level} color={self.font_color}>"
) )
@@ -26,19 +26,19 @@ from app.db.base import Base
if TYPE_CHECKING: # pragma: no cover - typing only if TYPE_CHECKING: # pragma: no cover - typing only
from app.models.template import Template from app.models.template import Template
from app.models.template_field_library import TemplateFieldLibrary from app.models.template_title import TemplateTitle
class TemplateField(Base): class TemplateTitlePlacement(Base):
"""One placement of one library field inside one template.""" """One placement of one library title inside one template."""
__tablename__ = "template_field" __tablename__ = "template_title_placement"
__table_args__ = ( __table_args__ = (
# Every read is "the fields of template X, in order", so the index # Every read is "the placements of template X, in order", so the index
# covers both the filter and the sort. # covers both the filter and the sort.
Index("ix_template_field_template_sort", "template_id", "sort"), Index("ix_template_title_placement_template_sort", "template_id", "sort"),
Index("ix_template_field_field_id", "field_id"), Index("ix_template_title_placement_title_id", "title_id"),
) )
id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True) id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
@@ -48,26 +48,26 @@ class TemplateField(Base):
nullable=False, nullable=False,
) )
#: ``RESTRICT``: a field still placed in a template must not vanish from #: ``RESTRICT``: a title still placed in a template must not vanish from
#: under it. The API enforces this in Python as well, since TiDB does not #: under it. The API checks this in Python too, so a refusal names the row
#: enforce foreign keys itself. #: rather than surfacing a driver error.
field_id: Mapped[int] = mapped_column( title_id: Mapped[int] = mapped_column(
ForeignKey("template_field_library.id", ondelete="RESTRICT"), ForeignKey("template_title.id", ondelete="RESTRICT"),
nullable=False, nullable=False,
) )
#: Display position within the template. Plain ascending integer — lower #: Display position within the template. Plain ascending integer — lower
#: sorts render first regardless of the field's ``level``. #: sorts render first regardless of the title's ``level``.
sort: Mapped[int] = mapped_column(Integer, nullable=False, default=0) sort: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
template: Mapped["Template"] = relationship(back_populates="items") template: Mapped["Template"] = relationship(back_populates="placements")
#: Eager-loaded because every template read needs the field's name and #: Eager-loaded because every template read needs the title's name and
#: typography; lazy loading would emit one query per row. #: typography; lazy loading would emit one query per row.
field: Mapped["TemplateFieldLibrary"] = relationship(lazy="joined") title: Mapped["TemplateTitle"] = relationship(lazy="joined")
def __repr__(self) -> str: # pragma: no cover - debugging aid def __repr__(self) -> str: # pragma: no cover - debugging aid
return ( return (
f"<TemplateField template_id={self.template_id} " f"<TemplateTitlePlacement template_id={self.template_id} "
f"field_id={self.field_id} sort={self.sort}>" f"title_id={self.title_id} sort={self.sort}>"
) )
+13 -13
View File
@@ -28,14 +28,14 @@ from app.schemas.template import (
TemplateListItem, TemplateListItem,
TemplateRead, TemplateRead,
TemplateUpdate, TemplateUpdate,
TemplateFieldInput, TemplateTitlePlacementInput,
TemplateFieldRead, TemplateTitlePlacementRead,
) )
from app.schemas.template_field_library import ( from app.schemas.template_title import (
TemplateFieldLibraryCreate, TemplateTitleCreate,
TemplateFieldLibraryRead, TemplateTitleRead,
TemplateFieldLibraryRef, TemplateTitleRef,
TemplateFieldLibraryUpdate, TemplateTitleUpdate,
) )
__all__ = [ __all__ = [
@@ -61,11 +61,11 @@ __all__ = [
"TemplateListItem", "TemplateListItem",
"TemplateRead", "TemplateRead",
"TemplateUpdate", "TemplateUpdate",
"TemplateFieldLibraryCreate", "TemplateTitleCreate",
"TemplateFieldLibraryRead", "TemplateTitleRead",
"TemplateFieldLibraryRef", "TemplateTitleRef",
"TemplateFieldLibraryUpdate", "TemplateTitleUpdate",
"TemplateFieldInput", "TemplateTitlePlacementInput",
"TemplateFieldRead", "TemplateTitlePlacementRead",
"normalize_hex_color", "normalize_hex_color",
] ]
+3 -3
View File
@@ -186,9 +186,9 @@ class ParagraphRead(BaseModel):
""" """
paper_template_filed_sort: int paper_template_filed_sort: int
#: The placement this paragraph resolved to, when there was one. #: The placement row this paragraph resolved to, when there was one.
template_field_id: int | None = None placement_id: int | None = None
field_id: int | None = None title_id: int | None = None
#: Heading text as written in the template — the numbering is part of it. #: Heading text as written in the template — the numbering is part of it.
name: str | None = None name: str | None = None
level: int = 1 level: int = 1
+26 -23
View File
@@ -6,34 +6,34 @@ from decimal import Decimal
from pydantic import BaseModel, ConfigDict, Field from pydantic import BaseModel, ConfigDict, Field
from app.models.template import Template from app.models.template import Template
from app.models.template_field import TemplateField from app.models.template_title_placement import TemplateTitlePlacement
from app.schemas.common import TypographyMixin from app.schemas.common import TypographyMixin
class TemplateFieldInput(BaseModel): class TemplateTitlePlacementInput(BaseModel):
"""One placement of a library field inside a template. """One placement of a library title inside a template.
The client sends the whole ordered selection on create and on update; the The client sends the whole ordered selection on create and on update; the
server replaces the stored rows with it. ``sort`` is a plain ascending server replaces the stored rows with it. ``sort`` is a plain ascending
integer and is the *only* thing that decides render order. integer and is the *only* thing that decides render order.
""" """
field_id: int title_id: int
sort: int = Field(default=0, ge=-1_000_000, le=1_000_000) sort: int = Field(default=0, ge=-1_000_000, le=1_000_000)
class TemplateFieldRead(TypographyMixin, BaseModel): class TemplateTitlePlacementRead(TypographyMixin, BaseModel):
"""A template's field, flattened with the library row it points at. """A template's placement, flattened with the library row it points at.
Persistence keeps the two apart — a placement row plus the library row it Persistence keeps the two apart — a placement row plus the library row it
references — but a client rendering an outline wants one flat record, so references — but a client rendering an outline wants one flat record, so
the typography is denormalised into the response. That is also what keeps the typography is denormalised into the response. That is also what keeps
the outline in sync: there is only ever one copy of a field's name and the outline in sync: there is only ever one copy of a title's name and
styling, in the library. styling, in the library.
""" """
id: int id: int
field_id: int title_id: int
sort: int sort: int
name: str name: str
level: int level: int
@@ -41,16 +41,16 @@ class TemplateFieldRead(TypographyMixin, BaseModel):
font_color: str font_color: str
@classmethod @classmethod
def from_model(cls, item: TemplateField) -> "TemplateFieldRead": def from_model(cls, item: TemplateTitlePlacement) -> "TemplateTitlePlacementRead":
"""Flatten a placement row and its library row into one record.""" """Flatten a placement row and its library row into one record."""
return cls( return cls(
id=item.id, id=item.id,
field_id=item.field_id, title_id=item.title_id,
sort=item.sort, sort=item.sort,
name=item.field.name, name=item.title.name,
level=item.field.level, level=item.title.level,
font_size=item.field.font_size, font_size=item.title.font_size,
font_color=item.field.font_color, font_color=item.title.font_color,
) )
@@ -64,34 +64,34 @@ class TemplateBase(BaseModel):
class TemplateCreate(TemplateBase): class TemplateCreate(TemplateBase):
"""Payload for ``POST /templates``. """Payload for ``POST /templates``.
The field selection is free: any subset, any order, repeats allowed. The The selection is free: any subset, any order, repeats allowed. The server
server stores it as given and orders it by ``sort`` on read. stores it as given and orders it by ``sort`` on read.
""" """
fields: list[TemplateFieldInput] = Field(default_factory=list) placements: list[TemplateTitlePlacementInput] = Field(default_factory=list)
class TemplateUpdate(BaseModel): class TemplateUpdate(BaseModel):
"""Payload for ``PATCH /templates/{id}``. """Payload for ``PATCH /templates/{id}``.
``fields`` is a full replacement when present — omit it to leave the ``placements`` is a full replacement when present — omit it to leave the
selection untouched. selection untouched.
""" """
name: str | None = Field(default=None, min_length=1, max_length=255) name: str | None = Field(default=None, min_length=1, max_length=255)
abstract: str | None = None abstract: str | None = None
fields: list[TemplateFieldInput] | None = None placements: list[TemplateTitlePlacementInput] | None = None
class TemplateListItem(BaseModel): class TemplateListItem(BaseModel):
"""A template as it appears in the list table — no field rows.""" """A template as it appears in the list table — no placement rows."""
model_config = ConfigDict(from_attributes=True) model_config = ConfigDict(from_attributes=True)
id: int id: int
name: str name: str
abstract: str | None abstract: str | None
field_count: int placement_count: int
created_at: datetime created_at: datetime
updated_at: datetime updated_at: datetime
@@ -106,7 +106,7 @@ class TemplateRead(BaseModel):
abstract: str | None abstract: str | None
#: The outline, ordered by ``sort`` — the ORM relationship sets that #: The outline, ordered by ``sort`` — the ORM relationship sets that
#: ordering, so this list is display-ready with no client-side sorting. #: ordering, so this list is display-ready with no client-side sorting.
fields: list[TemplateFieldRead] placements: list[TemplateTitlePlacementRead]
created_at: datetime created_at: datetime
updated_at: datetime updated_at: datetime
@@ -117,7 +117,10 @@ class TemplateRead(BaseModel):
id=template.id, id=template.id,
name=template.name, name=template.name,
abstract=template.abstract, abstract=template.abstract,
fields=[TemplateFieldRead.from_model(item) for item in template.items], placements=[
TemplateTitlePlacementRead.from_model(item)
for item in template.placements
],
created_at=template.created_at, created_at=template.created_at,
updated_at=template.updated_at, updated_at=template.updated_at,
) )
@@ -8,7 +8,7 @@ from pydantic import BaseModel, ConfigDict, Field
from app.schemas.common import TypographyMixin from app.schemas.common import TypographyMixin
class TemplateFieldLibraryBase(TypographyMixin, BaseModel): class TemplateTitleBase(TypographyMixin, BaseModel):
"""Fields a client may set on a library entry.""" """Fields a client may set on a library entry."""
#: Display name, numbering included — e.g. ``"1. Introduction"``. Stored #: Display name, numbering included — e.g. ``"1. Introduction"``. Stored
@@ -25,12 +25,12 @@ class TemplateFieldLibraryBase(TypographyMixin, BaseModel):
font_color: str = Field(default="#000000", max_length=32) font_color: str = Field(default="#000000", max_length=32)
class TemplateFieldLibraryCreate(TemplateFieldLibraryBase): class TemplateTitleCreate(TemplateTitleBase):
"""Payload for ``POST /template-field-library``.""" """Payload for ``POST /template-titles``."""
class TemplateFieldLibraryUpdate(TypographyMixin, BaseModel): class TemplateTitleUpdate(TypographyMixin, BaseModel):
"""Payload for ``PATCH /template-field-library/{id}`` — every part optional. """Payload for ``PATCH /template-titles/{id}`` — every part optional.
The colour normaliser tolerates ``None`` here; the validator returns The colour normaliser tolerates ``None`` here; the validator returns
non-strings untouched, so an omitted colour stays omitted. non-strings untouched, so an omitted colour stays omitted.
@@ -42,7 +42,7 @@ class TemplateFieldLibraryUpdate(TypographyMixin, BaseModel):
font_color: str | None = Field(default=None, max_length=32) font_color: str | None = Field(default=None, max_length=32)
class TemplateFieldLibraryRead(TemplateFieldLibraryBase): class TemplateTitleRead(TemplateTitleBase):
"""A stored library entry.""" """A stored library entry."""
model_config = ConfigDict(from_attributes=True) model_config = ConfigDict(from_attributes=True)
@@ -52,7 +52,7 @@ class TemplateFieldLibraryRead(TemplateFieldLibraryBase):
updated_at: datetime updated_at: datetime
class TemplateFieldLibraryRef(BaseModel): class TemplateTitleRef(BaseModel):
"""How many templates currently place a field — used to explain a refusal.""" """How many templates currently place a field — used to explain a refusal."""
field_id: int field_id: int
+30 -30
View File
@@ -1,6 +1,6 @@
"""Seed the template-field library and a couple of starter templates. """Seed the template-title library and a couple of starter templates.
Idempotent: fields are matched by name and templates by name, so running it Idempotent: titles are matched by name and templates by name, so running it
twice adds nothing. ``--reset`` empties the three tables first, which is the twice adds nothing. ``--reset`` empties the three tables first, which is the
way to get back to the seeded baseline after experimenting. way to get back to the seeded baseline after experimenting.
@@ -27,9 +27,9 @@ from sqlalchemy import delete, select # noqa: E402
from sqlalchemy.orm import Session # noqa: E402 from sqlalchemy.orm import Session # noqa: E402
from app.db.session import SessionLocal # noqa: E402 from app.db.session import SessionLocal # noqa: E402
from app.models import Template, TemplateFieldLibrary, TemplateField # noqa: E402 from app.models import Template, TemplateTitle, TemplateTitlePlacement # noqa: E402
# --- the field library ------------------------------------------------------- # --- the title library -------------------------------------------------------
# #
# (name, level, font_size, font_color) # (name, level, font_size, font_color)
# #
@@ -45,7 +45,7 @@ HEADING = "#1F1F1F"
SUB = "#404040" SUB = "#404040"
GREY = "#595959" GREY = "#595959"
FIELDS: list[tuple[str, int, Decimal, str]] = [ TITLES: list[tuple[str, int, Decimal, str]] = [
("0 Abstract", 1, Decimal("10.5"), GREY), ("0 Abstract", 1, Decimal("10.5"), GREY),
("1 Introduction", 1, Decimal("12.0"), HEADING), ("1 Introduction", 1, Decimal("12.0"), HEADING),
("1.1 Research Background", 2, Decimal("10.5"), SUB), ("1.1 Research Background", 2, Decimal("10.5"), SUB),
@@ -70,15 +70,15 @@ FIELDS: list[tuple[str, int, Decimal, str]] = [
# --- starter templates ------------------------------------------------------- # --- starter templates -------------------------------------------------------
# #
# Each entry is (template name, abstract, [field names in display order]). # Each entry is (template name, abstract, [title names in display order]).
# `sort` is assigned from the list position (1, 2, 3 ...), which is exactly # `sort` is assigned from the list position (1, 2, 3 ...), which is exactly
# what the UI does when the user picks fields and orders them. # what the UI does when the user picks titles and orders them.
TEMPLATES: list[tuple[str, str, list[str]]] = [ TEMPLATES: list[tuple[str, str, list[str]]] = [
( (
"标准学术论文(通用)", "标准学术论文(通用)",
"完整的通用学术论文骨架,含摘要、引言、相关工作、方法、实验、讨论与结论。" "完整的通用学术论文骨架,含摘要、引言、相关工作、方法、实验、讨论与结论。"
"适合期刊或会议长文;先按此模板把结构填满,再按目标期刊微调字段。", "适合期刊或会议长文;先按此模板把结构填满,再按目标期刊微调字段。",
[name for name, *_ in FIELDS], [name for name, *_ in TITLES],
), ),
( (
"四段式短文", "四段式短文",
@@ -117,57 +117,57 @@ TEMPLATES: list[tuple[str, str, list[str]]] = [
def reset(db: Session) -> None: def reset(db: Session) -> None:
"""Empty the three tables in dependency order.""" """Empty the three tables in dependency order."""
db.execute(delete(TemplateField)) db.execute(delete(TemplateTitlePlacement))
db.execute(delete(Template)) db.execute(delete(Template))
db.execute(delete(TemplateFieldLibrary)) db.execute(delete(TemplateTitle))
db.commit() db.commit()
def seed_fields(db: Session) -> dict[str, TemplateFieldLibrary]: def seed_titles(db: Session) -> dict[str, TemplateTitle]:
"""Insert any missing library fields and return name -> field.""" """Insert any missing library titles and return name -> title."""
existing = {field.name: field for field in db.scalars(select(TemplateFieldLibrary)).all()} existing = {title.name: title for title in db.scalars(select(TemplateTitle)).all()}
created = 0 created = 0
for name, level, font_size, font_color in FIELDS: for name, level, font_size, font_color in TITLES:
if name in existing: if name in existing:
continue continue
field = TemplateFieldLibrary( title = TemplateTitle(
name=name, level=level, font_size=font_size, font_color=font_color name=name, level=level, font_size=font_size, font_color=font_color
) )
db.add(field) db.add(title)
existing[name] = field existing[name] = title
created += 1 created += 1
db.commit() db.commit()
for field in existing.values(): for title in existing.values():
db.refresh(field) db.refresh(title)
print( print(
f" template_field_library : {created} created, " f" template_title : {created} created, "
f"{len(existing) - created} already present" f"{len(existing) - created} already present"
) )
return existing return existing
def seed_templates(db: Session, fields: dict[str, TemplateFieldLibrary]) -> None: def seed_templates(db: Session, titles: dict[str, TemplateTitle]) -> None:
"""Insert any missing starter templates.""" """Insert any missing starter templates."""
existing = {name for name in db.scalars(select(Template.name)).all()} existing = {name for name in db.scalars(select(Template.name)).all()}
created = 0 created = 0
for name, abstract, field_names in TEMPLATES: for name, abstract, title_names in TEMPLATES:
if name in existing: if name in existing:
continue continue
missing = [field_name for field_name in field_names if field_name not in fields] missing = [title_name for title_name in title_names if title_name not in titles]
if missing: if missing:
raise SystemExit(f"template {name!r} references unknown fields: {missing}") raise SystemExit(f"template {name!r} references unknown titles: {missing}")
template = Template(name=name, abstract=abstract) template = Template(name=name, abstract=abstract)
# sort is the list position: 1-based, ascending, with gaps allowed # sort is the list position: 1-based, ascending, with gaps allowed
# because the UI lets the user type any integer. # because the UI lets the user type any integer.
template.items = [ template.placements = [
TemplateField(field_id=fields[field_name].id, sort=index) TemplateTitlePlacement(title_id=titles[title_name].id, sort=index)
for index, field_name in enumerate(field_names, start=1) for index, title_name in enumerate(title_names, start=1)
] ]
db.add(template) db.add(template)
created += 1 created += 1
@@ -181,7 +181,7 @@ def main() -> None:
parser.add_argument( parser.add_argument(
"--reset", "--reset",
action="store_true", action="store_true",
help="delete all fields and templates before seeding", help="delete all titles and templates before seeding",
) )
args = parser.parse_args() args = parser.parse_args()
@@ -190,8 +190,8 @@ def main() -> None:
reset(db) reset(db)
print(" reset : all rows deleted") print(" reset : all rows deleted")
fields = seed_fields(db) titles = seed_titles(db)
seed_templates(db, fields) seed_templates(db, titles)
print("seed complete") print("seed complete")
+6 -5
View File
@@ -98,14 +98,15 @@ async def expect_error(session: ClientSession, tool: str, **arguments: Any) -> s
def pick_template() -> tuple[int, list[dict[str, Any]]]: def pick_template() -> tuple[int, list[dict[str, Any]]]:
"""The template with the most fields, and its outline as the tools see it.""" """The template with the most titles, and its outline as the tools see it."""
with SessionLocal() as db: with SessionLocal() as db:
template = db.scalars( template = db.scalars(
select(Template).order_by(Template.id.asc()) select(Template).order_by(Template.id.asc())
).all() ).all()
best = max(template, key=lambda item: len(item.items)) best = max(template, key=lambda item: len(item.placements))
return best.id, [ return best.id, [
{"position": item.sort, "name": item.field.name} for item in best.items {"position": item.sort, "name": item.title.name}
for item in best.placements
] ]
@@ -437,11 +438,11 @@ async def run(url: str | None = None, token: str | None = None) -> int:
def _field_id(name: str) -> int: def _field_id(name: str) -> int:
"""The library field behind a heading name, for the template-create step.""" """The library field behind a heading name, for the template-create step."""
from app.models import TemplateFieldLibrary from app.models import TemplateTitle
with SessionLocal() as db: with SessionLocal() as db:
row = db.scalars( row = db.scalars(
select(TemplateFieldLibrary).where(TemplateFieldLibrary.name == name) select(TemplateTitle).where(TemplateTitle.name == name)
).first() ).first()
if row is None: if row is None:
raise AssertionError(f"field {name!r} not in the library") raise AssertionError(f"field {name!r} not in the library")
+12 -7
View File
@@ -73,11 +73,11 @@ def main() -> int:
print("1. pick two templates with different paragraph positions") print("1. pick two templates with different paragraph positions")
templates = call("GET", "/templates?page_size=50")["items"] templates = call("GET", "/templates?page_size=50")["items"]
check("templates exist", len(templates) >= 2, f"got {len(templates)}") check("templates exist", len(templates) >= 2, f"got {len(templates)}")
wide = max(templates, key=lambda item: item["field_count"]) wide = max(templates, key=lambda item: item["placement_count"])
narrow = min(templates, key=lambda item: item["field_count"]) narrow = min(templates, key=lambda item: item["placement_count"])
wide_full = call("GET", f"/templates/{wide['id']}") wide_full = call("GET", f"/templates/{wide['id']}")
narrow_full = call("GET", f"/templates/{narrow['id']}") narrow_full = call("GET", f"/templates/{narrow['id']}")
print(f" wide={wide['name']} ({wide['field_count']}), narrow={narrow['name']}") print(f" wide={wide['name']} ({wide['placement_count']}), narrow={narrow['name']}")
print("2. create a paper") print("2. create a paper")
paper = call( paper = call(
@@ -97,7 +97,8 @@ def main() -> int:
check("keywords normalised", paper["keywords"] == "关键词A, 关键词B", paper["keywords"]) check("keywords normalised", paper["keywords"] == "关键词A, 关键词B", paper["keywords"])
check( check(
"paragraph denominator counts the template", "paragraph denominator counts the template",
paper["template_paragraph_count"] == len({f["sort"] for f in wide_full["fields"]}), paper["template_paragraph_count"]
== len({p["sort"] for p in wide_full["placements"]}),
str(paper["template_paragraph_count"]), str(paper["template_paragraph_count"]),
) )
check("no sentences yet", paper["sentence_count"] == 0) check("no sentences yet", paper["sentence_count"] == 0)
@@ -106,7 +107,7 @@ def main() -> int:
document = call("GET", f"/papers/{paper['id']}/document") document = call("GET", f"/papers/{paper['id']}/document")
check( check(
"every template position is a paragraph", "every template position is a paragraph",
len(document["paragraphs"]) == len({f["sort"] for f in wide_full["fields"]}), len(document["paragraphs"]) == len({p["sort"] for p in wide_full["placements"]}),
str(len(document["paragraphs"])), str(len(document["paragraphs"])),
) )
check("all paragraphs empty", all(not p["sentences"] for p in document["paragraphs"])) check("all paragraphs empty", all(not p["sentences"] for p in document["paragraphs"]))
@@ -238,7 +239,11 @@ def main() -> int:
# A position neither template defines, so the check means the same # A position neither template defines, so the check means the same
# thing before and after the switch below. # thing before and after the switch below.
orphan_sort = ( orphan_sort = (
max(f["sort"] for f in wide_full["fields"] + narrow_full["fields"]) + 5 max(
p["sort"]
for p in wide_full["placements"] + narrow_full["placements"]
)
+ 5
) )
call( call(
"POST", "POST",
@@ -266,7 +271,7 @@ def main() -> int:
unmatched = [p for p in document["paragraphs"] if not p["matched"]] unmatched = [p for p in document["paragraphs"] if not p["matched"]]
check( check(
"structure follows the new template", "structure follows the new template",
len(matched) == len({f["sort"] for f in narrow_full["fields"]}), len(matched) == len({p["sort"] for p in narrow_full["placements"]}),
str(len(matched)), str(len(matched)),
) )
check("unmatched positions kept", len(unmatched) >= 1, str(len(unmatched))) check("unmatched positions kept", len(unmatched) >= 1, str(len(unmatched)))
+61 -37
View File
@@ -62,15 +62,15 @@ Six tables. Every one is prefixed with the module it belongs to, and a model
class is named after its table, so the schema can be read as three groups: class is named after its table, so the schema can be read as three groups:
``` ```
template_field_library the 字段库: reusable headings template_title one reusable heading (字段库)
id, name, level, font_size, font_color id, name, level, font_size, font_color
template a named outline (模板) template a named outline (模板)
id, name, abstract id, name, abstract
template_field a field placed in a template — and the only template_title_placement that heading placed in a template — and the
id, template_id → template, home of display order id, template_id → template, only home of display order
field_id → template_field_library, sort title_id → template_title, sort
paper the document paper the document
id, title, template_id, author, status, keywords, target_journal id, title, template_id, author, status, keywords, target_journal
@@ -82,6 +82,29 @@ paper_sentence_reference the citations of one sentence
id, sentence_id → paper_sentence, reference_id, quote, sort id, sentence_id → paper_sentence, reference_id, quote, sort
``` ```
### How the tables are named
Three rules, applied everywhere:
1. **A table is its module's name plus what it holds** — `template*` belongs to
the 模板 module, `paper*` to the 论文 module.
2. **A class is named after its table** (`TemplateTitle` → `template_title`), so
reading a class name tells you which table to look at.
3. **One concept, one word.** The library entry, the placement and the paper's
paragraph are three different things and never share a name.
The join table is a *placement* rather than a `_link` because it is not a bare
link: it carries `sort`, the only place display order is stored, and it
deliberately allows the same title twice in one template. Calling it a link
would describe two foreign keys and hide the column the whole ordering rule
rests on.
`template_title` and `template_title_placement` are one word apart on purpose —
the first is the catalogue, the second is one use of it — and the earlier pair
(`template_field_library` / `template_field`) hid that distinction behind a
prefix that meant the opposite kind of thing. Revision `b19e4d7a3c58` renamed
them.
`paper` has no `abstract` column, and that is a decision rather than an `paper` has no `abstract` column, and that is a decision rather than an
omission. A paper's abstract *is* a paragraph of its body — the template's omission. A paper's abstract *is* a paragraph of its body — the template's
`0 Abstract` field — so it has a position in the document, the heading and `0 Abstract` field — so it has a position in the document, the heading and
@@ -92,38 +115,39 @@ and the one in the column could drift from the one in the body. Revision
`a83f5c21d7b6` removed it, moving each stored abstract into the abstract `a83f5c21d7b6` removed it, moving each stored abstract into the abstract
paragraph first. paragraph first.
`template_field` and `template_field_library` are one word apart and mean The two template tables are one word apart and mean different things, which is
opposite things. The first is a *placement* — this template puts this field what the names are for: `template_title_placement` is a *placement* — this
here, `sort` included. The second is the *catalogue* the field was picked from, template puts this title here, `sort` included — while `template_title` is the
shared by every template and owned by none. The library is managed from the *catalogue* the title was picked from, shared by every template and owned by
模板 menu, because it is the raw material a template is built out of. none. The library is managed from the 模板 menu, because it is the raw material
a template is built out of.
### The field library is flat, not a tree ### The title library is flat, not a tree
`template_field_library` has no `parent_id`. Hierarchy is expressed only by `level` `template_title` has no `parent_id`. Hierarchy is expressed only by `level`
(1 for `1.`, 2 for `1.1`), which is a *rendering hint*: it drives indentation (1 for `1.`, 2 for `1.1`), which is a *rendering hint*: it drives indentation
and numbering semantics in the UI and nothing else. and numbering semantics in the UI and nothing else.
The reason is reuse. With a parent pointer a level-2 heading would belong to The reason is reuse. With a parent pointer a level-2 heading would belong to
exactly one level-1 heading, so "Background" could not sit under both exactly one level-1 heading, so "Background" could not sit under both
`1. Introduction` and `2. Related Work`. Flat fields are attached to templates, `1. Introduction` and `2. Related Work`. Titles are attached to templates,
not to each other, so one field can appear in any number of templates, in a not to each other, so one title can appear in any number of templates, in a
different position in each. different position in each.
The numbering a reader sees is part of `name` and is written by the user The numbering a reader sees is part of `name` and is written by the user
(`"1. Introduction"`, `"0 Abstract"`). Nothing derives or rewrites it. (`"1. Introduction"`, `"0 Abstract"`). Nothing derives or rewrites it.
### Display order lives in the join table ### Display order lives in the placement table
`template_field.sort` is a plain ascending integer and is the **only** thing `template_title_placement.sort` is a plain ascending integer and is the **only**
that decides what order a template's fields appear in. The order the user thing that decides what order a template's titles appear in. The order the user
clicked fields in is never stored, so selecting `字段1, 字段2.1, 字段2, 字段1.1` clicked titles in is never stored, so selecting `标题1, 标题2.1, 标题2, 标题1.1`
and setting sorts `1, 4, 3, 2` renders as `字段1, 字段1.1, 字段2, 字段2.1`. and setting sorts `1, 4, 3, 2` renders as `标题1, 标题1.1, 标题2, 标题2.1`.
Two consequences are deliberate: Two consequences are deliberate:
- **There is no unique constraint on `(template_id, field_id)`.** Placing the - **There is no unique constraint on `(template_id, title_id)`.** Placing the
same field twice in one template is a legitimate layout — the same level-2 same title twice in one template is a legitimate layout — the same level-2
heading under two different level-1 headings. The UI warns about a repeat; it heading under two different level-1 headings. The UI warns about a repeat; it
does not forbid one. does not forbid one.
- **Ties are legal.** Equal `sort` values are broken by insertion order, so the - **Ties are legal.** Equal `sort` values are broken by insertion order, so the
@@ -132,16 +156,16 @@ Two consequences are deliberate:
### Templates hold references, not copies ### Templates hold references, not copies
`template_field` points at a library field; it does not snapshot its name or `template_title_placement` points at a library title; it does not snapshot its
typography. Renaming or restyling a field therefore updates every template that name or typography. Renaming or restyling a title therefore updates every
places it, which is what makes "fix the template and the section names follow" template that places it, which is what makes "fix the template and the section
work. names follow" work.
### A sentence is addressed by position, not by field id ### A sentence is addressed by position, not by field id
`paper_sentence.paper_template_filed_sort` holds the `sort` of the template `paper_sentence.paper_template_filed_sort` holds the `sort` of the template
placement the sentence belongs to — **not** `template_field.id`, and not placement the sentence belongs to — **not** `template_title_placement.id`, and not
`template_field_library.id`. Together with `sort`, the sentence's own position inside `template_title.id`. Together with `sort`, the sentence's own position inside
that paragraph, it is everything needed to place a line of text. that paragraph, it is everything needed to place a line of text.
The indirection is the feature. Two templates have no rows in common, but they The indirection is the feature. Two templates have no rows in common, but they
@@ -160,12 +184,12 @@ Three behaviours fall out of that one choice:
still rendered, in their place in the order, under the heading 未设定. Switch still rendered, in their place in the order, under the heading 未设定. Switch
back and the old headings return, because the sentences never moved. back and the old headings return, because the sentences never moved.
- **Ties and gaps are fine.** Sentences may share a `sort` (broken by `id`) and - **Ties and gaps are fine.** Sentences may share a `sort` (broken by `id`) and
may be numbered `10, 20, 30` to leave room, exactly as `template_field.sort` may be numbered `10, 20, 30` to leave room, exactly as `template_title_placement.sort`
allows. allows.
The name `paper_template_filed_sort` keeps the spelling the feature was The name `paper_template_filed_sort` keeps the spelling the feature was
specified with; it is the template field's `sort` (the `sort` column of specified with; it is the template field's `sort` (the `sort` column of
`template_field`). `paper_sentence.template_id` is the template the sentence was `template_title_placement`). `paper_sentence.template_id` is the template the sentence was
written against. It is kept in step with the paper's current template and is written against. It is kept in step with the paper's current template and is
provenance rather than a lookup key: rendering never filters on it, which is provenance rather than a lookup key: rendering never filters on it, which is
precisely why content survives a switch. precisely why content survives a switch.
@@ -263,10 +287,10 @@ All routes are mounted under `/api`. Interactive docs at `/docs`.
| Method | Path | Notes | | Method | Path | Notes |
|---|---|---| |---|---|---|
| `GET` | `/health` | liveness plus a TiDB probe | | `GET` | `/health` | liveness plus a TiDB probe |
| `GET` | `/template-field-library` | `keyword`, `level`, `page`, `page_size` | | `GET` | `/template-titles` | `keyword`, `level`, `page`, `page_size` |
| `POST` | `/template-field-library` | create a library entry | | `POST` | `/template-titles` | create a library entry |
| `GET` `PATCH` `DELETE` | `/template-field-library/{id}` | read / partial update / delete | | `GET` `PATCH` `DELETE` | `/template-titles/{id}` | read / partial update / delete |
| `POST` | `/template-field-library/batch-delete` | body `{ "ids": [...] }` | | `POST` | `/template-titles/batch-delete` | body `{ "ids": [...] }` |
| `GET` | `/templates` | `keyword` matches name **or** abstract | | `GET` | `/templates` | `keyword` matches name **or** abstract |
| `POST` | `/templates` | name + abstract + ordered `fields` | | `POST` | `/templates` | name + abstract + ordered `fields` |
| `GET` `PATCH` `DELETE` | `/templates/{id}` | `PATCH` with `fields` replaces the selection | | `GET` `PATCH` `DELETE` | `/templates/{id}` | `PATCH` with `fields` replaces the selection |
@@ -290,7 +314,7 @@ Conventions worth knowing:
- List endpoints return `{ items, total, page, page_size, pages }`. - List endpoints return `{ items, total, page, page_size, pages }`.
- A template read returns `fields` already ordered by `sort`; clients never sort. - A template read returns `fields` already ordered by `sort`; clients never sort.
- Route paths mirror table names one for one: `/templates` for `template`, - Route paths mirror table names one for one: `/templates` for `template`,
`/template-field-library` for `template_field_library`, `/papers` for `/template-titles` for `template_title`, `/papers` for
`paper`. `paper`.
- A paper document returns its `paragraphs` in ascending position order, - A paper document returns its `paragraphs` in ascending position order,
already carrying their sentences and citation numbering. The client sorts already carrying their sentences and citation numbering. The client sorts
@@ -451,7 +475,7 @@ are not lists (the paper document) keep scrolling normally.
| `/papers/:id` | one paper, read as a document | `papers` | | `/papers/:id` | one paper, read as a document | `papers` |
| `/templates` | redirects to `/templates/list` | — | | `/templates` | redirects to `/templates/list` | — |
| `/templates/list` | template table + CRUD | `templates` | | `/templates/list` | template table + CRUD | `templates` |
| `/templates/fields` | field library + CRUD | `templates` | | `/templates/fields` | title library + CRUD (the UI label is 字段管理) | `templates` |
### The paper view ### The paper view
@@ -479,7 +503,7 @@ paper-doc/
├── backend/ # FastAPI application ├── backend/ # FastAPI application
│ ├── app/ │ ├── app/
│ │ ├── api/routes/ # route handlers (health, papers, templates, │ │ ├── api/routes/ # route handlers (health, papers, templates,
│ │ │ # template_field_library) │ │ │ # template_title)
│ │ ├── core/ # settings and configuration │ │ ├── core/ # settings and configuration
│ │ ├── crud/ # data-access helpers │ │ ├── crud/ # data-access helpers
│ │ ├── db/ # engine, session, declarative base │ │ ├── db/ # engine, session, declarative base
@@ -487,7 +511,7 @@ paper-doc/
│ │ ├── models/ # SQLAlchemy models │ │ ├── models/ # SQLAlchemy models
│ │ └── schemas/ # Pydantic request/response models │ │ └── schemas/ # Pydantic request/response models
│ ├── alembic/ # migration environment and revisions │ ├── alembic/ # migration environment and revisions
│ ├── scripts/seed.py # idempotent seed for the field library + templates │ ├── scripts/seed.py # idempotent seed for the title library + templates
│ ├── scripts/smoke_papers.py # end-to-end check of the writing loop │ ├── scripts/smoke_papers.py # end-to-end check of the writing loop
│ ├── scripts/mcp_server.py # MCP entry point (stdio / http) │ ├── scripts/mcp_server.py # MCP entry point (stdio / http)
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client │ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
@@ -557,7 +581,7 @@ alembic upgrade head
**Seed data** **Seed data**
`scripts/seed.py` fills the field library with a standard academic outline (20 `scripts/seed.py` fills the title library with a standard academic outline (20
fields, from `0 Abstract` to `7 References`) and creates three starter fields, from `0 Abstract` to `7 References`) and creates three starter
templates. It matches fields and templates by name, so running it twice adds templates. It matches fields and templates by name, so running it twice adds
nothing: nothing:
+2 -2
View File
@@ -102,8 +102,8 @@ export interface Sentence {
/** One paragraph of a paper: its heading and the sentences under it. */ /** One paragraph of a paper: its heading and the sentences under it. */
export interface PaperParagraph { export interface PaperParagraph {
paper_template_filed_sort: number paper_template_filed_sort: number
template_field_id: number | null placement_id: number | null
field_id: number | null title_id: number | null
/** `null` when the template has no placement here — rendered as 未设定. */ /** `null` when the template has no placement here — rendered as 未设定. */
name: string | null name: string | null
level: number level: number
@@ -1,8 +1,8 @@
import http from './client' import http from './client'
import type { BatchDeleteResult, PageQuery, PageResult } from './types' import type { BatchDeleteResult, PageQuery, PageResult } from './types'
/** Mirrors `app.schemas.template_field_library.TemplateFieldLibraryRead`. */ /** Mirrors `app.schemas.template_title.TemplateTitleRead`. */
export interface TemplateFieldLibrary { export interface TemplateTitle {
id: number id: number
/** Display name, numbering included — e.g. `1. Introduction`. */ /** Display name, numbering included — e.g. `1. Introduction`. */
name: string name: string
@@ -17,23 +17,23 @@ export interface TemplateFieldLibrary {
} }
/** Body for creating or updating a library field. */ /** Body for creating or updating a library field. */
export interface TemplateFieldLibraryPayload { export interface TemplateTitlePayload {
name: string name: string
level: number level: number
font_size: number font_size: number
font_color: string font_color: string
} }
export interface TemplateFieldLibraryQuery extends PageQuery { export interface TemplateTitleQuery extends PageQuery {
level?: number | null level?: number | null
} }
/** The API caps `page_size` at 500; 200 keeps responses modest while looping. */ /** The API caps `page_size` at 500; 200 keeps responses modest while looping. */
const LIBRARY_PAGE_SIZE = 200 const LIBRARY_PAGE_SIZE = 200
export async function listTemplateFieldLibrary( export async function listTemplateTitle(
query: TemplateFieldLibraryQuery = {}, query: TemplateTitleQuery = {},
): Promise<PageResult<TemplateFieldLibrary>> { ): Promise<PageResult<TemplateTitle>> {
// Drop empty filters so the URL stays clean and the backend sees "no filter" // Drop empty filters so the URL stays clean and the backend sees "no filter"
// rather than `keyword=`. // rather than `keyword=`.
const params: Record<string, unknown> = {} const params: Record<string, unknown> = {}
@@ -42,8 +42,8 @@ export async function listTemplateFieldLibrary(
if (query.page) params.page = query.page if (query.page) params.page = query.page
if (query.page_size) params.page_size = query.page_size if (query.page_size) params.page_size = query.page_size
const { data } = await http.get<PageResult<TemplateFieldLibrary>>( const { data } = await http.get<PageResult<TemplateTitle>>(
'/template-field-library', '/template-titles',
{ params }, { params },
) )
return data return data
@@ -55,12 +55,12 @@ export async function listTemplateFieldLibrary(
* The template form needs every field, not one page, so that a field placed * The template form needs every field, not one page, so that a field placed
* deep in the library can still be shown by name in an existing selection. * deep in the library can still be shown by name in an existing selection.
*/ */
export async function fetchAllTemplateFieldLibrary(keyword?: string): Promise<TemplateFieldLibrary[]> { export async function fetchAllTemplateTitle(keyword?: string): Promise<TemplateTitle[]> {
const all: TemplateFieldLibrary[] = [] const all: TemplateTitle[] = []
let page = 1 let page = 1
for (;;) { for (;;) {
const result = await listTemplateFieldLibrary({ const result = await listTemplateTitle({
keyword, keyword,
page, page,
page_size: LIBRARY_PAGE_SIZE, page_size: LIBRARY_PAGE_SIZE,
@@ -73,29 +73,29 @@ export async function fetchAllTemplateFieldLibrary(keyword?: string): Promise<Te
} }
} }
export async function createTemplateFieldLibrary( export async function createTemplateTitle(
payload: TemplateFieldLibraryPayload, payload: TemplateTitlePayload,
): Promise<TemplateFieldLibrary> { ): Promise<TemplateTitle> {
const { data } = await http.post<TemplateFieldLibrary>('/template-field-library', payload) const { data } = await http.post<TemplateTitle>('/template-titles', payload)
return data return data
} }
export async function updateTemplateFieldLibrary( export async function updateTemplateTitle(
id: number, id: number,
payload: Partial<TemplateFieldLibraryPayload>, payload: Partial<TemplateTitlePayload>,
): Promise<TemplateFieldLibrary> { ): Promise<TemplateTitle> {
const { data } = await http.patch<TemplateFieldLibrary>(`/template-field-library/${id}`, payload) const { data } = await http.patch<TemplateTitle>(`/template-titles/${id}`, payload)
return data return data
} }
export async function deleteTemplateFieldLibrary(id: number): Promise<void> { export async function deleteTemplateTitle(id: number): Promise<void> {
await http.delete(`/template-field-library/${id}`) await http.delete(`/template-titles/${id}`)
} }
export async function batchDeleteTemplateFieldLibrary( export async function batchDeleteTemplateTitle(
ids: number[], ids: number[],
): Promise<BatchDeleteResult> { ): Promise<BatchDeleteResult> {
const { data } = await http.post<BatchDeleteResult>('/template-field-library/batch-delete', { const { data } = await http.post<BatchDeleteResult>('/template-titles/batch-delete', {
ids, ids,
}) })
return data return data
+11 -8
View File
@@ -1,10 +1,11 @@
import http from './client' import http from './client'
import type { BatchDeleteResult, PageQuery, PageResult } from './types' import type { BatchDeleteResult, PageQuery, PageResult } from './types'
/** One placement of a library field inside a template, with its typography. */ /** One placement of a library title inside a template, with its typography. */
export interface TemplateField { export interface TemplateTitlePlacement {
id: number id: number
field_id: number /** The library entry this placement puts here. */
title_id: number
/** Display position. The only thing that decides render order. */ /** Display position. The only thing that decides render order. */
sort: number sort: number
name: string name: string
@@ -18,7 +19,8 @@ export interface TemplateListItem {
id: number id: number
name: string name: string
abstract: string | null abstract: string | null
field_count: number /** How many placements the template defines. */
placement_count: number
created_at: string created_at: string
updated_at: string updated_at: string
} }
@@ -28,21 +30,22 @@ export interface TemplateDetail {
id: number id: number
name: string name: string
abstract: string | null abstract: string | null
fields: TemplateField[] /** The outline, already ordered by `sort`. */
placements: TemplateTitlePlacement[]
created_at: string created_at: string
updated_at: string updated_at: string
} }
/** One entry of the selection sent on create/update. */ /** One entry of the selection sent on create/update. */
export interface TemplateFieldInput { export interface TemplateTitlePlacementInput {
field_id: number title_id: number
sort: number sort: number
} }
export interface TemplatePayload { export interface TemplatePayload {
name: string name: string
abstract: string | null abstract: string | null
fields: TemplateFieldInput[] placements: TemplateTitlePlacementInput[]
} }
export async function listTemplates( export async function listTemplates(
@@ -11,18 +11,18 @@ import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
import { errorMessage } from '@/api/client' import { errorMessage } from '@/api/client'
import { import {
createTemplateFieldLibrary, createTemplateTitle,
updateTemplateFieldLibrary, updateTemplateTitle,
type TemplateFieldLibrary, type TemplateTitle,
type TemplateFieldLibraryPayload, type TemplateTitlePayload,
} from '@/api/templateFieldLibrary' } from '@/api/templateTitles'
import { normalizeHexColor, typographyStyle } from '@/utils/format' import { normalizeHexColor, typographyStyle } from '@/utils/format'
const props = defineProps<{ const props = defineProps<{
/** Visibility, used with `v-model`. */ /** Visibility, used with `v-model`. */
modelValue: boolean modelValue: boolean
/** The field being edited, or `null` to create a new one. */ /** The field being edited, or `null` to create a new one. */
field: TemplateFieldLibrary | null field: TemplateTitle | null
}>() }>()
const emit = defineEmits<{ const emit = defineEmits<{
@@ -39,7 +39,7 @@ const visible = computed({
const formRef = ref<FormInstance>() const formRef = ref<FormInstance>()
const saving = ref(false) const saving = ref(false)
const form = reactive<TemplateFieldLibraryPayload>({ const form = reactive<TemplateTitlePayload>({
name: '', name: '',
level: 1, level: 1,
// 小四, the conventional body size for a Chinese thesis. // 小四, the conventional body size for a Chinese thesis.
@@ -47,7 +47,7 @@ const form = reactive<TemplateFieldLibraryPayload>({
font_color: '#000000', font_color: '#000000',
}) })
const rules: FormRules<TemplateFieldLibraryPayload> = { const rules: FormRules<TemplateTitlePayload> = {
name: [ name: [
{ required: true, message: '请填写字段名称', trigger: 'blur' }, { required: true, message: '请填写字段名称', trigger: 'blur' },
{ max: 255, message: '字段名称最多 255 个字符', trigger: 'blur' }, { max: 255, message: '字段名称最多 255 个字符', trigger: 'blur' },
@@ -118,10 +118,10 @@ async function submit(): Promise<void> {
saving.value = true saving.value = true
try { try {
if (props.field) { if (props.field) {
await updateTemplateFieldLibrary(props.field.id, { ...form }) await updateTemplateTitle(props.field.id, { ...form })
ElMessage.success('字段已更新,使用它的模板会同步生效') ElMessage.success('字段已更新,使用它的模板会同步生效')
} else { } else {
await createTemplateFieldLibrary({ ...form }) await createTemplateTitle({ ...form })
ElMessage.success('字段已创建') ElMessage.success('字段已创建')
} }
emit('saved') emit('saved')
@@ -173,7 +173,7 @@ async function submit(): Promise<void> {
:label="template.name" :label="template.name"
> >
<span>{{ template.name }}</span> <span>{{ template.name }}</span>
<span class="option-hint">{{ template.field_count }} 段</span> <span class="option-hint">{{ template.placement_count }} 段</span>
</el-option> </el-option>
</el-select> </el-select>
<div v-if="templates.length === 0" class="field-hint"> <div v-if="templates.length === 0" class="field-hint">
@@ -107,7 +107,10 @@ async function loadCandidate(templateId: number | null): Promise<void> {
previewing.value = true previewing.value = true
try { try {
const detail = await getTemplate(templateId) const detail = await getTemplate(templateId)
candidate.value = detail.fields.map((field) => ({ sort: field.sort, name: field.name })) candidate.value = detail.placements.map((placement) => ({
sort: placement.sort,
name: placement.name,
}))
} catch (error) { } catch (error) {
ElMessage.error(errorMessage(error)) ElMessage.error(errorMessage(error))
candidate.value = [] candidate.value = []
@@ -170,7 +173,7 @@ async function submit(): Promise<void> {
:disabled="template.id === paper.template_id" :disabled="template.id === paper.template_id"
> >
<span>{{ template.name }}</span> <span>{{ template.name }}</span>
<span class="option-hint">{{ template.field_count }} 段</span> <span class="option-hint">{{ template.placement_count }} 段</span>
</el-option> </el-option>
</el-select> </el-select>
</div> </div>
@@ -4,7 +4,7 @@
* *
* The picker is the heart of the feature, and it is deliberately *not* a tree. * The picker is the heart of the feature, and it is deliberately *not* a tree.
* Fields come from one flat library and are chosen freely: any subset, any * Fields come from one flat library and are chosen freely: any subset, any
* order, and the same field more than once. What the reader finally sees is * order, and the same title more than once. What the reader finally sees is
* decided by `sort` alone, so the right-hand list is always rendered sorted by * decided by `sort` alone, so the right-hand list is always rendered sorted by
* `sort` — reordering the numbers reorders the outline immediately, and the * `sort` — reordering the numbers reorders the outline immediately, and the
* order the user clicked in is never stored. * order the user clicked in is never stored.
@@ -28,12 +28,12 @@ import {
import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus' import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
import { errorMessage } from '@/api/client' import { errorMessage } from '@/api/client'
import { fetchAllTemplateFieldLibrary, type TemplateFieldLibrary } from '@/api/templateFieldLibrary' import { fetchAllTemplateTitle, type TemplateTitle } from '@/api/templateTitles'
import { import {
createTemplate, createTemplate,
getTemplate, getTemplate,
updateTemplate, updateTemplate,
type TemplateFieldInput, type TemplateTitlePlacementInput,
type TemplateListItem, type TemplateListItem,
} from '@/api/templates' } from '@/api/templates'
import { levelIndent, typographyStyle } from '@/utils/format' import { levelIndent, typographyStyle } from '@/utils/format'
@@ -51,11 +51,11 @@ const emit = defineEmits<{
saved: [] saved: []
}>() }>()
/** One chosen field, at one position. The same field may appear many times. */ /** One chosen title, at one position. The same title may appear many times. */
interface Placement { interface Placement {
/** Local identity for `v-for` / `row-key`; not sent to the server. */ /** Local identity for `v-for` / `row-key`; not sent to the server. */
key: number key: number
field_id: number title_id: number
sort: number sort: number
} }
@@ -70,7 +70,7 @@ const formRef = ref<FormInstance>()
const loading = ref(false) const loading = ref(false)
const saving = ref(false) const saving = ref(false)
const library = ref<TemplateFieldLibrary[]>([]) const library = ref<TemplateTitle[]>([])
const libraryKeyword = ref('') const libraryKeyword = ref('')
const selected = ref<Placement[]>([]) const selected = ref<Placement[]>([])
@@ -81,12 +81,12 @@ const rules: FormRules = { name: [{ required: true, message: '请填写模板名
/** Keys only ever count up, so a reopened dialog cannot collide with itself. */ /** Keys only ever count up, so a reopened dialog cannot collide with itself. */
let nextKey = 1 let nextKey = 1
const fieldMap = computed(() => new Map(library.value.map((field) => [field.id, field]))) const titleMap = computed(() => new Map(library.value.map((title) => [title.id, title])))
const filteredLibrary = computed(() => { const filteredLibrary = computed(() => {
const keyword = libraryKeyword.value.trim().toLowerCase() const keyword = libraryKeyword.value.trim().toLowerCase()
if (!keyword) return library.value if (!keyword) return library.value
return library.value.filter((field) => field.name.toLowerCase().includes(keyword)) return library.value.filter((title) => title.name.toLowerCase().includes(keyword))
}) })
/** The selection in display order — ascending `sort`, ties by insertion. */ /** The selection in display order — ascending `sort`, ties by insertion. */
@@ -98,15 +98,15 @@ const rows = computed(() =>
// property name `key` rather than a function expression. // property name `key` rather than a function expression.
key: placement.key, key: placement.key,
placement, placement,
field: fieldMap.value.get(placement.field_id), title: titleMap.value.get(placement.title_id),
})), })),
) )
/** How many times each library field is placed. */ /** How many times each library title is placed. */
const repeatCounts = computed(() => { const repeatCounts = computed(() => {
const counts = new Map<number, number>() const counts = new Map<number, number>()
for (const placement of selected.value) { for (const placement of selected.value) {
counts.set(placement.field_id, (counts.get(placement.field_id) ?? 0) + 1) counts.set(placement.title_id, (counts.get(placement.title_id) ?? 0) + 1)
} }
return counts return counts
}) })
@@ -114,7 +114,7 @@ const repeatCounts = computed(() => {
const repeatedNames = computed(() => const repeatedNames = computed(() =>
[...repeatCounts.value.entries()] [...repeatCounts.value.entries()]
.filter(([, count]) => count > 1) .filter(([, count]) => count > 1)
.map(([id, count]) => `${fieldMap.value.get(id)?.name ?? `#${id}`} ×${count}`), .map(([id, count]) => `${titleMap.value.get(id)?.name ?? `#${id}`} ×${count}`),
) )
const duplicatedSorts = computed(() => { const duplicatedSorts = computed(() => {
@@ -143,18 +143,18 @@ watch(
loading.value = true loading.value = true
try { try {
// The whole library, so a field that was placed before the keyword // The whole library, so a title that was placed before the keyword
// filter existed still resolves to a name in the selection. // filter existed still resolves to a name in the selection.
library.value = await fetchAllTemplateFieldLibrary() library.value = await fetchAllTemplateTitle()
if (props.template) { if (props.template) {
const detail = await getTemplate(props.template.id) const detail = await getTemplate(props.template.id)
form.name = detail.name form.name = detail.name
form.abstract = detail.abstract ?? '' form.abstract = detail.abstract ?? ''
selected.value = detail.fields.map((field) => ({ selected.value = detail.placements.map((placement) => ({
key: nextKey++, key: nextKey++,
field_id: field.field_id, title_id: placement.title_id,
sort: field.sort, sort: placement.sort,
})) }))
} }
} catch (error) { } catch (error) {
@@ -166,9 +166,9 @@ watch(
) )
/** Append a placement, at the end of the current order. */ /** Append a placement, at the end of the current order. */
function addField(field: TemplateFieldLibrary): void { function addTitle(title: TemplateTitle): void {
const highest = selected.value.reduce((max, item) => Math.max(max, item.sort), 0) const highest = selected.value.reduce((max, item) => Math.max(max, item.sort), 0)
selected.value.push({ key: nextKey++, field_id: field.id, sort: highest + 1 }) selected.value.push({ key: nextKey++, title_id: title.id, sort: highest + 1 })
} }
function removePlacement(key: number): void { function removePlacement(key: number): void {
@@ -208,7 +208,7 @@ function autoSort(): void {
} }
/** /**
* Open the field library in a second tab. * Open the title library in a second tab.
* *
* Deliberately not an in-place navigation: a half-filled template form would * Deliberately not an in-place navigation: a half-filled template form would
* be lost, and the usual reason to go there is "the field I need does not * be lost, and the usual reason to go there is "the field I need does not
@@ -240,14 +240,14 @@ async function submit(): Promise<void> {
// Sent in display order, so that equal `sort` values get placement ids in // Sent in display order, so that equal `sort` values get placement ids in
// the same order the user sees and the backend's id tie-break agrees with // the same order the user sees and the backend's id tie-break agrees with
// the screen. // the screen.
const fields: TemplateFieldInput[] = rows.value.map((row) => ({ const placements: TemplateTitlePlacementInput[] = rows.value.map((row) => ({
field_id: row.placement.field_id, title_id: row.placement.title_id,
sort: row.placement.sort, sort: row.placement.sort,
})) }))
const payload = { const payload = {
name: form.name.trim(), name: form.name.trim(),
abstract: form.abstract.trim() || null, abstract: form.abstract.trim() || null,
fields, placements,
} }
if (props.template) { if (props.template) {
@@ -321,18 +321,21 @@ async function submit(): Promise<void> {
<div class="picker-list"> <div class="picker-list">
<button <button
v-for="field in filteredLibrary" v-for="title in filteredLibrary"
:key="field.id" :key="title.id"
type="button" type="button"
class="lib-item" class="lib-item"
@click="addField(field)" @click="addTitle(title)"
> >
<span class="lib-name" :style="{ paddingLeft: levelIndent(field.level), ...typographyStyle(field) }"> <span
{{ field.name }} class="lib-name"
:style="{ paddingLeft: levelIndent(title.level), ...typographyStyle(title) }"
>
{{ title.name }}
</span> </span>
<span class="lib-side"> <span class="lib-side">
<el-tag v-if="repeatCounts.get(field.id)" size="small" type="warning" effect="plain"> <el-tag v-if="repeatCounts.get(title.id)" size="small" type="warning" effect="plain">
×{{ repeatCounts.get(field.id) }} ×{{ repeatCounts.get(title.id) }}
</el-tag> </el-tag>
<el-icon class="lib-add"><Plus /></el-icon> <el-icon class="lib-add"><Plus /></el-icon>
</span> </span>
@@ -404,7 +407,7 @@ async function submit(): Promise<void> {
> >
{{ row.field.name }} {{ row.field.name }}
</span> </span>
<span v-else class="missing">字段 #{{ row.placement.field_id }} 已不存在</span> <span v-else class="missing">标题 #{{ row.placement.title_id }} 已不存在</span>
</template> </template>
</el-table-column> </el-table-column>
@@ -516,7 +519,7 @@ async function submit(): Promise<void> {
scrollbar-width: thin; scrollbar-width: thin;
} }
/* A button per field: clickable, focusable and keyboard-operable for free. */ /* A button per title: clickable, focusable and keyboard-operable for free. */
.lib-item { .lib-item {
display: flex; display: flex;
align-items: center; align-items: center;
@@ -7,12 +7,12 @@
* drawn at its own font size and colour. The `sort` value is shown alongside so * drawn at its own font size and colour. The `sort` value is shown alongside so
* the order can be checked against the numbers rather than taken on trust. * the order can be checked against the numbers rather than taken on trust.
*/ */
import type { TemplateField } from '@/api/templates' import type { TemplateTitlePlacement } from '@/api/templates'
import { levelIndent, typographyStyle } from '@/utils/format' import { levelIndent, typographyStyle } from '@/utils/format'
withDefaults( withDefaults(
defineProps<{ defineProps<{
fields: TemplateField[] placements: TemplateTitlePlacement[]
/** Show the sort value and typography under each heading. */ /** Show the sort value and typography under each heading. */
showMeta?: boolean showMeta?: boolean
}>(), }>(),
@@ -22,10 +22,10 @@ withDefaults(
<template> <template>
<div class="outline"> <div class="outline">
<el-empty v-if="fields.length === 0" description="这个模板还没有选择任何字段" /> <el-empty v-if="placements.length === 0" description="这个模板还没有选择任何字段" />
<ol v-else class="outline-list"> <ol v-else class="outline-list">
<li v-for="field in fields" :key="field.id" class="outline-row"> <li v-for="field in placements" :key="field.id" class="outline-row">
<span class="outline-sort">{{ field.sort }}</span> <span class="outline-sort">{{ field.sort }}</span>
<div class="outline-body"> <div class="outline-body">
<div class="outline-name" :style="{ paddingLeft: levelIndent(field.level) }"> <div class="outline-name" :style="{ paddingLeft: levelIndent(field.level) }">
+6 -6
View File
@@ -12,7 +12,7 @@ import { useRouter } from 'vue-router'
import { Files, Notebook, Setting } from '@element-plus/icons-vue' import { Files, Notebook, Setting } from '@element-plus/icons-vue'
import { listPapers } from '@/api/papers' import { listPapers } from '@/api/papers'
import { listTemplateFieldLibrary } from '@/api/templateFieldLibrary' import { listTemplateTitle } from '@/api/templateTitles'
import { listTemplates } from '@/api/templates' import { listTemplates } from '@/api/templates'
import AppLogo from '@/components/AppLogo.vue' import AppLogo from '@/components/AppLogo.vue'
@@ -20,7 +20,7 @@ const router = useRouter()
const paperCount = ref<number | null>(null) const paperCount = ref<number | null>(null)
const templateCount = ref<number | null>(null) const templateCount = ref<number | null>(null)
const fieldCount = ref<number | null>(null) const titleCount = ref<number | null>(null)
/** `null` renders as an em dash: unknown, not zero. */ /** `null` renders as an em dash: unknown, not zero. */
function display(value: number | null): string { function display(value: number | null): string {
@@ -30,14 +30,14 @@ function display(value: number | null): string {
onMounted(async () => { onMounted(async () => {
// `page_size: 1` because only `total` is used. A failure leaves the count as // `page_size: 1` because only `total` is used. A failure leaves the count as
// an em dash rather than blocking the page. // an em dash rather than blocking the page.
const [papers, templates, fields] = await Promise.allSettled([ const [papers, templates, titles] = await Promise.allSettled([
listPapers({ page: 1, page_size: 1 }), listPapers({ page: 1, page_size: 1 }),
listTemplates({ page: 1, page_size: 1 }), listTemplates({ page: 1, page_size: 1 }),
listTemplateFieldLibrary({ page: 1, page_size: 1 }), listTemplateTitle({ page: 1, page_size: 1 }),
]) ])
if (papers.status === 'fulfilled') paperCount.value = papers.value.total if (papers.status === 'fulfilled') paperCount.value = papers.value.total
if (templates.status === 'fulfilled') templateCount.value = templates.value.total if (templates.status === 'fulfilled') templateCount.value = templates.value.total
if (fields.status === 'fulfilled') fieldCount.value = fields.value.total if (titles.status === 'fulfilled') titleCount.value = titles.value.total
}) })
</script> </script>
@@ -81,7 +81,7 @@ onMounted(async () => {
<div class="stat"> <div class="stat">
<el-icon class="stat-icon"><Setting /></el-icon> <el-icon class="stat-icon"><Setting /></el-icon>
<div> <div>
<div class="stat-value">{{ display(fieldCount) }}</div> <div class="stat-value">{{ display(titleCount) }}</div>
<div class="stat-label">字段库</div> <div class="stat-label">字段库</div>
</div> </div>
</div> </div>
@@ -14,18 +14,18 @@ import { ElMessage, ElMessageBox } from 'element-plus'
import { errorMessage } from '@/api/client' import { errorMessage } from '@/api/client'
import { import {
batchDeleteTemplateFieldLibrary, batchDeleteTemplateTitle,
deleteTemplateFieldLibrary, deleteTemplateTitle,
listTemplateFieldLibrary, listTemplateTitle,
type TemplateFieldLibrary, type TemplateTitle,
} from '@/api/templateFieldLibrary' } from '@/api/templateTitles'
import FieldFormDialog from '@/components/fields/FieldFormDialog.vue' import FieldFormDialog from '@/components/fields/FieldFormDialog.vue'
import { formatDateTime, levelIndent, typographyStyle } from '@/utils/format' import { formatDateTime, levelIndent, typographyStyle } from '@/utils/format'
const loading = ref(false) const loading = ref(false)
const rows = ref<TemplateFieldLibrary[]>([]) const rows = ref<TemplateTitle[]>([])
const total = ref(0) const total = ref(0)
const selection = ref<TemplateFieldLibrary[]>([]) const selection = ref<TemplateTitle[]>([])
const query = reactive({ const query = reactive({
keyword: '', keyword: '',
@@ -35,7 +35,7 @@ const query = reactive({
}) })
const dialogVisible = ref(false) const dialogVisible = ref(false)
const editing = ref<TemplateFieldLibrary | null>(null) const editing = ref<TemplateTitle | null>(null)
const LEVEL_FILTERS = [ const LEVEL_FILTERS = [
{ value: null, label: '全部等级' }, { value: null, label: '全部等级' },
@@ -47,7 +47,7 @@ const LEVEL_FILTERS = [
async function load(): Promise<void> { async function load(): Promise<void> {
loading.value = true loading.value = true
try { try {
const result = await listTemplateFieldLibrary(query) const result = await listTemplateTitle(query)
rows.value = result.items rows.value = result.items
total.value = result.total total.value = result.total
@@ -81,12 +81,12 @@ function onCreate(): void {
dialogVisible.value = true dialogVisible.value = true
} }
function onEdit(row: TemplateFieldLibrary): void { function onEdit(row: TemplateTitle): void {
editing.value = row editing.value = row
dialogVisible.value = true dialogVisible.value = true
} }
async function onDelete(row: TemplateFieldLibrary): Promise<void> { async function onDelete(row: TemplateTitle): Promise<void> {
try { try {
await ElMessageBox.confirm(`确定删除字段「${row.name}」?`, '删除字段', { await ElMessageBox.confirm(`确定删除字段「${row.name}」?`, '删除字段', {
type: 'warning', type: 'warning',
@@ -98,7 +98,7 @@ async function onDelete(row: TemplateFieldLibrary): Promise<void> {
} }
try { try {
await deleteTemplateFieldLibrary(row.id) await deleteTemplateTitle(row.id)
ElMessage.success('已删除') ElMessage.success('已删除')
await load() await load()
} catch (error) { } catch (error) {
@@ -121,7 +121,7 @@ async function onBatchDelete(): Promise<void> {
} }
try { try {
const result = await batchDeleteTemplateFieldLibrary(ids) const result = await batchDeleteTemplateTitle(ids)
ElMessage.success(`已删除 ${result.deleted} 个字段`) ElMessage.success(`已删除 ${result.deleted} 个字段`)
selection.value = [] selection.value = []
await load() await load()
@@ -195,7 +195,7 @@ onMounted(load)
stripe stripe
class="table table-fill" class="table table-fill"
height="100%" height="100%"
@selection-change="(value: TemplateFieldLibrary[]) => (selection = value)" @selection-change="(value: TemplateTitle[]) => (selection = value)"
> >
<el-table-column type="selection" width="46" reserve-selection /> <el-table-column type="selection" width="46" reserve-selection />
@@ -4,7 +4,7 @@
* *
* The full CRUD surface: search, create, edit, single and batch delete, with a * The full CRUD surface: search, create, edit, single and batch delete, with a
* preview drawer that renders a template's outline exactly as it will read. * preview drawer that renders a template's outline exactly as it will read.
* The drawer is the quickest way to confirm that a template's fields really do * The drawer is the quickest way to confirm that a template's titles really do
* come out in `sort` order before committing to write against it. * come out in `sort` order before committing to write against it.
*/ */
import { onMounted, reactive, ref } from 'vue' import { onMounted, reactive, ref } from 'vue'
@@ -210,7 +210,7 @@ onMounted(load)
<el-table-column label="段落数" width="100" align="center"> <el-table-column label="段落数" width="100" align="center">
<template #default="{ row }"> <template #default="{ row }">
<el-tag size="small" effect="plain">{{ row.field_count }}</el-tag> <el-tag size="small" effect="plain">{{ row.placement_count }}</el-tag>
</template> </template>
</el-table-column> </el-table-column>
@@ -262,7 +262,7 @@ onMounted(load)
<div class="preview-meta"> <div class="preview-meta">
<el-tag size="small" effect="plain"> <el-tag size="small" effect="plain">
<el-icon><Files /></el-icon> <el-icon><Files /></el-icon>
{{ preview.fields.length }} 个段落 {{ preview.placements.length }} 个段落
</el-tag> </el-tag>
<span class="muted">更新于 {{ formatDateTime(preview.updated_at) }}</span> <span class="muted">更新于 {{ formatDateTime(preview.updated_at) }}</span>
</div> </div>
@@ -274,7 +274,7 @@ onMounted(load)
<span class="divider-hint">已按 sort 升序排列</span> <span class="divider-hint">已按 sort 升序排列</span>
</el-divider> </el-divider>
<TemplateOutline :fields="preview.fields" /> <TemplateOutline :placements="preview.placements" />
</template> </template>
</div> </div>
</el-drawer> </el-drawer>