Optimize admin schema

Author: wu-clan

backend/app/admin/conf.py

@@ -8,30 +8,27 @@
 
 
 class AdminSettings(BaseSettings):
-    """Admin Settings"""
+    """Admin 配置"""
 
     model_config = SettingsConfigDict(env_file=f'{BASE_PATH}/.env', env_file_encoding='utf-8', extra='ignore')
 
-    # OAuth2：https://github.com/fastapi-practices/fastapi_oauth20
-    # GitHub
+    # .env OAuth2 配置
     OAUTH2_GITHUB_CLIENT_ID: str
     OAUTH2_GITHUB_CLIENT_SECRET: str
-    OAUTH2_GITHUB_REDIRECT_URI: str = 'http://127.0.0.1:8000/api/v1/oauth2/github/callback'
-
-    # Linux Do
     OAUTH2_LINUX_DO_CLIENT_ID: str
     OAUTH2_LINUX_DO_CLIENT_SECRET: str
-    OAUTH2_LINUX_DO_REDIRECT_URI: str = 'http://127.0.0.1:8000/api/v1/oauth2/linux-do/callback'
 
-    # Front-end redirect address
+    # OAuth2 配置
+    OAUTH2_GITHUB_REDIRECT_URI: str = 'http://127.0.0.1:8000/api/v1/oauth2/github/callback'
+    OAUTH2_LINUX_DO_REDIRECT_URI: str = 'http://127.0.0.1:8000/api/v1/oauth2/linux-do/callback'
     OAUTH2_FRONTEND_REDIRECT_URI: str = 'http://localhost:5173/oauth2/callback'
 
-    # Captcha
+    # 验证码配置
     CAPTCHA_LOGIN_REDIS_PREFIX: str = 'fba:login:captcha'
-    CAPTCHA_LOGIN_EXPIRE_SECONDS: int = 60 * 5  # 过期时间，单位：秒
+    CAPTCHA_LOGIN_EXPIRE_SECONDS: int = 60 * 5  # 3 分钟
 
-    # Config
-    CONFIG_BUILT_IN_TYPES: list = ['website', 'protocol', 'policy']
+    # 系统配置
+    CONFIG_BUILT_IN_TYPES: list[str] = ['website', 'protocol', 'policy']
 
 
 @lru_cache

backend/app/admin/schema/captcha.py

@@ -6,5 +6,7 @@
 
 
 class GetCaptchaDetail(SchemaBase):
+    """验证码详情"""
+
     image_type: str = Field(description='图片类型')
     image: str = Field(description='图片内容')

backend/app/admin/schema/config.py

@@ -2,37 +2,43 @@
 # -*- coding: utf-8 -*-
 from datetime import datetime
 
-from pydantic import ConfigDict
+from pydantic import ConfigDict, Field
 
 from backend.common.schema import SchemaBase
 
 
 class SaveBuiltInConfigParam(SchemaBase):
-    name: str
-    key: str
-    value: str
+    """保存内置配置参数"""
+
+    name: str = Field(description='配置名称')
+    key: str = Field(description='配置键名')
+    value: str = Field(description='配置值')
 
 
 class ConfigSchemaBase(SchemaBase):
-    name: str
-    type: str | None
-    key: str
-    value: str
-    is_frontend: bool
-    remark: str | None
+    """配置基础模型"""
+
+    name: str = Field(description='配置名称')
+    type: str | None = Field(default=None, description='配置类型')
+    key: str = Field(description='配置键名')
+    value: str = Field(description='配置值')
+    is_frontend: bool = Field(description='是否前端配置')
+    remark: str | None = Field(default=None, description='备注')
 
 
 class CreateConfigParam(ConfigSchemaBase):
-    pass
+    """创建配置参数"""
 
 
 class UpdateConfigParam(ConfigSchemaBase):
-    pass
+    """更新配置参数"""
 
 
 class GetConfigDetail(ConfigSchemaBase):
+    """配置详情"""
+
     model_config = ConfigDict(from_attributes=True)
 
-    id: int
-    created_time: datetime
-    updated_time: datetime | None = None
+    id: int = Field(description='配置 ID')
+    created_time: datetime = Field(description='创建时间')
+    updated_time: datetime | None = Field(default=None, description='更新时间')

backend/app/admin/schema/data_rule.py

@@ -9,28 +9,33 @@
 
 
 class DataRuleSchemaBase(SchemaBase):
