Metadata-Version: 2.3
Name: fastapirestframework-tortoise
Version: 0.0.7
Summary: DRF-inspired async CRUD framework for FastAPI and Tortoise ORM
Requires-Dist: fastapi==0.146.0
Requires-Dist: pydantic==2.14.1
Requires-Dist: tortoise-orm==1.1.9
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# FastAPI REST Framework · Tortoise

`fastapirestframework-tortoise` 是基于 FastAPI、Tortoise ORM 和 Pydantic v2 的异步 REST API 开发库，提供 DRF 风格的 Serializer、ViewSet、Router，以及按模型自动生成的 Vue 3 管理后台。

- PyPI 发行名：`fastapirestframework-tortoise`，当前版本 **0.0.7**；包含自动后台、自定义页面、行操作与多层导航，支持下文完整 Demo。
- Python 导入名：`fastapirestframework`。
- Python 要求：**3.12 或更高**。当前运行依赖固定为 FastAPI 0.146.0、Pydantic 2.14.1、Tortoise ORM 1.1.9。
- 后台资源随 wheel 提供，运行无需 Node、npm 或 CDN。

完整参数说明、分册用法及可独立运行的文档版示例统一维护在源码目录 `docs/guide/`，入口为 `docs/guide/README.md`。本页提供安装与主要用法；后续功能或参数变化会同步该目录。


### 0.0.7 后台保存、删除与导出

- 编辑弹窗支持「保存并继续编辑」。在模型的 `ModelAdmin` 配置 `copy_fields=("title", "content", "author", "tags")` 可启用「另存为新记录」。它创建新增草稿，由用户检查字段后保存。只复制明确声明的字段，主键和 Inline 子记录不复制。
- 单条和批量删除确认显示影响预览，按模型汇总预计级联删除和可能阻止删除的引用。实际结果以删除事务为准。
- 模型列表默认提供 CSV 下载。未勾选时导出当前页，勾选后仅导出所选记录。文件包含后台公开的全部模型字段及配置的计算列，列表列显隐不影响字段范围。

### 后台列表体验

- 配置了筛选的模型会在列表上方显示可折叠的筛选卡片。宽度随内容收缩，空间不足时换行。「查询」应用筛选，「重置」清空筛选条件。
- 列表工具栏提供关键词搜索、新增、刷新、列设置和保存查询。列设置只影响当前打开的模型列表。保存查询记录已应用的关键词、筛选、排序和每页条数，每个模型在当前浏览器最多保存 20 个预设。
- 表格使用细边框、浅色斑马纹和三行正文预览。查询、重置、新增和删除使用不同的操作颜色。

### 后台编辑体验

- 多对多字段显示已选摘要，点「管理选择」打开穿梭框。候选支持远程搜索和分页，已选项可单独搜索。应用选择后回填主表单，随主表单保存。
- 外键使用可搜索的单选下拉，选项显示名称及 ID，快捷新增位于下拉底部。
- 编辑表单每个字段独占一行，按配置顺序排列。桌面标签在左，窄屏标签在上。弹窗显示当前记录名称，优先使用 `label_field`。字段说明可悬停或聚焦信息图标查看。
- 列表与详情继续统一布尔标签、枚举和时间格式，JSON 在列表显示摘要，在详情显示格式化内容。

## 使用目录

