refactor: 优化代码注释和文档字符串格式

style: 统一代码风格和格式 docs: 完善函数和方法的文档字符串 refactor(base_model): 移除冗余的表名和表参数生成方法 refactor(constant): 更新返回码注释格式 refactor(router_class): 添加路由处理器的详细文档 refactor(database): 完善数据库连接函数的文档 refactor(security): 添加认证类和方法的详细文档 refactor(validator): 更新验证器函数的文档格式 refactor(serialize): 优化序列化工具类的文档 refactor(response): 完善响应类的文档字符串 refactor(dependencies): 添加依赖函数的详细文档 refactor(initialize): 完善初始化脚本的文档 refactor(plugin): 添加生命周期和中间件注册的文档 refactor(service): 完善服务层方法的文档 refactor(controller): 添加控制器方法的详细文档 refactor(crud): 完善CRUD操作的文档字符串 refactor(schema): 简化模型类并移除冗余字段 refactor(param): 更新查询参数类的注释格式 refactor(template): 优化代码生成模板的格式 refactor(console): 添加控制台输出功能的实现 refactor(util): 完善工具函数的文档字符串
2026-09-21 04:46:26 +00:00 · 2025-10-18 16:31:28 +08:00
parent 0ea88c3320
commit c2ca6d19ac
101 changed files with 6914 additions and 2295 deletions
@@ -24,7 +24,17 @@ async def get_obj_list_controller(
    search: OperationLogQueryParam = Depends(),
    auth: AuthSchema = Depends(AuthPermission(["system:log:query"]))
 ) -> JSONResponse:
-    """ 查询日志 """
+    """ 
+    查询日志 
+    
+    参数:
+    - page (PaginationQueryParam): 分页查询参数模型
+    - search (OperationLogQueryParam): 日志查询参数模型
+    - auth (AuthSchema): 认证信息模型
+    
+    返回:
+    - JSONResponse: 包含分页日志详情的 JSON 响应模型
+    """
    order_by = [{"created_at": "desc"}]
    if page.order_by:
        order_by = page.order_by
@@ -39,7 +49,16 @@ async def get_obj_detail_controller(
    id: int = Path(..., description="操作日志ID"),
    auth: AuthSchema = Depends(AuthPermission(["system:log:query"]))
 ) -> JSONResponse:
-    """ 详情日志 """
+    """ 
+    获取日志详情 
+    
+    参数:
+    - id (int): 操作日志ID
+    - auth (AuthSchema): 认证信息模型
+    
+    返回:
+    - JSONResponse: 包含日志详情的 JSON 响应模型
+    """
    result_dict = await OperationLogService.get_log_detail_service(id=id, auth=auth)
    logger.info(f"查询日志成功 {id}")
    return SuccessResponse(data=result_dict, msg="获取日志详情成功")
@@ -50,7 +69,16 @@ async def delete_obj_log_controller(
    ids: list[int] = Body(..., description="ID列表"),
    auth: AuthSchema = Depends(AuthPermission(["system:log:delete"]))
 ) -> JSONResponse:
-    """ 删除日志 """
+    """ 
+    删除日志 
+    
+    参数:
+    - ids (list[int]): 日志 ID 列表
+    - auth (AuthSchema): 认证信息模型
+    
+    返回:
+    - JSONResponse: 包含删除结果的 JSON 响应模型
+    """
    await OperationLogService.delete_log_service(ids=ids, auth=auth)
    logger.info(f"删除日志成功 {ids}")
    return SuccessResponse(msg="删除日志成功")
@@ -61,7 +89,16 @@ async def export_obj_list_controller(
    search: OperationLogQueryParam = Depends(),
    auth: AuthSchema = Depends(AuthPermission(["system:log:export"]))
 ) -> StreamingResponse:
-    """ 导出日志 """
+    """ 
+    导出日志 
+    
+    参数:
+    - search (OperationLogQueryParam): 日志查询参数模型
+    - auth (AuthSchema): 认证信息模型
+    
+    返回:
+    - StreamingResponse: 包含导出日志的流式响应模型
+    """
    operation_log_list = await OperationLogService.get_log_list_service(search=search, auth=auth)
    operation_log_export_result = await OperationLogService.export_log_list_service(operation_log_list=operation_log_list)
    logger.info('导出日志成功')
@@ -9,38 +9,51 @@ from .schema import OperationLogCreateSchema


 class OperationLogCRUD(CRUDBase[OperationLogModel, OperationLogCreateSchema, OperationLogCreateSchema]):
