paper-doc/backend/app/mcp/tools/fields.py

"""Field-library tools (字段库): the reusable headings templates are built from.

The library is the catalogue, and ``template_field`` is a placement in one
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
outline that uses it and why deleting one is refused while any template still
places it.

The numbering a reader sees ("1. Introduction", "2.1 Study area") is part of
``name`` and is written by the caller. Nothing here derives or rewrites it:
``level`` is a rendering hint, not a parent pointer, which is what lets one
level-2 heading sit under two different level-1 headings in two templates.
"""

from __future__ import annotations

from typing import Annotated

from mcp.server.mcpserver import MCPServer
from pydantic import Field
from sqlalchemy.orm import Session

from app.crud import template_field_library as field_crud
from app.mcp import support as s
from app.mcp.tools.registry import mcp_tool
from app.models import TemplateFieldLibrary
from app.schemas.template_field_library import (
    TemplateFieldLibraryCreate,
    TemplateFieldLibraryUpdate,
)


def register(server: MCPServer) -> None:
    """Register every field-library tool on ``server``."""

    @mcp_tool(server, title="列出字段库")
    def field_list(
        keyword: Annotated[str | None, Field(description="按字段名称模糊搜索")] = None,
        level: Annotated[
            int | None, Field(description="按层级过滤：1 是一级标题，2 是二级")
        ] = None,
        page: Annotated[int, Field(description="页码，从 1 开始")] = 1,
        page_size: Annotated[int, Field(description="每页条数，最大 200")] = 50,
    ) -> str:
        """列出字段库（模板能用的所有标题）。建模板前先查这里的 id。"""
        page, page_size = s.page_args(page, page_size)
        with s.session() as db:
            rows, total = field_crud.list_fields(
                db, keyword=keyword, level=level, page=page, page_size=page_size
            )
            return s.dumps(
                s.page_payload(
                    items=[_field_row(row) for row in rows],
                    total=total,
                    page=page,
                    page_size=page_size,
                )
            )

    @mcp_tool(server, title="取一个字段")
    def field_get(
        field_id: Annotated[int, Field(description="字段 id")],
    ) -> str:
        """取字段库里一个字段，并给出它被几个模板使用。"""
        with s.session() as db:
            field = s.field_or_fail(db, field_id)
            payload = _field_row(field)
            payload["used_by_templates"] = field_crud.usage_counts(db, [field.id]).get(
                field.id, 0
            )
            return s.dumps(payload)

    @mcp_tool(server, title="新建字段")
    def field_create(
        name: Annotated[
            str,
            Field(description="字段名，编号要自己写进去，例如 “3. Results” 或 “3.1 Study area”"),
        ],
        level: Annotated[
            int, Field(description="层级 1-9，只决定缩进，1 是一级标题")
        ] = 1,
        font_size: Annotated[
            float, Field(description="字号（磅），中文五号是 10.5")
        ] = 12.0,
        font_color: Annotated[
            str, Field(description="颜色，#RRGGBB 或 rgb(r,g,b)")
        ] = "#000000",
    ) -> str:
        """往字段库加一个标题字段，可带字号颜色。"""
        payload = TemplateFieldLibraryCreate(
            name=name, level=level, font_size=font_size, font_color=font_color
        )
        with s.session() as db:
            return s.dumps(_field_row(field_crud.create(db, payload)))

    @mcp_tool(server, title="修改字段")
    def field_update(
        field_id: Annotated[int, Field(description="字段 id")],
        name: Annotated[str | None, Field(description="新名称；不传则不改")] = None,
        level: Annotated[int | None, Field(description="新层级")] = None,
        font_size: Annotated[float | None, Field(description="新字号")] = None,
        font_color: Annotated[str | None, Field(description="新颜色")] = None,
    ) -> str:
        """改字段的名称或排版。所有引用它的模板会立刻跟着变。"""
        # Only the keys actually given are sent: the update schema treats an
        # explicitly-passed ``None`` as "set this column to null", which no
        # column here allows, so a parameter left out must not reach it.
        values: dict[str, object] = {}
        if name is not None:
            values["name"] = name
        if level is not None:
            values["level"] = level
        if font_size is not None:
            values["font_size"] = font_size
        if font_color is not None:
            values["font_color"] = font_color
        if not values:
            s.fail("没有给出任何要修改的内容")

        payload = TemplateFieldLibraryUpdate(**values)

        with s.session() as db:
            field = s.field_or_fail(db, field_id)
            updated = field_crud.update(db, field, payload)
            result = _field_row(updated)
            result["used_by_templates"] = field_crud.usage_counts(db, [field_id]).get(
                field_id, 0
            )
            return s.dumps(result)

    @mcp_tool(server, title="删除字段")
    def field_delete(
        field_ids: Annotated[int | list[int], Field(description="字段 id，或 id 数组")],
    ) -> str:
        """删除字段（仍被模板使用的会被拒绝，需先从模板里移除）。"""
        ids = s.id_list(field_ids)
        if not ids:
            s.fail("必须给出至少一个字段 id")

        with s.session() as db:
            fields = field_crud.get_many(db, ids)
            _assert_unused(db, fields)
            for field in fields:
                field_crud.delete(db, field)
            found = {field.id for field in fields}
            return s.dumps(
                {
                    "deleted": len(fields),
                    "ids": [field_id for field_id in ids if field_id in found],
                    "missing": [field_id for field_id in ids if field_id not in found],
                }
            )


# --- helpers -----------------------------------------------------------------


def _field_row(field: TemplateFieldLibrary) -> dict:
    """One library entry as a model reads it."""
    return {
        "id": field.id,
        "name": field.name,
        "level": field.level,
        "font_size": float(field.font_size),
        "font_color": field.font_color,
    }


def _assert_unused(db: Session, fields: list[TemplateFieldLibrary]) -> None:
    """Refuse the delete while any template still places the field.

    Dropping a field that is placed somewhere would silently remove a heading
    from that template's outline — data loss wearing the costume of cleanup.
    Every offender is named at once, with its template count.
    """
    counts = field_crud.usage_counts(db, [field.id for field in fields])
    if not counts:
        return

    names = {field.id: field.name for field in fields}
    blockers = "、".join(
        f"“{names.get(field_id, field_id)}”（{count} 个模板）"
        for field_id, count in sorted(counts.items())
    )
    s.fail(f"以下字段正被模板使用，请先用 template_update 从模板里移除：{blockers}")