chore: 批量优化项目代码，修复多处细节问题

本次提交包含多项优化和修复：
1. 修复CRUD初始化参数传递、搜索参数处理逻辑
2. 更新环境配置中的大模型相关参数
3. 重构部分服务方法命名，统一代码风格
4. 新增多个枚举类型，补充模型关联关系和加载选项
5. 优化查询参数类实现，完善字段校验逻辑
6. 调整Pydantic模型字段注释和类型定义
7. 简化并移除冗余的CRUD方法实现
8. 新增超级管理员权限装饰器
9. 修复邮件日志模型的租户关联和字段定义

backend/app/api/v1/module_platform/plugin/controller.py

@@ -1,6 +1,6 @@
 from typing import Annotated
 
-from fastapi import APIRouter, Body, Depends, Path
+from fastapi import APIRouter, Body, Depends, Path, Query
 from fastapi.responses import JSONResponse
 from fastapi_cache import FastAPICache
 from fastapi_cache.decorator import cache
@@ -27,9 +27,13 @@ _PLUGIN_NS = "plugin"
 # ───── 超管：插件 CRUD ─────
 
 
-@PluginRouter.get("/list", summary="插件列表", response_model=ResponseSchema[PageResultSchema[PluginOutSchema]])
+@PluginRouter.get(
+    "/list",
+    summary="插件列表",
+    response_model=ResponseSchema[PageResultSchema[PluginOutSchema]],
+)
 @cache(expire=300, namespace=_PLUGIN_NS)