-    """操作日志数据层"""
+    """
+    操作日志数据层。
+    """

    def __init__(self, auth: AuthSchema) -> None:
-        """初始化操作日志CRUD"""
+        """
+        初始化操作日志CRUD。
+        """
        self.auth = auth
        super().__init__(model=OperationLogModel, auth=auth)

    async def create_crud(self, data: OperationLogCreateSchema) -> Optional[OperationLogModel]:
        """
-        创建操作日志记录
+        创建操作日志记录。
        
-        :param data: 操作日志创建模型
-        :return: 操作日志记录
+        参数:
+        - data (OperationLogCreateSchema): 操作日志创建模型。
+        
+        返回:
+        - OperationLogModel | None: 创建后的日志记录。
        """
        return await self.create(data=data)

    async def get_by_id_crud(self, id: int) -> Optional[OperationLogModel]:
        """
-        根据ID获取操作日志详情
+        根据ID获取操作日志详情。
        
-        :param id: 操作日志ID
-        :return: 操作日志记录
+        参数:
+        - id (int): 操作日志ID。
+        
+        返回:
+        - OperationLogModel | None: 操作日志记录。
        """
        return await self.get(id=id)

    async def get_list_crud(self, search: Optional[Dict] = None, order_by: Optional[List[Dict[str, str]]] = None) -> Sequence[OperationLogModel]:
        """
-        获取操作日志列表
+        获取操作日志列表。
        
-        :param search: 搜索条件
-        :param order_by: 排序字段
-        :return: 操作日志列表
+        参数:
+        - search (Dict | None): 搜索条件字典。
+        - order_by (List[Dict[str, str]] | None): 排序字段列表。
+        
+        返回:
+        - Sequence[OperationLogModel]: 操作日志列表。
        """
        return await self.list(search=search, order_by=order_by)

@@ -20,28 +20,65 @@ class OperationLogService:

    @classmethod
    async def get_log_detail_service(cls, auth: AuthSchema, id: int) -> Dict:
-        """获取日志详情"""
+        """
+        获取日志详情
+        
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - id (int): 日志 ID
+        
+        返回:
+        - Dict: 日志详情字典
+        """
        log = await OperationLogCRUD(auth).get_by_id_crud(id=id)
        log_dict = OperationLogOutSchema.model_validate(log).model_dump()
        return log_dict

    @classmethod
    async def get_log_list_service(cls, auth: AuthSchema, search: Optional[OperationLogQueryParam], order_by: Optional[List[Dict]] = None) -> List[Dict]:
-        """获取日志列表"""            
+        """
+        获取日志列表
+        
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - search (Optional[OperationLogQueryParam]): 日志查询参数模型
+        - order_by (Optional[List[Dict]]): 排序字段列表
+        
+        返回:
+        - List[Dict]: 日志详情字典列表
+        """            
        log_list = await OperationLogCRUD(auth).get_list_crud(search=search.__dict__, order_by=order_by)
        log_dict_list = [OperationLogOutSchema.model_validate(log).model_dump() for log in log_list]
        return log_dict_list

    @classmethod
    async def create_log_service(cls, auth: AuthSchema, data: OperationLogCreateSchema) -> Dict:
-        """创建日志"""
+        """
+        创建日志
+        
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - data (OperationLogCreateSchema): 日志创建模型
+        
+        返回:
+        - Dict: 日志详情字典
+        """
        new_log = await OperationLogCRUD(auth).create(data=data)
        new_log_dict = OperationLogOutSchema.model_validate(new_log).model_dump()
        return new_log_dict
    
    @classmethod
    async def delete_log_service(cls, auth: AuthSchema, ids: list[int]) -> None:
-        """删除日志"""
+        """
+        删除日志
+        
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - ids (list[int]): 日志 ID 列表
+        
+        返回:
+        - None
+        """
        if len(ids) < 1:
            raise CustomException(msg='删除失败，删除对象不能为空')
        await OperationLogCRUD(auth).delete(ids=ids)
@@ -51,11 +88,11 @@ class OperationLogService:
        """
        导出日志信息

-        Args:
-            operation_log_list: 操作日志信息列表
+        参数:
+        - operation_log_list (List[Dict[str, Any]]): 操作日志信息列表
        
-        Returns:
-            bytes: 操作日志信息excel的二进制数据
+        返回:
+        - bytes: 操作日志信息excel的二进制数据
        """
        # 操作日志字段映射
        mapping_dict = {