1. [安装与启动](#安装与启动)
2. [完整单文件 Demo](#完整单文件-demo)
3. [调用 API、认证与关联保存](#调用-api)
4. [普通 API 的常用扩展](#普通-api-的常用扩展)
5. [自动管理后台 frfadmin](#自动管理后台-frfadmin)
6. [后台导航分组](#后台导航分组)
7. [自定义数据页面](#自定义数据页面)
8. [行操作、参数表单与动态候选](#行操作参数表单与动态候选)
9. [MCP 单表示例与运行入口](#mcp-单表示例与运行入口)
10. [常见问题与能力边界](#常见问题与能力边界)

## 安装与启动

已发布版本可以这样安装：

```bash
uv add fastapirestframework-tortoise==0.0.7 uvicorn
```

**下方安装指令使用 0.0.7。旧版 0.0.2 不包含 `AdminPage/register_page`，请先升级。**

在当前源码仓库根目录，可以直接运行：

```bash
make demo
```

若要把完整代码独立复制为 `app.py`，先在一个新目录创建环境并安装本版：

```bash
uv init --python 3.12
uv add fastapirestframework-tortoise==0.0.7 uvicorn
```

将下一节完整代码保存为新目录的 **app.py**，然后运行：

```bash
uv run uvicorn app:app --host 127.0.0.1 --port 8000
```

打开：

- [自动管理后台](http://127.0.0.1:8000/admin/)：可先新增用户、标签，再新增文章。
- 后台侧栏 **内容管理 → 数据概览**：查看统计卡片、筛选表格，点击加号并确认后新增示例文章。
- [Swagger API 文档](http://127.0.0.1:8000/docs)：点击 Authorize，输入 `admin-demo` 或 `user-demo`，不需要手动输入 Bearer 前缀。

按 Ctrl+C 停止。示例使用 SQLite 内存数据库，启动时自动建表，重启后数据清空。生产应用应自行管理数据库配置和迁移。

## 完整单文件 Demo

关系为：User 一对多 Post；每篇 Post 必须有一个作者，可以有零个或多个 Tag；Tag 可由多篇文章共享。User 仅为作者资料，与演示认证令牌分开。

这份代码无需导入仓库的 `examples`，可以独立保存为 `app.py` 使用。`PostOverview`、查询和操作方法以及 `admin.register_page(...)` 均包含在同一个文件中。

```python
"""可独立复制的单文件入门 Demo：API、自动后台及自定义数据概览页。"""

from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from typing import ClassVar

from fastapi import Depends, FastAPI, Request
from fastapi.security import HTTPBearer
from tortoise import fields
from tortoise.contrib.fastapi import RegisterTortoise
from tortoise.models import Model
from tortoise.queryset import QuerySet
from tortoise.transactions import in_transaction

from fastapirestframework import configure
from fastapirestframework.admin import (
    AdminPage,
    AdminRouter,
    FieldOptions,
    ModelAdmin,
    PageAction,
    PageColumn,
    PageFilter,
    PageQuery,
    PageResult,
    PageStat,
)
from fastapirestframework.authentication import BearerAuthentication, Identity
from fastapirestframework.decorators import action
from fastapirestframework.exceptions import (
    AuthenticationFailed,
    Conflict,
    NotFound,
    ValidationError,
)
from fastapirestframework.permissions import IsAdminUser, IsAuthenticated
from fastapirestframework.routers import DefaultRouter
from fastapirestframework.serializers import (
    Field,
    IntegerField,
    ModelSerializer,
    NestedField,
    Serializer,
)
from fastapirestframework.throttling import ScopedRateThrottle, UserRateThrottle
from fastapirestframework.viewsets import ModelViewSet

DEMO_TOKENS: dict[str, Identity] = {
    "user-demo": Identity(user="demo-user", is_authenticated=True),
    "admin-demo": Identity(user="demo-admin", is_authenticated=True, is_admin=True),
}


class DemoAuthentication(BearerAuthentication):
    """固定令牌仅用于演示认证，User 是作者资料，不承担登录账户职责。"""

    async def authenticate_credentials(self, credential: str, request: Request) -> Identity:
        """未知令牌立即401，不把客户端自报用户当作已验证身份。"""
        identity: Identity | None = DEMO_TOKENS.get(credential)
        if identity is None:
            raise AuthenticationFailed("演示令牌无效。")
        return identity


class User(Model):
    """一个作者可以有多篇文章；已有文章的作者不能直接删除。"""

    id = fields.IntField(primary_key=True)
    username = fields.CharField(max_length=50, unique=True)


class Tag(Model):
    """标签可以独立存在，也可以被多篇文章共享。"""

    id = fields.IntField(primary_key=True)
    name = fields.CharField(max_length=50, unique=True)


class Post(Model):
    """文章必须有一个作者；中间表保存零个或多个不重复的标签关系。"""

    id = fields.IntField(primary_key=True)
    title = fields.CharField(max_length=200)
    content = fields.TextField()
    author: fields.ForeignKeyRelation[User] = fields.ForeignKeyField(
        "models.User", related_name="posts", null=False, on_delete=fields.OnDelete.RESTRICT
    )
    tags: fields.ManyToManyRelation[Tag] = fields.ManyToManyField(
        "models.Tag",
        related_name="posts",
        through="post_tags",
        on_delete=fields.OnDelete.CASCADE,
        unique=True,
    )


class UserSerializer(ModelSerializer):
    """作者白名单；用户名唯一性由数据库约束保证。"""

    class Meta:
        model: type[Model] = User
        fields: list[str] = ["id", "username"]
        read_only_fields: list[str] = ["id"]


class TagSerializer(ModelSerializer):
    """标签只暴露id和name，不循环嵌套关联文章。"""

    class Meta:
        model: type[Model] = Tag
        fields: list[str] = ["id", "name"]
        read_only_fields: list[str] = ["id"]


class PostSerializer(ModelSerializer):
    """写入已有作者/标签ID，读取展开对象；不支持嵌套创建关联记录。"""

    # 显式声明author_id，注册期无需等待ORM生成外键的底层标量字段。
    author_id = IntegerField(write_only=True, gt=0)
    tag_ids = Field(list[int], default=list, write_only=True)
    author = NestedField(UserSerializer)
    tags = NestedField(TagSerializer, many=True)

    class Meta:
        model: type[Model] = Post
        fields: list[str] = ["id", "title", "content", "author_id", "tag_ids", "author", "tags"]
        read_only_fields: list[str] = ["id"]

    def validate_tag_ids(self, value: object) -> list[int]:
        """拒绝非正整数和重复标签，避免无意重复绑定。"""
        if not isinstance(value, list):
            raise ValidationError({"tag_ids": ["必须是标签ID列表。"]})
        ids: list[int] = []
        for item in value:
            if not isinstance(item, int) or item <= 0:
                raise ValidationError({"tag_ids": ["标签ID必须是正整数。"]})
            ids.append(item)
        if len(set(ids)) != len(ids):
            raise ValidationError({"tag_ids": ["标签ID不能重复。"]})
        return ids

    async def create(self, data: dict[str, object]) -> Post:
        """创建文章和标签关联共享一个事务。"""
        return await self._write(None, data)

    async def update(self, instance: object, data: dict[str, object]) -> Post:
        """PATCH省略关联不修改；空列表清空；列表替换全部标签。"""
        if not isinstance(instance, Post):
            raise TypeError("PostSerializer只更新Post实例")
        return await self._write(instance, data)

    async def _write(self, instance: Post | None, data: dict[str, object]) -> Post:
        """先验证引用，再保存；所有查询、写入和中间表操作使用同一连接。"""
        values: dict[str, object] = dict(data)
        tag_ids: list[int] | None = (
            self.validate_tag_ids(values.pop("tag_ids")) if "tag_ids" in values else None
        )
        async with in_transaction() as connection:
            if (
                "author_id" in values
                and not await User.filter(id=values["author_id"]).using_db(connection).exists()
            ):
                raise ValidationError({"author_id": ["作者不存在。"]})
            tags: list[Tag] = []
            if tag_ids is not None:
                tags = await Tag.filter(id__in=tag_ids).using_db(connection).order_by("id")
                if len(tags) != len(tag_ids):
                    raise ValidationError({"tag_ids": ["存在未找到的标签。"]})
            post: Post
            if instance is None:
                post = Post(**values)
                await post.save(using_db=connection, force_create=True)
            else:
                # 使用事务中的新实例，不让回滚后旧对象残留未提交的内存字段值。
                post = await Post.filter(id=instance.pk).using_db(connection).get()
                if values:
                    post.update_from_dict(values)
                    await post.save(using_db=connection, update_fields=list(values))
            if tag_ids is not None:
                await post.tags.clear(using_db=connection)
                if tags:
                    await post.tags.add(*tags, using_db=connection)
            return post


class UserViewSet(ModelViewSet[User]):
    """作者CRUD；拒绝删除仍被文章引用的作者。"""

    serializer_class: ClassVar[type[Serializer]] = UserSerializer

    def get_queryset(self) -> QuerySet[User]:
        """请求内构造查询，不在导入时连接数据库。"""
        return User.all().order_by("id")

    async def perform_destroy(self, instance: User) -> None:
        """业务409说明原因，数据库RESTRICT同时保证作者引用不悬空。"""
        async with in_transaction() as connection:
            if await Post.filter(author_id=instance.pk).using_db(connection).exists():
                raise Conflict("用户仍有文章，请先转移作者或删除文章。")
            await instance.delete(using_db=connection)


class TagViewSet(ModelViewSet[Tag]):
    """标签CRUD；删除标签由数据库清理中间表，文章仍保留。"""

    serializer_class: ClassVar[type[Serializer]] = TagSerializer

    def get_queryset(self) -> QuerySet[Tag]:
        """仅返回标签，不自动循环展开文章。"""
        return Tag.all().order_by("id")


class PostViewSet(ModelViewSet[Post]):
    """文章CRUD复用框架，关联写入交给PostSerializer扩展点。"""

    serializer_class: ClassVar[type[Serializer]] = PostSerializer

    def get_queryset(self) -> QuerySet[Post]:
        """NestedField会批量预加载作者与标签，不在同步输出时查询。"""
        return Post.all().order_by("id")

    @action(
        detail=False,
        permission_classes=[IsAdminUser],
        throttle_classes=[ScopedRateThrottle],
        throttle_scope="statistics",
        response_model=dict[str, int],
        summary="管理员统计文章数量",
    )
    async def statistics(self) -> dict[str, int]:
        """普通用户403；管理员统计独立限流。"""
        return {"total": await self.get_queryset().count()}


class PostOverview(AdminPage):
    """统计全局数据，表格按关键词及标签状态筛选；不代表作者隔离。"""

    title: ClassVar[str] = "文章数据概览"
    label: ClassVar[str | None] = "内容管理/数据概览"
    icon: ClassVar[str] = "DataAnalysis"
    description: ClassVar[str] = "查看用户、文章和标签统计，筛选文章，并体验页面级操作。"
    stats: ClassVar[tuple[PageStat, ...]] = (
        PageStat("users", "用户总数"),
        PageStat("posts", "文章总数"),
        PageStat("tags", "标签总数"),
    )
    columns: ClassVar[tuple[PageColumn, ...]] = (
        PageColumn("id", "ID", sortable=True),
        PageColumn("title", "文章标题", sortable=True),
        PageColumn("author", "作者"),
        PageColumn("tags", "标签"),
    )
    filters: ClassVar[tuple[PageFilter, ...]] = (
        PageFilter("tagged", "标签状态", (("yes", "有标签"), ("no", "无标签"))),
    )
    actions: ClassVar[tuple[PageAction, ...]] = (
        PageAction(
            "add_sample",
            "新增示例文章",
            icon="Plus",
            confirmation="确认新增一篇示例文章？缺少演示作者和标签时会一并创建。",
        ),
    )

    async def get_data(self, request: Request, query: PageQuery) -> PageResult:
        """查询参数已校验，业务显式应用筛选、排序、分页和关联预加载。"""
        queryset: QuerySet[Post] = Post.all()
        if query.search:
            queryset = queryset.filter(title__icontains=query.search)
        if value := query.filters.get("tagged"):
            queryset = queryset.filter(tags__id__isnull=value == "no").distinct()
        total: int = await queryset.count()
        posts: list[Post] = (
            await queryset.order_by(query.ordering or "-id", "id")
            .offset((query.page - 1) * query.page_size)
            .limit(query.page_size)
            .prefetch_related("author", "tags")
        )
        return PageResult(
            stats={
                "users": await User.all().count(),
                "posts": await Post.all().count(),
                "tags": await Tag.all().count(),
            },
            rows=[
                {
                    "id": post.id,
                    "title": post.title,
                    "author": post.author.username,
                    "tags": [tag.name for tag in post.tags],
                }
                for post in posts
            ],
            total=total,
        )

    async def run_action(self, request: Request, name: str, query: PageQuery) -> str:
        """页面操作自行管理事务；不自动调用普通Serializer或ModelAdmin钩子。"""
        if name != "add_sample":
            raise NotFound("操作不存在。")
        async with in_transaction() as connection:
            user: User | None = await User.filter(username="page-demo").using_db(connection).first()
            if user is None:
                user = await User.create(username="page-demo", using_db=connection)
            tag: Tag | None = await Tag.filter(name="数据页示例").using_db(connection).first()
            if tag is None:
                tag = await Tag.create(name="数据页示例", using_db=connection)
            post: Post = await Post.create(
                title="自定义页面示例文章",
                content="由页面级POST操作创建。",
                author_id=user.id,
                using_db=connection,
            )
            await post.tags.add(tag, using_db=connection)
        return "已新增示例文章，可在模型管理中继续编辑。"


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    """应用持有唯一数据库生命周期；内存库重启清空，仅演示时自动建表。"""
    async with RegisterTortoise(
        app=app,
        db_url="sqlite://:memory:",
        modules={"models": [__name__]},
        generate_schemas=True,
    ):
        yield


app: FastAPI = FastAPI(title="FRF User / Post / Tag Demo", lifespan=lifespan)
# 为便于连续操作关联流程，默认100/min；修改速率后重启即可体验更低限额。
configure(
    default_authentication_classes=[DemoAuthentication],
    default_permission_classes=[IsAuthenticated],
    default_throttle_classes=[UserRateThrottle],
    default_throttle_rates={"user": "100/min", "statistics": "2/min"},
)
router: DefaultRouter = DefaultRouter()
# 仅给Swagger提供令牌输入框，凭证仍由DemoAuthentication验证。
security: HTTPBearer = HTTPBearer(auto_error=False, scheme_name="DemoBearer")
router.register("users", UserViewSet, basename="user", dependencies=[Depends(security)])
router.register("tags", TagViewSet, basename="tag", dependencies=[Depends(security)])
router.register("posts", PostViewSet, basename="post", dependencies=[Depends(security)])
app.include_router(router)


# 后台复用同一模型和数据库生命周期；其表单使用author/tags关系名称。
admin: AdminRouter = AdminRouter(prefix="/admin", title="FRF 入门后台")
admin.register(
    User,
    slug="users",
    admin=ModelAdmin(
        label="用户",
        icon="UserFilled",
        fields=("id", "username"),
        list_display=("id", "username"),
        search_fields=("username",),
        label_field="username",
    ),
)
admin.register(
    Tag,
    slug="tags",
    admin=ModelAdmin(
        label="内容管理/标签",
        icon="CollectionTag",
        fields=("id", "name"),
        list_display=("id", "name"),
        search_fields=("name",),
        label_field="name",
    ),
)
admin.register(
    Post,
    slug="posts",
    admin=ModelAdmin(
        label="内容管理/文章",
        icon="Document",
        fields=("id", "title", "content", "author", "tags"),
        list_display=("id", "title", "author", "tags"),
        list_editable=("title", "author"),
        search_fields=("title", "content"),
        list_filter=("author", "tags"),
        ordering=("-id", "title"),
        label_field="title",
        field_options={
            "title": FieldOptions(label="标题"),
            "content": FieldOptions(label="正文", widget="textarea"),
            "author": FieldOptions(label="作者"),
            "tags": FieldOptions(label="标签"),
        },
    ),
)
admin.register_page("post-overview", page=PostOverview)
app.include_router(admin)
```

## 调用 API

下列命令适用于新启动、尚无数据的 Demo。先创建作者和标签，再创建文章。示例ID均为1；已有数据时请使用响应中的实际ID。

```bash
curl -X POST http://127.0.0.1:8000/users/ \
  -H 'Authorization: Bearer admin-demo' \
  -H 'Content-Type: application/json' \
  -d '{"username":"alice"}'

curl -X POST http://127.0.0.1:8000/tags/ \
  -H 'Authorization: Bearer admin-demo' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Python"}'

curl -X POST http://127.0.0.1:8000/posts/ \
  -H 'Authorization: Bearer admin-demo' \
  -H 'Content-Type: application/json' \
  -d '{"title":"第一篇文章","content":"Hello FRF","author_id":1,"tag_ids":[1]}'

curl http://127.0.0.1:8000/posts/ \
  -H 'Authorization: Bearer admin-demo'

curl -X PATCH http://127.0.0.1:8000/posts/1/ \
  -H 'Authorization: Bearer admin-demo' \
  -H 'Content-Type: application/json' \
  -d '{"title":"修改标题","tag_ids":[]}'

curl http://127.0.0.1:8000/posts/statistics/ \
  -H 'Authorization: Bearer admin-demo'
```

创建文章返回201，响应展开关联对象，例如：

```json
{
  "id": 1,
  "title": "第一篇文章",
  "content": "Hello FRF",
  "author": {"id": 1, "username": "alice"},
  "tags": [{"id": 1, "name": "Python"}]
}
```

### CRUD 路由

将表格中的 `posts` 替换为 `users` 或 `tags` 可操作对应资源；三者均由 ModelViewSet 自动生成。

| 方法 | 路径 | 行为 |
| --- | --- | --- |
| GET | `/posts/` | 查询列表；当前Demo未启用普通API分页，返回数组 |
| POST | `/posts/` | 创建文章，返回201 |
| GET | `/posts/{pk}/` | 查看详情 |
| PUT | `/posts/{pk}/` | 完整更新 |
| PATCH | `/posts/{pk}/` | 局部更新 |
| DELETE | `/posts/{pk}/` | 删除，返回204且无响应体 |
| GET | `/posts/statistics/` | 集合Action，返回文章总数，仅管理员可用 |

PATCH 省略字段表示保持原值；`tag_ids: []` 清空标签，列表替换全部标签，`null` 不允许。作者必须存在，重复或无效标签返回400；作者仍有文章时删除返回409。

### 认证、权限和限流

- 不带令牌访问普通API返回401；`user-demo` 与 `admin-demo` 都可以操作普通CRUD。Demo未做作者隔离，二者共享数据。
- 统计Action仅允许 `admin-demo`；`user-demo` 调用返回403。`detail=False` 表示集合行为；`detail=True` 的自定义行为会绑定单条记录并先执行对象权限。
- 全局 `configure(...)` 必须在创建 Router 前调用。有效配置优先级为 Action → ViewSet → 全局默认；显式空策略列表可关闭对应策略。
- 普通API按身份100次/分钟；统计接口独立2次/分钟，超限返回429及可用的 Retry-After。内置计数仅在同一进程内共享，不是分布式限流。
- 固定令牌仅用于演示，生产中应继承认证器验证真实凭证并返回 Identity；框架不提供登录账户系统、JWT签发或撤销。

### Serializer 与关联保存

ModelSerializer 的 `Meta.model` 绑定 ORM 模型，`Meta.fields` 显式限制公开字段；只读字段拒绝写入，只写字段不出现在响应中。ModelViewSet 绑定 Serializer 并实现 `get_queryset()`，DefaultRouter 注册后提供标准CRUD。查询在请求内创建，应用自己管理 ORM 生命周期。

Demo 的 `author_id`、`tag_ids` 是输入字段，`author`、`tags` 通过 NestedField 输出展开对象。关联写入由 PostSerializer 的 create/update 扩展实现，引用检查、文章保存及中间表写入共用同一事务。NestedField 本身仅用于输出，不能据此认为框架支持任意嵌套写入。

需要增加业务校验时，可参考代码中的 `validate_tag_ids`；多次写入业务通过 `in_transaction()` 显式控制事务。同步序列化阶段不应临时发起异步数据库查询。

## 普通 API 的常用扩展

以下都是在完整Demo基础上的**可选改法**。涉及ViewSet的配置放在`router.register(...)`之前，不要在注册后修改声明；示例默认普通API仍返回数组，后台分页不代表普通API已经分页。

### 分页、搜索、过滤与排序

```python
from fastapirestframework.pagination import PageNumberPagination

# 保留原PostViewSet，在其后声明扩展子类，继承Serializer、权限及统计Action。
class QueryPostViewSet(PostViewSet):
    pagination_class = PageNumberPagination
    filterset_fields = {"id": ["exact", "in"], "title": ["exact", "icontains"]}
    search_fields = ("title", "content")
    ordering_fields = ("id", "title")
    ordering = ("-id",)

# 用这一行替换原来的posts注册，不能重复注册同一路由。
# router.register("posts", QueryPostViewSet, basename="post", dependencies=[Depends(security)])
```

配置后可请求`/posts/?page=1&page_size=20&search=FRF&ordering=-id`，或`/posts/?title__icontains=接口`。分页响应为`count/next/previous/results`，不再是数组。默认每页20、最大100；也可使用`LimitOffsetPagination`，参数为`limit/offset`。过滤仅允许显式声明的本层标量，不开放任意ORM关联表达式。超出最后页返回404，非法分页大小返回422。

### Serializer 的输入、校验与计算输出

| 声明或方法 | 使用方式 |
| --- | --- |
| `Meta.model / fields` | 绑定模型并限制公开字段；建议显式白名单 |
| `Meta.read_only_fields / write_only_fields` | 控制只读、只写；未知字段和只读输入拒绝 |
| `validate_title(value)` | 字段级同步或异步校验，可返回规范化后的值 |
| `validate(data)` | 跨字段同步或异步业务校验 |
| `create(data) / update(instance, data)` | 自定义持久化；关联写入见完整Demo的PostSerializer |
| `SerializerMethodField` | 只读计算字段，编写对应`get_字段名`方法 |
| `NestedField` | 只读关联输出；关联依赖提前加载，不执行隐式数据库查询 |

直接使用Serializer时，先`await serializer.is_valid(raise_exception=True)`，再`await serializer.save()`；需要输出时使用`await serializer.serialize()`。初始化支持instance/data/partial/context/many；`many=True`用于列表输出，不用于批量输入保存。

### ViewSet、Action 与数据范围

标准读写使用`ModelViewSet`，只读接口可用`ReadOnlyModelViewSet`；也能组合`GenericViewSet`与CRUD Mixin。`get_queryset()`构造当前请求的数据范围，`perform_create/perform_update/perform_destroy`接入业务保存逻辑。不要在模块导入时调用尚未绑定数据库的`Model.all()`。

完整Demo的`@action(detail=False)`生成集合统计接口。`detail=True`适用于单条文章操作，执行前会通过`get_object()`及对象权限；业务中用`await self.get_object()`取得同一目标。Action显式认证、权限及限流配置优先于ViewSet和全局配置，显式空列表禁用对应策略。

普通FRF的`@action`、后台ModelAdmin的`@action`、数据页的`PageAction`是三个不同入口，不混用装饰器或方法签名。列表数据隔离应在QuerySet中完成，不能依赖逐条对象权限。外部身份验证、用户系统和事务边界由应用负责。

## 自动管理后台 frfadmin

`AdminRouter.register(Model, slug=..., admin=ModelAdmin(...))` 根据注册模型生成界面，无需为每个模型编写 Vue 页面。已有应用只需添加 Demo 末尾的后台注册部分，复用原有模型与数据库生命周期。

| 常用配置 | 用途 |
| --- | --- |
| `label`、`icon` | `/`分组的导航路径与Element Plus图标名，未配图标时使用Grid |
| `fields`、`readonly_fields` | 表单及详情公开字段、只读字段 |
| `list_display` | 列表列及顺序 |
| `list_editable` | 双击可编辑的列表字段，使用列表编辑栏保存或取消 |
| `search_fields`、`list_filter` | 搜索字段、允许精确筛选的字段 |
| `ordering` | 默认排序与允许切换的字段 |
| `label_field` | 关联候选项的可读名称 |
| `field_options` | 中文标签、帮助文字、占位文字、textarea等控件 |
| `page_size` | 后台每页条数，默认20 |

后台支持搜索、筛选、排序、关联远程选择及快捷保存；分页选项为10、20、100、200、500、1000。导航图标采用 UserFilled / Document / CollectionTag。操作图标悬停显示名称，详情完整内容不重复提示，列表文字实际溢出才显示全文提示。

后台还提供 ModelAdmin 类继承与业务钩子、display 计算列、action 批量行为、Fieldset 动态分组、FK Inline、区间/空值/自定义筛选和浏览器本地保存查询等扩展点。本入门Demo仅启用代码中明确声明的配置，未配置全部扩展。

后台输入关系名为 `author` 和 `tags`，普通Demo API输入为 `author_id` 和 `tag_ids`，两套输入契约不同。后台使用ModelAdmin钩子，不自动调用普通PostSerializer的自定义钩子；新增业务约束需要在对应入口实施。

当前后台**没有内置登录**，独立于普通API的认证权限限流；应由部署应用决定访问保护。关联快捷保存为独立事务，取消主表单不撤销已快捷保存的关联记录。


### 后台扩展配置与钩子

已有三模型时，可以用子类替换原来的`ModelAdmin(...)`配置；同一个模型不要重复注册。

```python
from fastapirestframework.admin import Fieldset, InlineModelAdmin, ModelAdmin, display

class ArticleAdmin(ModelAdmin):
    label: str = "内容管理/文章"
    fields = ("id", "title", "content", "author", "tags")
    list_display = ("id", "title", "author_name", "tags")
    list_editable = ("title",)
    search_fields = ("title", "content")
    fieldsets = (
        Fieldset("基本信息", ("title", "author")),
        Fieldset("正文与标签", ("content", "tags"), collapsed=True),
    )

    @display(description="作者名称", prefetch_related=("author",))
    def author_name(self, obj: Model) -> str:
        if not isinstance(obj, Post):
            raise TypeError("需要Post实例")
        return obj.author.username

class AuthorAdmin(ModelAdmin):
    label: str = "用户"
    fields = ("id", "username")
    inlines = (InlineModelAdmin(Post, "author", fields=("id", "title", "content", "tags")),)

# 替换原有注册：
# admin.register(Post, slug="posts", admin=ArticleAdmin)
# admin.register(User, slug="users", admin=AuthorAdmin)
```

`Fieldset`是表单字段分区，`label`中的`/`是导航分组，两者独立。`InlineModelAdmin`可在用户表单内维护文章；不支持嵌套Inline、反向M2M或跨数据库连接。

| 扩展点 | 职责 |
| --- | --- |
| 同步`get_queryset(request)` | 限制列表、详情、修改、删除、批量及关联候选的数据范围 |
| 同步`get_fields/get_readonly_fields/get_fieldsets` | 根据请求和对象缩小表单字段、调整只读和分区 |
| 异步`validate(request, data, obj, connection)` | 校验业务输入，返回字段字典或抛ValidationError |
| 异步`save_model/save_related/delete_model` | 接入保存/关联/删除；所有查询和写入沿用传入事务连接 |
| `@display` | 声明计算列；关联依赖通过prefetch_related预加载 |
| 后台`@action`与`ActionResult` | 自定义批量行为；必须列入actions，并使用传入QuerySet范围和事务 |
| `FilterSpec / SimpleListFilter` | 显式区间、空值、自定义筛选；不接受任意ORM表达式 |

后台批量选择显式ID，单次1–1000条，必须确认；`actions=()`关闭批量行为。列表修改、父表及Inline分别整笔事务保存，失败回滚。保存查询只存当前浏览器localStorage，不随账号同步；同一路径/模型最多20个。

## 后台导航分组

```python
# 模型页：参数配置或ModelAdmin子类均可。
# admin.register(Post, slug="posts", admin=ModelAdmin(label="内容管理/文章"))

class ArticleOverview(PostOverview):
    label: ClassVar[str | None] = "内容管理/报表/文章概览"
    title: ClassVar[str] = "文章数据概览"

# 放在app.include_router(admin)前注册：
# admin.register_page("article-overview", page=ArticleOverview)
```

导航显示“内容管理 → 报表 → 文章概览”。相同完整路径的分组合并，模型页和自定义页可以处于同一组；中间分组点击展开/收起，最后一级点击进入页面。无`/`时仍为顶层页面。当前页祖先自动展开，整栏收起后通过图标子菜单访问。

模型`label=None`回退模型类名；页面`label=None`回退title，单独设置label时title继续作为内容标题。各段去掉两侧空白；空字符串、开头/结尾`/`、连续`//`注册时报配置错误。`/`为分隔符，没有转义语法。若要两个并列叶子，应分别配置两条路径，不用尖括号或竖线表示分支。

元数据`nav_path`给出完整路径，模型label输出叶子名称用于新增/删除/搜索文案。分组不改变slug、API路径或数据权限；菜单身份使用类型+slug，模型与页面同slug也不会覆盖。取消未保存确认会保留旧页面、草稿和高亮。折叠状态不持久化，刷新会重新初始化。

## 自定义数据页面

完整Demo中的`PostOverview`不绑定ORM资源，可以从数据库聚合、外部服务或计算结果读取数据；它不会自动拥有CRUD。侧栏路径为“内容管理 → 数据概览”。

1. 打开数据概览，查看用户、文章、标签统计。
2. 点击“新增示例文章”图标并确认，生成演示数据并刷新；取消不写入。
3. 输入关键词、选择有标签/无标签后点击查询，可使用排序与分页。
4. 到文章模型页修改，再回概览刷新查看变化。

| 配置或钩子 | 用途 |
| --- | --- |
| `title / label / icon / description` | 内容标题、导航路径、图标和说明 |
| `stats: tuple[PageStat, ...]` | 统计卡片键和名称 |
| `columns: tuple[PageColumn, ...]` | 公开表格列；sortable声明可排序列 |
| `filters: tuple[PageFilter, ...]` | 固定枚举或动态候选筛选 |
| `actions: tuple[PageAction, ...]` | 页面级或行级按钮 |
| `get_data(request, query)` | 返回PageResult(stats/rows/total)，业务自己筛选、排序与分页 |
| `run_action(request, name, query)` | 兼容无参数页面操作，返回反馈文字 |

声明页面类后用`admin.register_page("slug", page=PageClass)`注册，必须先于`app.include_router(admin)`；注册的是类，每次请求新建实例。未注册名称不能通过请求调用其他方法。声明的卡片和列是输出白名单，不能替代权限。

PageQuery含page/page_size/search/ordering/filters；后台页大小固定允许10、20、100、200、500、1000，默认20。PageResult.rows只返回当前页，total是过滤后总数；业务不得返回未求值QuerySet或ORM实例。页面操作收到已应用查询，未点查询的输入草稿不改变页面操作范围。

## 行操作、参数表单与动态候选

下例是**可选扩展**，没有默认加入入门app。先复制完整Demo，再将此段插入其最后一行`app.include_router(admin)`之前；复用已有User/Post/Tag、PostSerializer、Request、ClassVar等定义，不另开数据库生命周期。

它增加“内容管理 → 工具 → 文章操作台”：作者下拉实时查数据库，列表每行可修改标题、作者和标签；参数表单自动回显，失败保留输入。写入时**主动调用**Demo的PostSerializer，复用关联校验与事务，而非框架自动调用。

```python
from collections.abc import Mapping
from pydantic import BaseModel, Field as ParameterField, JsonValue
from fastapirestframework.admin import PageOption, PageOptionQuery, PageOptions


class PostParameters(BaseModel):
    title: str = ParameterField(min_length=1, max_length=200, title="文章标题")
    author_id: int = ParameterField(gt=0, title="作者")
    tag_ids: list[int] = ParameterField(default_factory=list, title="标签")


class PostToolsPage(AdminPage):
    """只展示本例已允许的数据；真实项目须在行与候选查询中加入权限范围。"""

    title: ClassVar[str] = "文章操作台"
    label: ClassVar[str | None] = "内容管理/工具/文章操作台"
    row_key: ClassVar[str | None] = "id"
    option_sources: ClassVar[tuple[str, ...]] = ("authors", "tags")
    columns: ClassVar[tuple[PageColumn, ...]] = (
        PageColumn("id", "ID", sortable=True),
        PageColumn("title", "文章标题", sortable=True),
    )
    filters: ClassVar[tuple[PageFilter, ...]] = (
        PageFilter("author", "作者", options="authors"),
    )
    actions: ClassVar[tuple[PageAction, ...]] = (
        PageAction(
            "edit_post", "修改文章", icon="Edit", detail=True,
            input_model=PostParameters,
            option_fields={"author_id": "authors", "tag_ids": "tags"},
            confirmation="确认保存这篇文章的标题、作者和标签？",
        ),
    )

    async def get_data(self, request: Request, query: PageQuery) -> PageResult:
        """框架校验参数，业务显式实现范围、筛选及数据库分页。"""
        queryset: QuerySet[Post] = Post.all()
        if query.search:
            queryset = queryset.filter(title__icontains=query.search)
        if author := query.filters.get("author"):
            queryset = queryset.filter(author_id=int(author))
        total: int = await queryset.count()
        posts: list[Post] = await queryset.order_by(query.ordering or "-id", "id").offset(
            (query.page - 1) * query.page_size
        ).limit(query.page_size)
        return PageResult(rows=[{"id": post.id, "title": post.title} for post in posts], total=total)

    async def get_row(self, request: Request, row_id: str) -> dict[str, JsonValue]:
        """重新从服务端加载目标，不接受客户端提交整行数据。"""
        if not row_id.isascii() or not row_id.isdecimal() or len(row_id) > 19:
            raise NotFound("文章不存在。")
        if not 0 < int(row_id) <= 2**63 - 1 or str(int(row_id)) != row_id:
            raise NotFound("文章不存在。")
        post: Post | None = await Post.filter(id=int(row_id)).prefetch_related("author", "tags").first()
        if post is None:
            raise NotFound("文章不存在。")
        return {"id": post.id, "title": post.title, "author_id": post.author.id,
                "tag_ids": [tag.id for tag in post.tags]}

    async def get_action_initial(
        self, request: Request, name: str, query: PageQuery,
        row: Mapping[str, JsonValue] | None = None,
    ) -> dict[str, JsonValue]:
        if row is None:
            raise NotFound("文章不存在。")
        return {key: row[key] for key in ("title", "author_id", "tag_ids")}

    async def get_options(
        self, request: Request, source: str, query: PageOptionQuery,
        row: Mapping[str, JsonValue] | None = None,
    ) -> PageOptions:
        """精确回显忽略搜索分页；两条分支都应受业务可见范围约束。"""
        queryset: QuerySet[User] | QuerySet[Tag]
        if source == "authors":
            queryset = User.all()
            name_field: str = "username"
        elif source == "tags":
            queryset = Tag.all()
            name_field = "name"
        else:
            raise NotFound("候选来源不存在。")
        if query.values:
            # 本例主键为正整数，拒绝非规范ID以免回显与提交身份不一致。
            ids: list[int] = []
            for value in query.values:
                if value.isascii() and value.isdecimal() and len(value) <= 19:
                    numeric: int = int(value)
                    if 0 < numeric <= 2**63 - 1 and str(numeric) == value:
                        ids.append(numeric)
            queryset = queryset.filter(id__in=ids)
        elif query.search:
            queryset = queryset.filter(**{f"{name_field}__icontains": query.search})
        total: int = await queryset.count()
        queryset = queryset.order_by("id")
        if not query.values:
            queryset = queryset.offset((query.page - 1) * query.page_size).limit(query.page_size)
        records: list[User] | list[Tag] = await queryset
        return PageOptions(items=[PageOption(value=str(item.id), label=(
            item.username if isinstance(item, User) else item.name
        )) for item in records], total=total)

    async def execute_action(
        self, request: Request, name: str, query: PageQuery,
        data: dict[str, object], row: Mapping[str, JsonValue] | None = None,
    ) -> str:
        if name != "edit_post" or row is None:
            raise NotFound("操作不存在。")
        post: Post | None = await Post.get_or_none(id=row["id"])
        if post is None:
            raise NotFound("文章不存在。")
        # 主动复用入门Demo的业务Serializer，其引用检查及关联保存共用事务。
        serializer: PostSerializer = PostSerializer(instance=post, data=data, partial=True)
        await serializer.is_valid(raise_exception=True)
        await serializer.save()
        return "文章已更新。"


admin.register_page("post-tools", page=PostToolsPage)
```

先在数据概览新增一篇示例文章，再进入文章操作台。点击行内修改图标，选择作者/标签并保存；标签多选清空会移除全部标签，作者为必填且不可空。可新增第二名作者、更多标签观察动态候选刷新，不需改页面配置。

### 行身份与参数契约

- `row_key`是稳定行键，不用行号或当前筛选猜测目标；字符串/整数键在列表中统一为字符串，当前页必须唯一。`get_row()`按授权范围重新加载目标，找不到或不可见抛NotFound，不接收客户端整行对象。
- `PageAction(detail=True)`是行操作，默认False是页面操作；两者均可指定input_model。行ID通过POST body的row_id传递，特殊字符不拼进URL路径。
- input_model使用Pydantic BaseModel，生成表单并执行提交校验；get_action_initial用于当前值回显，execute_action接收验证后的data及真实row。无参数页面操作继续兼容run_action。
- 常见字符串、数值、布尔、枚举、日期时间、JSON对象/数组可渲染；Field的title/description/default用于展示和默认值。多行字符串可设`json_schema_extra={"widget":"textarea"}`。暂不支持字段别名、复杂联合或任意JSON Schema组件。
- 无参数操作先确认，有参数操作展示表单及确认说明；取消不提交，未保存关闭需确认。成功刷新当前列表，加载期间阻止重复执行及切换导航。行操作少于4项直接展示，达到4项显示前三项及更多菜单。

### 动态候选与级联

`option_sources`列出允许的来源。`get_options()`返回PageOptions(items=[PageOption(value="稳定ID", label="名称")], total=...)；字符串ID避免浏览器大整数精度丢失。

| 查询模式 | 提供者应如何处理 |
| --- | --- |
| 普通搜索 | 按query.search搜索，query.page从1开始，query.page_size固定20，返回当前页及过滤后total |
| 已选回显 | query.values非空时按ID精确查询；忽略搜索分页，仅返回仍可见的候选，最多1000个 |
| 行关联 | row是服务端重新加载的目标，可据此限制候选范围 |

`PageFilter(..., options="authors")`将候选用作筛选。级联可声明`depends_on=("parent_filter",)`，只能引用前面已声明的筛选；父项变化清空子项，候选查询的filters携带相关父值。来源仍须主动执行范围约束，不能信任传入filters就是授权结果。筛选自身是单个字符串值，不支持多选筛选。

`PageAction(option_fields={"author_id":"authors", "tag_ids":"tags"})`将参数字段映射为远程单/多选。候选必须是字符串/整数或其数组；严格整数模型需自行处理选择器提交的字符串ID。可空单选清空为null，多选清空为[]。提交前会重新检查来源、候选存在性、可见性和重复ID；打开表单后目标被删或禁用，不能靠旧标签绕过校验。操作参数字段之间暂不支持级联。

候选有搜索、加载更多、跨页已选项回显；普通筛选只能访问筛选声明的来源，操作只能访问该action映射的来源。业务须在get_row/get_options及实际写入中维护权限和事务；重新加载目标并不自动锁定记录或防止并发修改。

### 自定义页面 HTTP 接口

相对后台前缀（默认/admin）：

| 方法 | 路径 | 行为 |
| --- | --- | --- |
| GET | `/api/meta` | 模型与页面声明，含导航路径 |
| GET | `/api/_pages/{slug}` | 统计及当前页数据 |
| GET | `/api/_pages/{slug}/actions/{name}/form` | 参数字段、默认值和目标当前值 |
| GET | `/api/_pages/{slug}/options/{source}` | 搜索、分页或精确回显候选 |
| POST | `/api/_pages/{slug}/actions/{name}` | 执行操作，返回message |

GET接受page/page_size/search/ordering/filters，filters是JSON对象字符串。表单可带row_id；候选增加option_search/option_page及重复value，操作候选还带action及行操作row_id。POST中filters是对象，操作参数在data内，不允许额外顶层字段。

```json
{"row_id":"1","data":{"title":"修改标题","author_id":1,"tag_ids":[]}}
```

参数或候选错误通常400，HTTP请求结构错误422，未知页面/操作/目标404；不会把任意业务方法暴露为接口。后台无登录，普通FRF API的认证策略不自动保护这些端点。

## MCP 单表示例与运行入口

仓库另有`examples/mcp/app.py`，只有MCPConnection业务表，工具目录、开关、配置和同步信息使用mock内存。它演示逐行启用/禁用/参数配置/模拟调用，页面级带参数同步，以及动态MCP和工具候选；同名工具按连接ID隔离。不是MCP协议服务端，不依赖真实SDK，也不向远端发送停用命令。

```bash
make demo DEMO=examples.mcp.app:app PORT=8772
```

打开`http://127.0.0.1:8772/admin/`，导航为“大模型 → MCP连接”和“大模型 → MCP → 工具管理”。禁用工具后可用目录过滤掉它，实际调用时再次检查，禁用返回409；配置/开关单进程共享，重启重置。此示例在源码仓库中，安装wheel不会额外得到examples目录。

| 源码仓库命令 | 用途 |
| --- | --- |
| `make demo` | 启动完整User/Post/Tag入门例子；支持HOST/PORT覆盖 |
| `make demo DEMO=examples.admin.app:app` | 体验更多ModelAdmin钩子、Inline和批量等配置 |
| `make demo DEMO=examples.mcp.app:app PORT=8772` | 体验MCP单表工具管理 |
| `make build` | 构建并核对当前版本wheel，包含预构建后台资源与说明元数据 |

使用wheel运行后台无需Node/npm；只有修改前端源码才需要前端构建。make命令属于源码仓库开发入口，不是安装包内的命令。

## 常见问题与能力边界

| 问题 | 说明 |
| --- | --- |
| 安装0.0.2后导入AdminPage失败 | 0.0.2不含该功能；升级到fastapirestframework-tortoise==0.0.7后使用本页Demo |
| 只需要普通API | 不注册AdminRouter即可；已有应用自己管理FastAPI和ORM生命周期 |
| 导航有分组，标题为何只有最后一级 | nav_path保存完整分组，模型label输出叶子供CRUD文案使用；自定义页title可独立设置 |
| 为什么后台与普通API输入不同 | 后台自动表单使用author/tags关系名，入门API使用author_id/tag_ids；ModelAdmin不会自动接入普通Serializer钩子 |
| 为什么统计与筛选后的数量不同 | 入门概览统计全局数量，列表total是筛选后的数量；业务可自行改为同一查询范围 |
| 复杂页面能否直接配置 | 当前支持统计/表格/筛选/操作表单，尚无任意Vue组件、图表、实时日志、拖拽和流程编排 |
| 数据是否持久化 | 入门及MCP Demo均为SQLite内存库；MCP工具状态另为内存mock，重启清空 |
| 认证是否区分文章作者 | 演示令牌与User作者资料无绑定；需业务限制QuerySet及关联数据范围 |

数据库、迁移、真实凭证验证、后台访问保护与业务事务由应用负责。框架不提供账户系统、JWT签发/撤销、分布式限流或任意关联嵌套写入。NestedField只读，作者/标签写入来自Demo显式业务扩展。

本文入门例子及自定义页以SQLite内存库验收；历史普通框架曾验证MySQL 8.3.0，不代表本轮全部后台组合已验证。PostgreSQL、其他依赖组合、并发压力及其他浏览器未在本轮验收，不扩大支持范围。

发行内容为Python框架、预构建后台资源和本页Markdown元数据；完整入门代码直接嵌在本页，不依赖安装包内的examples。本版为 0.0.7，包含保存并继续编辑、另存为、删除影响预览和 CSV 导出。后续内容更新需要新版本，现有版本不能覆盖；未验收的sdist不上传。