-async def plugin_list(
+async def plugin_list_controller(
     page: Annotated[PaginationQueryParam, Depends()],
     search: Annotated[PluginQueryParam, Depends()],
     auth: Annotated[AuthSchema, Depends(AuthPermission(["module_platform:plugin:query"]))],
@@ -40,16 +44,27 @@ async def plugin_list(
     参数:
     - page (PaginationQueryParam): 分页查询参数。
     - search (PluginQueryParam): 查询筛选参数。
+    - auth (AuthSchema): 认证信息模型。
 
     返回:
     - JSONResponse: 包含分页插件列表的 JSON 响应。
     """
-    r = await PluginService.page_service(auth, page.page_no, page.page_size, search, page.order_by)
+    r = await PluginService.page_service(
+        auth=auth,
+        page_no=page.page_no,
+        page_size=page.page_size,
+        search=search,
+        order_by=page.order_by,
+    )
     return SuccessResponse(data=r, msg="查询成功")
 
 
-@PluginRouter.get("/detail/{id}", summary="插件详情", response_model=ResponseSchema[PluginOutSchema])
-async def plugin_detail(
+@PluginRouter.get(
+    "/detail/{id}",
+    summary="插件详情",
+    response_model=ResponseSchema[PluginOutSchema],
+)
+async def plugin_detail_controller(
     id: Annotated[int, Path()],
     auth: Annotated[AuthSchema, Depends(AuthPermission(["module_platform:plugin:query"]))],
 ) -> JSONResponse:
@@ -58,15 +73,20 @@ async def plugin_detail(
 
     参数:
     - id (int): 插件 ID。
+    - auth (AuthSchema): 认证信息模型。
 
     返回:
     - JSONResponse: 包含插件详情的 JSON 响应。
     """
-    return SuccessResponse(data=await PluginService.detail_service(auth, id), msg="查询成功")
+    return SuccessResponse(data=await PluginService.detail_service(auth=auth, id=id), msg="查询成功")
 
 
-@PluginRouter.post("/create", summary="创建插件", response_model=ResponseSchema[PluginOutSchema])
-async def plugin_create(
+@PluginRouter.post(
+    "/create",
+    summary="创建插件",
+    response_model=ResponseSchema[PluginOutSchema],
+)
+async def plugin_create_controller(
     data: PluginCreateSchema,
     auth: Annotated[AuthSchema, Depends(AuthPermission(["module_platform:plugin:create"]))],
 ) -> JSONResponse:
@@ -75,17 +95,22 @@ async def plugin_create(
 
     参数:
     - data (PluginCreateSchema): 插件创建参数。
+    - auth (AuthSchema): 认证信息模型。
 
     返回:
     - JSONResponse: 包含创建后的插件详情的 JSON 响应。
     """
-    r = await PluginService.create_service(auth, data)
+    r = await PluginService.create_service(auth=auth, data=data)
     await FastAPICache.clear(namespace=_PLUGIN_NS)
     return SuccessResponse(data=r, msg="创建成功")
 
 
-@PluginRouter.put("/update/{id}", summary="更新插件", response_model=ResponseSchema[PluginOutSchema])
-async def plugin_update(
+@PluginRouter.put(
+    "/update/{id}",
+    summary="更新插件",
+    response_model=ResponseSchema[PluginOutSchema],
+)
+async def plugin_update_controller(
     id: Annotated[int, Path()],
     data: PluginUpdateSchema,
     auth: Annotated[AuthSchema, Depends(AuthPermission(["module_platform:plugin:update"]))],
@@ -96,17 +121,22 @@ async def plugin_update(
     参数:
     - id (int): 插件 ID。
     - data (PluginUpdateSchema): 插件更新参数。
+    - auth (AuthSchema): 认证信息模型。
 
     返回:
     - JSONResponse: 包含更新后的插件详情的 JSON 响应。
     """
-    r = await PluginService.update_service(auth, id, data)
+    r = await PluginService.update_service(auth=auth, id=id, data=data)
     await FastAPICache.clear(namespace=_PLUGIN_NS)
     return SuccessResponse(data=r, msg="更新成功")
 
 
-@PluginRouter.delete("/delete", summary="删除插件", response_model=ResponseSchema[None])
-async def plugin_delete(
+@PluginRouter.delete(
+    "/delete",
+    summary="删除插件",
+    response_model=ResponseSchema[None],
+)
+async def plugin_delete_controller(
     ids: Annotated[list[int], Body()],
     auth: Annotated[AuthSchema, Depends(AuthPermission(["module_platform:plugin:delete"]))],
 ) -> JSONResponse:
@@ -115,11 +145,12 @@ async def plugin_delete(
 
     参数:
     - ids (list[int]): 插件 ID 列表。
+    - auth (AuthSchema): 认证信息模型。
 
     返回:
     - JSONResponse: 删除结果。
     """
-    await PluginService.delete_service(auth, ids)
+    await PluginService.delete_service(auth=auth, ids=ids)
     await FastAPICache.clear(namespace=_PLUGIN_NS)
     return SuccessResponse(msg="删除成功")
 
@@ -127,12 +158,16 @@ async def plugin_delete(
 # ───── 租户：插件市场 ─────
 
 
-@PluginRouter.get("/marketplace", summary="插件市场", response_model=ResponseSchema[PageResultSchema[PluginOutSchema]])
+@PluginRouter.get(
+    "/marketplace",
+    summary="插件市场",
+    response_model=ResponseSchema[PageResultSchema[PluginOutSchema]],
+)
 @cache(expire=600, namespace=_PLUGIN_NS)
-async def marketplace(
+async def plugin_marketplace_controller(
+    auth: Annotated[AuthSchema, Depends(AuthPermission(["module_platform:plugin:query"]))],
     page: Annotated[PaginationQueryParam, Depends()],
-    category: str | None = None,
-    auth: Annotated[AuthSchema, Depends(AuthPermission(["module_platform:plugin:query"]))] = None,
+    category: Annotated[str | None, Query(description="分类筛选")] = None,
 ) -> JSONResponse:
     """
     插件市场
@@ -140,16 +175,21 @@ async def marketplace(
     参数:
     - page (PaginationQueryParam): 分页查询参数。
     - category (str | None): 分类筛选。
+    - auth (AuthSchema): 认证信息模型。
 
     返回:
     - JSONResponse: 包含分页市场插件列表的 JSON 响应。
     """
-    r = await PluginService.marketplace_service(auth, page.page_no, page.page_size, category)
+    r = await PluginService.marketplace_service(auth=auth, page_no=page.page_no, page_size=page.page_size, category=category)
     return SuccessResponse(data=r, msg="查询成功")
 
 
-@PluginRouter.post("/install", summary="安装插件", response_model=ResponseSchema[None])
-async def plugin_install(
+@PluginRouter.post(
+    "/install",
+    summary="安装插件",
+    response_model=ResponseSchema[None],
+)
+async def plugin_install_controller(
     data: PluginInstallSchema,
     auth: Annotated[AuthSchema, Depends(AuthPermission(["module_platform:plugin:install"]))],
 ) -> JSONResponse:
@@ -158,17 +198,22 @@ async def plugin_install(
 
     参数:
     - data (PluginInstallSchema): 安装参数（插件 ID）。
+    - auth (AuthSchema): 认证信息模型。
 
     返回:
     - JSONResponse: 安装结果。
     """
-    await PluginService.install_service(auth, data.plugin_id)
+    await PluginService.install_service(auth=auth, plugin_id=data.plugin_id)
     await FastAPICache.clear(namespace=_PLUGIN_NS)
     return SuccessResponse(msg="安装成功")
 
 
-@PluginRouter.post("/uninstall", summary="卸载插件", response_model=ResponseSchema[None])
-async def plugin_uninstall(
+@PluginRouter.post(
+    "/uninstall",
+    summary="卸载插件",
+    response_model=ResponseSchema[None],
+)
+async def plugin_uninstall_controller(
     data: PluginInstallSchema,
     auth: Annotated[AuthSchema, Depends(AuthPermission(["module_platform:plugin:uninstall"]))],
 ) -> JSONResponse:
@@ -177,17 +222,22 @@ async def plugin_uninstall(
 
     参数:
     - data (PluginInstallSchema): 卸载参数（插件 ID）。
+    - auth (AuthSchema): 认证信息模型。
 
     返回:
     - JSONResponse: 卸载结果。
     """
-    await PluginService.uninstall_service(auth, data.plugin_id)
+    await PluginService.uninstall_service(auth=auth, plugin_id=data.plugin_id)
     await FastAPICache.clear(namespace=_PLUGIN_NS)
     return SuccessResponse(msg="卸载成功")
 
 
-@PluginRouter.post("/toggle", summary="启用/禁用插件", response_model=ResponseSchema[None])
-async def plugin_toggle(
+@PluginRouter.post(
+    "/toggle",
+    summary="启用/禁用插件",
+    response_model=ResponseSchema[None],
+)
+async def plugin_toggle_controller(
     data: PluginInstallSchema,
     auth: Annotated[AuthSchema, Depends(AuthPermission(["module_platform:plugin:toggle"]))],
 ) -> JSONResponse:
@@ -196,31 +246,43 @@ async def plugin_toggle(
 
     参数:
     - data (PluginInstallSchema): 操作参数（插件 ID）。
+    - auth (AuthSchema): 认证信息模型。
 
     返回:
     - JSONResponse: 操作结果。
     """
-    await PluginService.toggle_service(auth, data.plugin_id)
+    await PluginService.toggle_service(auth=auth, plugin_id=data.plugin_id)
     await FastAPICache.clear(namespace=_PLUGIN_NS)
     return SuccessResponse(msg="操作成功")
 
 
-@PluginRouter.get("/my", summary="我的插件", response_model=ResponseSchema[list[PluginOutSchema]])
+@PluginRouter.get(
+    "/my",
+    summary="我的插件",
+    response_model=ResponseSchema[list[PluginOutSchema]],
+)
 @cache(expire=120, namespace=_PLUGIN_NS)
-async def my_plugins(
+async def plugin_my_list_controller(
     auth: Annotated[AuthSchema, Depends(AuthPermission(["module_platform:plugin:query"]))],
 ) -> JSONResponse:
     """
     我的插件
 
+    参数:
+    - auth (AuthSchema): 认证信息模型。
+
     返回:
     - JSONResponse: 包含已安装插件列表的 JSON 响应。
     """
-    return SuccessResponse(data=await PluginService.my_plugins_service(auth), msg="查询成功")
+    return SuccessResponse(data=await PluginService.my_plugins_service(auth=auth), msg="查询成功")
 
 
-@PluginRouter.post("/reload", summary="热重载插件路由", response_model=ResponseSchema[str])
-async def plugin_reload(
+@PluginRouter.post(
+    "/reload",
+    summary="热重载插件路由",
+    response_model=ResponseSchema[str],
+)
+async def plugin_reload_controller(
     auth: Annotated[AuthSchema, Depends(AuthPermission(["module_platform:plugin:reload"]))],
 ) -> JSONResponse:
     """
@@ -228,6 +290,12 @@ async def plugin_reload(
 
     重新扫描 app/plugin/module_* 目录，清除模块缓存并注册新路由，
     无需重启服务器。
+
+    参数:
+    - auth (AuthSchema): 认证信息模型。
+
+    返回:
+    - JSONResponse: 包含重载结果的 JSON 响应。
     """
     msg = PluginService.reload_service()
     await FastAPICache.clear(namespace=_PLUGIN_NS)

backend/app/api/v1/module_platform/plugin/model.py

@@ -1,4 +1,4 @@
-from sqlalchemy import DateTime, ForeignKey, Integer, String, Text, UniqueConstraint
+from sqlalchemy import Boolean, DateTime, ForeignKey, Integer, String, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column, validates
 
 from app.core.base_model import MappedBase, ModelMixin
@@ -49,6 +49,6 @@ class TenantPluginModel(MappedBase):
     id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True, comment="主键ID")
     tenant_id: Mapped[int] = mapped_column(Integer, ForeignKey("platform_tenant.id", ondelete="CASCADE"), nullable=False, index=True, comment="租户ID")
     plugin_id: Mapped[int] = mapped_column(Integer, ForeignKey("platform_plugin.id", ondelete="CASCADE"), nullable=False, index=True, comment="插件ID")
-    enabled: Mapped[str] = mapped_column(String(1), nullable=False, default="1", comment="启用(1:启用 0:禁用)")
-    purchased: Mapped[str] = mapped_column(String(1), nullable=False, default="0", comment="是否已购买(1:已购买 0:未购买)")
+    enabled: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True, comment="启用(True:启用 False:禁用)")
+    purchased: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False, comment="是否已购买(True:已购买 False:未购买)")
     installed_time: Mapped[DateTime] = mapped_column(DateTime, nullable=False, comment="安装时间")

backend/app/api/v1/module_platform/plugin/schema.py

@@ -1,3 +1,6 @@
+from dataclasses import dataclass
+
+from fastapi import Query
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from app.common.enums import QueueEnum
@@ -10,7 +13,6 @@ class PluginCreateSchema(BaseModel):
 
     name: str = Field(..., min_length=1, max_length=100, description="插件名称")
     code: str = Field(..., min_length=1, max_length=50, description="插件编码（如 module_xxx）")
-    description: str | None = Field(default=None, max_length=255, description="插件描述")
     version: str = Field(default="1.0.0", max_length=20, description="版本号")
     author: str | None = Field(default=None, max_length=100, description="作者")
     icon: str | None = Field(default=None, max_length=500, description="图标URL")
@@ -21,6 +23,7 @@ class PluginCreateSchema(BaseModel):
     dependencies: str | None = Field(default=None, description="依赖插件编码(JSON数组)")
     sort: int = Field(default=0, ge=0, description="排序")
     status: int = Field(default=0, ge=0, le=1, description="状态(0:启动 1:停用)")
+    description: str | None = Field(default=None, max_length=255, description="插件描述")
 
     @field_validator("category")
     @classmethod
@@ -79,13 +82,14 @@ class PluginInstallSchema(BaseModel):
     plugin_id: int = Field(..., description="插件ID")
 
 
+@dataclass
 class PluginQueryParam(BaseQueryParam):
     """插件查询参数"""
 
     def __init__(
         self,
-        name: str | None = None,
-        category: str | None = None,
+        name: str | None = Query(None, description="插件名称"),
+        category: str | None = Query(None, description="插件分类(tool/ai/monitor/business)"),
         *args,
         **kwargs,
     ) -> None:

backend/app/api/v1/module_platform/plugin/service.py

@@ -3,6 +3,7 @@ from datetime import datetime
 import sqlalchemy as sa
 
 from app.core.base_schema import AuthSchema
+from app.core.dependencies import require_superadmin
 from app.core.exceptions import CustomException
 from app.core.logger import logger
 
@@ -12,7 +13,12 @@ from .schema import PluginCreateSchema, PluginOutSchema, PluginQueryParam, Plugi
 
 
 class PluginService:
+    """
+    插件管理服务（仅超级管理员可操作 CRUD，租户通过 marketplace/install/uninstall/toggle/my 操作）
+    """
+
     @classmethod
+    @require_superadmin
     async def page_service(
         cls,
         auth: AuthSchema,
@@ -21,44 +27,109 @@ class PluginService:
         search: PluginQueryParam | None = None,
         order_by: list | None = None,
     ) -> dict:
+        """
+        分页查询插件
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - page_no (int): 页码
+        - page_size (int): 每页数量
+        - search (PluginQueryParam | None): 查询参数
+        - order_by (list | None): 排序参数
+
+        返回:
+        - dict: 分页数据
+        """
         return await PluginCRUD(auth).page(
             offset=(page_no - 1) * page_size,
             limit=page_size,
             order_by=order_by or [{"sort": "asc"}],
-            search=search.__dict__ if search else {},
+            search=vars(search) if search else None,
             out_schema=PluginOutSchema,
         )
 
     @classmethod
+    @require_superadmin
     async def detail_service(cls, auth: AuthSchema, id: int) -> PluginOutSchema:
-        obj = await PluginCRUD(auth).get(id=id)
-        if not obj:
-            raise CustomException(msg="插件不存在")
-        return PluginOutSchema.model_validate(obj)
+        """
+        插件详情
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - id (int): 插件ID
+
+        返回:
+        - PluginOutSchema: 插件详情
+        """
+        return await PluginCRUD(auth).get_or_404(id=id, out_schema=PluginOutSchema)
 
     @classmethod
+    @require_superadmin
     async def create_service(cls, auth: AuthSchema, data: PluginCreateSchema) -> PluginOutSchema:
+        """
+        创建插件
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - data (PluginCreateSchema): 插件创建模型
+
+        返回:
+        - PluginOutSchema: 插件详情
+        """
         if await PluginCRUD(auth).get(code=data.code):
-            raise CustomException(msg="插件编码已存在")
+            raise CustomException(msg="创建失败，插件编码已存在")
         obj = await PluginCRUD(auth).create(data=data)
         return PluginOutSchema.model_validate(obj)
 
     @classmethod
+    @require_superadmin
     async def update_service(cls, auth: AuthSchema, id: int, data: PluginUpdateSchema) -> PluginOutSchema:
-        obj = await PluginCRUD(auth).get(id=id)
-        if not obj:
-            raise CustomException(msg="插件不存在")
+        """
+        更新插件
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - id (int): 插件ID
+        - data (PluginUpdateSchema): 插件更新模型
+
+        返回:
+        - PluginOutSchema: 插件详情
+        """
+        _ = await PluginCRUD(auth).get_or_404(id=id)
         updated = await PluginCRUD(auth).update(id=id, data=data)
         return PluginOutSchema.model_validate(updated)
 
     @classmethod
+    @require_superadmin
     async def delete_service(cls, auth: AuthSchema, ids: list[int]) -> None:
+        """
+        删除插件
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - ids (list[int]): 插件ID列表
+
+        返回:
+        - None
+        """
         await PluginCRUD(auth).delete(ids=ids)
 
     # ───── 插件市场 API ─────
 
     @classmethod
     async def marketplace_service(cls, auth: AuthSchema, page_no: int, page_size: int, category: str | None = None) -> dict:
+        """
+        插件市场列表（租户端）
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - page_no (int): 页码
+        - page_size (int): 每页数量
+        - category (str | None): 分类筛选
+
+        返回:
+        - dict: 分页数据（含租户的 installed/purchased 标记）
+        """
         search = {}
         if category:
             search["category"] = ("eq", category)
@@ -81,11 +152,21 @@ class PluginService:
             for item in result.items:
                 pid = item["id"]
                 item["installed"] = pid in record_map
-                item["purchased"] = record_map.get(pid, "0") == "1"
+                item["purchased"] = record_map.get(pid, False)
         return result
 
     @classmethod
     async def install_service(cls, auth: AuthSchema, plugin_id: int) -> None:
+        """
+        安装插件
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - plugin_id (int): 插件ID
+
+        返回:
+        - None
+        """
         tenant_id = getattr(auth, "tenant_id", None) or auth.user.tenant_id
         if not tenant_id:
             raise CustomException(msg="无法获取租户信息")
@@ -101,7 +182,7 @@ class PluginService:
 
         plugin = await PluginCRUD(auth).get(id=plugin_id)
         if not plugin or plugin.status == 1:
-            raise CustomException(msg="插件不可用")
+            raise CustomException(msg="该数据不存在")
 
         # 付费插件需要先购买
         if tenant_id != 1 and getattr(plugin, "price", 0) > 0:
@@ -114,7 +195,7 @@ class PluginService:
                 .limit(1)
             )
             tp_record = exist.scalar_one_or_none()
-            if not tp_record or tp_record.purchased != "1":
+            if not tp_record or not tp_record.purchased:
                 raise CustomException(msg="此插件为付费插件，请先购买后再安装")
 
         exist = await auth.db.execute(
@@ -132,14 +213,14 @@ class PluginService:
                     TenantPluginModel.tenant_id == tenant_id,
                     TenantPluginModel.plugin_id == plugin_id,
                 )
-                .values(enabled="0")
+                .values(enabled=False)
             )
         else:
             tp = TenantPluginModel(
                 tenant_id=tenant_id,
                 plugin_id=plugin_id,
-                enabled="0",
-                purchased="1" if getattr(plugin, "price", 0) == 0 else "0",
+                enabled=False,
+                purchased=True if getattr(plugin, "price", 0) == 0 else False,
                 installed_time=datetime.now(),
             )
             auth.db.add(tp)
@@ -148,6 +229,16 @@ class PluginService:
 
     @classmethod
     async def uninstall_service(cls, auth: AuthSchema, plugin_id: int) -> None:
+        """
+        卸载插件
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - plugin_id (int): 插件ID
+
+        返回:
+        - None
+        """
         tenant_id = getattr(auth, "tenant_id", None) or auth.user.tenant_id
         if not tenant_id:
             raise CustomException(msg="无法获取租户信息")
@@ -162,6 +253,16 @@ class PluginService:
 
     @classmethod
     async def toggle_service(cls, auth: AuthSchema, plugin_id: int) -> None:
+        """
+        启用/禁用插件
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - plugin_id (int): 插件ID
+
+        返回:
+        - None
+        """
         tenant_id = getattr(auth, "tenant_id", None) or auth.user.tenant_id
         tp = await auth.db.execute(
             sa.select(TenantPluginModel)
@@ -174,12 +275,21 @@ class PluginService:
         tp = tp.scalar_one_or_none()
         if not tp:
             raise CustomException(msg="未安装该插件")
-        tp.enabled = "1" if tp.enabled == "0" else "0"
+        tp.enabled = not tp.enabled
         await auth.db.flush()
         logger.info(f"租户[{tenant_id}]插件[{plugin_id}]状态→{tp.enabled}")
 
     @classmethod
     async def my_plugins_service(cls, auth: AuthSchema) -> list[dict]:
+        """
+        查询我的插件列表（租户端）
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+
+        返回:
+        - list[dict]: 已安装插件列表
+        """
         tenant_id = getattr(auth, "tenant_id", None) or auth.user.tenant_id
         if not tenant_id:
             return []