-    name: str
-    model: str
-    column: str
-    operator: RoleDataRuleOperatorType = Field(RoleDataRuleOperatorType.OR)
-    expression: RoleDataRuleExpressionType = Field(RoleDataRuleExpressionType.eq)
-    value: str
+    """数据规则基础模型"""
+
+    name: str = Field(description='规则名称')
+    model: str = Field(description='模型名称')
+    column: str = Field(description='字段名称')
+    operator: RoleDataRuleOperatorType = Field(default=RoleDataRuleOperatorType.OR, description='操作符（AND/OR）')
+    expression: RoleDataRuleExpressionType = Field(default=RoleDataRuleExpressionType.eq, description='表达式类型')
+    value: str = Field(description='规则值')
 
 
 class CreateDataRuleParam(DataRuleSchemaBase):
-    pass
+    """创建数据规则参数"""
 
 
 class UpdateDataRuleParam(DataRuleSchemaBase):
-    pass
+    """更新数据规则参数"""
 
 
 class GetDataRuleDetail(DataRuleSchemaBase):
+    """数据规则详情"""
+
     model_config = ConfigDict(from_attributes=True)
 
-    id: int
-    created_time: datetime
-    updated_time: datetime | None = None
+    id: int = Field(description='规则 ID')
+    created_time: datetime = Field(description='创建时间')
+    updated_time: datetime | None = Field(default=None, description='更新时间')
 
-    def __hash__(self):
+    def __hash__(self) -> int:
+        """计算哈希值"""
         return hash(self.name)

backend/app/admin/schema/dept.py

@@ -9,27 +9,31 @@
 
 
 class DeptSchemaBase(SchemaBase):
-    name: str
-    parent_id: int | None = Field(default=None, description='部门父级ID')
+    """部门基础模型"""
+
+    name: str = Field(description='部门名称')
+    parent_id: int | None = Field(default=None, description='部门父级 ID')
     sort: int = Field(default=0, ge=0, description='排序')
-    leader: str | None = None
-    phone: CustomPhoneNumber | None = None
-    email: CustomEmailStr | None = None
-    status: StatusType = Field(default=StatusType.enable)
+    leader: str | None = Field(default=None, description='负责人')
+    phone: CustomPhoneNumber | None = Field(default=None, description='联系电话')
+    email: CustomEmailStr | None = Field(default=None, description='邮箱')
+    status: StatusType = Field(default=StatusType.enable, description='状态')
 
 
 class CreateDeptParam(DeptSchemaBase):
-    pass
+    """创建部门参数"""
 
 
 class UpdateDeptParam(DeptSchemaBase):
-    pass
+    """更新部门参数"""
 
 
 class GetDeptDetail(DeptSchemaBase):
+    """部门详情"""
+
     model_config = ConfigDict(from_attributes=True)
 
-    id: int
-    del_flag: bool
-    created_time: datetime
-    updated_time: datetime | None = None
+    id: int = Field(description='部门 ID')
+    del_flag: bool = Field(description='是否删除')
+    created_time: datetime = Field(description='创建时间')
+    updated_time: datetime | None = Field(default=None, description='更新时间')

backend/app/admin/schema/dict_data.py

@@ -10,29 +10,35 @@
 
 
 class DictDataSchemaBase(SchemaBase):
-    type_id: int
-    label: str
-    value: str
-    sort: int
-    status: StatusType = Field(default=StatusType.enable)
-    remark: str | None = None
+    """字典数据基础模型"""
+
+    type_id: int = Field(description='字典类型 ID')
+    label: str = Field(description='字典标签')
+    value: str = Field(description='字典值')
+    sort: int = Field(description='排序')
+    status: StatusType = Field(default=StatusType.enable, description='状态')
+    remark: str | None = Field(default=None, description='备注')
 
 
 class CreateDictDataParam(DictDataSchemaBase):
-    pass
+    """创建字典数据参数"""
 
 
 class UpdateDictDataParam(DictDataSchemaBase):
-    pass
+    """更新字典数据参数"""
 
 
 class GetDictDataDetail(DictDataSchemaBase):
+    """字典数据详情"""
+
     model_config = ConfigDict(from_attributes=True)
 
-    id: int
-    created_time: datetime
-    updated_time: datetime | None = None
+    id: int = Field(description='字典数据 ID')
+    created_time: datetime = Field(description='创建时间')
+    updated_time: datetime | None = Field(default=None, description='更新时间')
 
 
 class GetDictDataWithRelation(DictDataSchemaBase):
-    type: GetDictTypeDetail | None = None
+    """字典数据关联详情"""
+
+    type: GetDictTypeDetail | None = Field(default=None, description='字典类型信息')

backend/app/admin/schema/dict_type.py

@@ -9,23 +9,31 @@
 
 
 class DictTypeSchemaBase(SchemaBase):
-    name: str
-    code: str
-    status: StatusType = Field(default=StatusType.enable)
-    remark: str | None = None
+    """字典类型基础模型"""
+
+    name: str = Field(description='字典名称')
+    code: str = Field(description='字典编码')
+    status: StatusType = Field(default=StatusType.enable, description='状态')
+    remark: str | None = Field(default=None, description='备注')
 
 
 class CreateDictTypeParam(DictTypeSchemaBase):
+    """创建字典类型参数"""
+
     pass
 
 
 class UpdateDictTypeParam(DictTypeSchemaBase):
+    """更新字典类型参数"""
+
     pass
 
 
 class GetDictTypeDetail(DictTypeSchemaBase):
+    """字典类型详情"""
+
     model_config = ConfigDict(from_attributes=True)
 
-    id: int
-    created_time: datetime
-    updated_time: datetime | None = None
+    id: int = Field(description='字典类型 ID')
+    created_time: datetime = Field(description='创建时间')
+    updated_time: datetime | None = Field(default=None, description='更新时间')

backend/app/admin/schema/login_log.py

@@ -2,37 +2,41 @@
 # -*- coding: utf-8 -*-
 from datetime import datetime
 
-from pydantic import ConfigDict
+from pydantic import ConfigDict, Field
 
 from backend.common.schema import SchemaBase
 
 
 class LoginLogSchemaBase(SchemaBase):
-    user_uuid: str
-    username: str
-    status: int
-    ip: str
-    country: str | None
-    region: str | None
-    city: str | None
-    user_agent: str
-    browser: str | None
-    os: str | None
-    device: str | None
-    msg: str
-    login_time: datetime
+    """登录日志基础模型"""
+
+    user_uuid: str = Field(description='用户 UUID')
+    username: str = Field(description='用户名')
+    status: int = Field(description='登录状态')
+    ip: str = Field(description='IP 地址')
+    country: str | None = Field(default=None, description='国家')
+    region: str | None = Field(default=None, description='地区')
+    city: str | None = Field(default=None, description='城市')
+    user_agent: str = Field(description='用户代理')
+    browser: str | None = Field(default=None, description='浏览器')
+    os: str | None = Field(default=None, description='操作系统')
+    device: str | None = Field(default=None, description='设备')
+    msg: str = Field(description='消息')
+    login_time: datetime = Field(description='登录时间')
 
 
 class CreateLoginLogParam(LoginLogSchemaBase):
-    pass
+    """创建登录日志参数"""
 
 
 class UpdateLoginLogParam(LoginLogSchemaBase):
-    pass
+    """更新登录日志参数"""
 
 
 class GetLoginLogDetail(LoginLogSchemaBase):
+    """登录日志详情"""
+
     model_config = ConfigDict(from_attributes=True)
 
-    id: int
-    created_time: datetime
+    id: int = Field(description='日志 ID')
+    created_time: datetime = Field(description='创建时间')

backend/app/admin/schema/menu.py

@@ -9,32 +9,36 @@
 
 
 class MenuSchemaBase(SchemaBase):
-    title: str
-    name: str
-    parent_id: int | None = Field(default=None, description='菜单父级ID')
+    """菜单基础模型"""
+
+    title: str = Field(description='菜单标题')
+    name: str = Field(description='菜单名称')
+    parent_id: int | None = Field(default=None, description='菜单父级 ID')
     sort: int = Field(default=0, ge=0, description='排序')
-    icon: str | None = None
-    path: str | None = None
+    icon: str | None = Field(default=None, description='图标')
+    path: str | None = Field(default=None, description='路由路径')
     menu_type: MenuType = Field(default=MenuType.directory, description='菜单类型（0目录 1菜单 2按钮）')
-    component: str | None = None
-    perms: str | None = None
-    status: StatusType = Field(default=StatusType.enable)
-    display: StatusType = Field(default=StatusType.enable)
-    cache: StatusType = Field(default=StatusType.enable)
-    remark: str | None = None
+    component: str | None = Field(default=None, description='组件路径')
+    perms: str | None = Field(default=None, description='权限标识')
+    status: StatusType = Field(default=StatusType.enable, description='状态')
+    display: StatusType = Field(default=StatusType.enable, description='是否显示')
+    cache: StatusType = Field(default=StatusType.enable, description='是否缓存')
+    remark: str | None = Field(default=None, description='备注')
 
 
 class CreateMenuParam(MenuSchemaBase):
-    pass
+    """创建菜单参数"""
 
 
 class UpdateMenuParam(MenuSchemaBase):
-    pass
+    """更新菜单参数"""
 
 
 class GetMenuDetail(MenuSchemaBase):
+    """菜单详情"""
+
     model_config = ConfigDict(from_attributes=True)
 
-    id: int
-    created_time: datetime
-    updated_time: datetime | None = None
+    id: int = Field(description='菜单 ID')
+    created_time: datetime = Field(description='创建时间')
+    updated_time: datetime | None = Field(default=None, description='更新时间')