Optimize codes and comments with cursor

.gitignore

@@ -1,5 +1,7 @@
 .idea/
 .vscode/
+.cursor/
+.DS_Store
 venv/
 .venv/
 .python-version

README.md

@@ -6,9 +6,7 @@
 
 English | [简体中文](./README.zh-CN.md)
 
-A backend and frontend separation solution based on the FastAPI framework, following
-the [pseudo 3-tier architecture](#pseudo-3-tier-architecture) design, supporting **Python 3.10** and above
-versions
+Enterprise-level backend architecture solution
 
 **🔥Continuously updated and maintained🔥**
 
@@ -49,37 +47,39 @@ pattern, use templates to transform it to your heart's content!
 
 ## Features
 
-- [x] Design with FastAPI PEP 593 Annotated Parameters
-- [x] Global asynchronous design with async/await + asgiref
-- [x] Follows Restful API specification
-- [x] Global SQLAlchemy 2.0 syntax
-- [x] Pydantic v1 and v2 (different branches)
-- [x] Casbin RBAC access control model
-- [x] Role menu RBAC access control model
-- [x] Celery asynchronous tasks
-- [x] JWT middleware whitelist authentication
-- [x] Global customizable time zone time
-- [x] Docker / Docker-compose deployment
-- [x] Pytest Unit Testing
-
-## Built-in features
-
-- [x] User management: System User Role Management, Permission Allocation
-- [x] Department management: Configure system organization (company, department, team...)
-- [x] Menu management: Configure system menu, user menu, button permission tags
-- [x] Role management: role menu permission allocation, role route permission allocation
-- [x] Dictionary management: Maintain commonly used fixed data or parameters within the system
-- [x] Token management: System user online status detection, supports kicking users offline
-- [x] Login authentication: backend-based graphical captcha background authentication login
-- [x] Multipoint login: One-click modification of multipoint login through user information
-- [x] OAuth 2.0: Built-in self-developed OAuth 2.0 login integration
-- [x] Code generation: automatic backend code generation, supports preview, writing, and download
-- [x] Scheduled task: Automated task, asynchronous task, supports function calls
-- [x] Plugin system: Say goodbye to high coupling integration through hot-pluggable plugin mode
-- [x] Operation log: Record and query of system normal and abnormal operations
-- [x] Login log: Record and query of normal and abnormal user login
-- [x] Service monitoring: Server hardware device information and status
-- [x] API documentation: Automatically generate online interactive API documentation
+- [x] Global FastAPI PEP 593 Annotated parameter style
+- [x] Comprehensive async/await + asgiref asynchronous design
+- [x] Adheres to RESTful API specifications
+- [x] Uses SQLAlchemy 2.0 with new syntax
+- [x] Uses Pydantic v2 version
+- [x] Implements role-menu RBAC access control
+- [x] Integrates Casbin RBAC access control
+- [x] Supports Celery asynchronous tasks
+- [x] Custom-developed JWT authentication middleware
+- [x] Supports global custom time zones
+- [x] Supports Docker / Docker-compose deployment
+- [x] Integrates Pytest unit testing
+
+## Built-in Functions
+
+- [x] User Management: Assign roles and permissions
+- [x] Department Management: Configure organizational structure (company, department, team, etc.)
+- [x] Menu Management: Set up menus and button-level permissions
+- [x] Role Management: Configure roles, assign menus and permissions
+- [x] Dictionary Management: Maintain common parameters and configurations
+- [x] Parameter Management: Dynamically configure commonly used system parameters
+- [x] Notification Announcements: Publish and maintain system notification and announcement information
+- [x] Token Management: Detect online status, support forced logout
+- [x] Multi-device Login: Support one-click switching between multi-device login modes
+- [x] OAuth 2.0: Built-in custom-developed OAuth 2.0 authorization login
+- [x] Plugin System: Hot-swappable plugin design to reduce coupling
+- [x] Scheduled Tasks: Support scheduled, asynchronous tasks, and function calls
+- [x] Code Generation: Automatically generate code with preview, write, and download support
+- [x] Operation Logs: Record and query normal and abnormal operations
+- [x] Login Logs: Record and query normal and abnormal logins
+- [x] Cache Monitoring: Query system cache information and command statistics
+- [x] Service Monitoring: View server hardware information and status
+- [x] API Documentation: Automatically generate online interactive API documentation
 
 ## Development and deployment
 
@@ -103,7 +103,7 @@ the [official documentation](https://fastapi-practices.github.io/fastapi_best_ar
 
 ## Interactivity
 
-[TG / Discord](https://wu-clan.github.io/homepage/)
+[Discord](https://wu-clan.github.io/homepage/)
 
 ## Sponsor us
 

README.zh-CN.md

@@ -6,7 +6,7 @@
 
 简体中文 | [English](./README.md)
 
-基于 FastAPI 框架的前后端分离中后台解决方案，遵循[伪三层架构](#伪三层架构)设计， 支持 **python3.10** 及以上版本
+企业级后端架构解决方案
 
 **🔥持续更新维护中🔥**
 
@@ -43,38 +43,40 @@ mvc 架构作为常规设计模式，在 python web 中也很常见，但是三
 | 数据访问 | dao / mapper   | crud                      |
 | 模型   | model / entity | model                     |
 
-## 特征
+## 特性
 
 - [x] 全局 FastAPI PEP 593 Annotated 参数风格
-- [x] async/await + asgiref 的全局异步设计
-- [x] 遵循 Restful API 规范
-- [x] 全局 SQLAlchemy 2.0 语法
-- [x] Pydantic v1 和 v2 (不同分支)
-- [x] Casbin RBAC 访问控制模型
-- [x] 角色菜单 RBAC 访问控制模型
-- [x] Celery 异步任务
-- [x] JWT 中间件白名单认证
-- [x] 全局自定义时区时间
-- [x] Docker / Docker-compose 部署
-- [x] Pytest 单元测试
+- [x] 全面 async/await + asgiref 异步设计
+- [x] 遵循 RESTful API 规范
+- [x] 使用 SQLAlchemy 2.0 全新语法
+- [x] 使用 Pydantic v2 版本
+- [x] 实现角色菜单 RBAC 访问控制
+- [x] 集成 Casbin RBAC 访问控制
+- [x] 支持 Celery 异步任务
+- [x] 自研 JWT 认证中间件
+- [x] 支持全局自定义时间时区
+- [x] 支持 Docker / Docker-compose 部署
+- [x] 集成 Pytest 单元测试
 
 ## 内置功能
 
-- [x] 用户管理：系统用户角色管理，权限分配
-- [x] 部门管理：配置系统组织机构（公司、部门、小组...）
-- [x] 菜单管理：配置系统菜单，用户菜单，按钮权限标识
-- [x] 角色管理：角色菜单权限分配，角色路由权限分配
-- [x] 字典管理：维护系统内部常用固定数据或参数
-- [x] 令牌管理：系统用户在线状态检测，支持踢人下线
-- [x] 登录认证：基于后端的图形验证码后台认证登录
-- [x] 多点登录：通过用户信息一键修改多点登录支持
-- [x] OAuth20：内置自研 OAuth 2.0 登录集成
-- [x] 代码生成：后端代码自动生成，支持预览，写入及下载
-- [x] 定时任务：自动化任务，异步任务，支持函数调用
-- [x] 插件系统：通过热插拔插件模式告别高耦合集成
-- [x] 操作日志：系统正常和异常操作的日志记录与查询
-- [x] 登录日志：用户正常和异常登录的日志记录与查询
-- [x] 服务监控：服务器硬件设备信息与状态
+- [x] 用户管理：分配角色和权限
+- [x] 部门管理：配置组织架构（公司、部门、小组等）
+- [x] 菜单管理：设置菜单及按钮级权限
+- [x] 角色管理：配置角色、分配菜单和权限
+- [x] 字典管理：维护常用参数和配置
+- [x] 参数管理：系统常用参数动态配置
+- [x] 通知公告：发布和维护系统通知公告信息
+- [x] 令牌管理：检测在线状态，支持强制下线
+- [x] 多端登录：支持一键切换多端登录模式
+- [x] OAuth 2.0：内置自研 OAuth 2.0 授权登录
+- [x] 插件系统：热插拔插件设计，降低耦合
+- [x] 定时任务：支持定时，异步任务及函数调用
+- [x] 代码生成：自动生成代码，支持预览、写入和下载
+- [x] 操作日志：记录和查询正常和异常操作
+- [x] 登录日志：记录和查询正常和异常登录
+- [x] 缓存监控：查询系统缓存信息和命令统计
+- [x] 服务监控：查看服务器硬件信息和状态
 - [x] 接口文档：自动生成在线交互式 API 文档
 
 ## 开发部署
@@ -98,7 +100,7 @@ mvc 架构作为常规设计模式，在 python web 中也很常见，但是三
 
 ## 互动
 
-[TG / Discord](https://wu-clan.github.io/homepage/)
+[Discord](https://wu-clan.github.io/homepage/)
 
 ## 赞助我们
 

backend/app/admin/api/v1/auth/auth.py

@@ -36,7 +36,7 @@ async def user_login(
 
 
 @router.post('/token/new', summary='创建新 token')
-async def create_new_token(request: Request, response: Response) -> ResponseSchemaModel[GetNewToken]:
+async def create_new_token(request: Request) -> ResponseSchemaModel[GetNewToken]:
     data = await auth_service.new_token(request=request)
     return response_base.success(data=data)
 

backend/app/admin/api/v1/log/login_log.py

@@ -18,17 +18,17 @@
 
 @router.get(
     '',
-    summary='（模糊条件）分页获取登录日志',
+    summary='分页获取登录日志',
     dependencies=[
         DependsJwtAuth,
         DependsPagination,
     ],
 )
 async def get_pagination_login_logs(
     db: CurrentSession,
-    username: Annotated[str | None, Query()] = None,
-    status: Annotated[int | None, Query()] = None,
-    ip: Annotated[str | None, Query()] = None,
+    username: Annotated[str | None, Query(description='用户名')] = None,
+    status: Annotated[int | None, Query(description='状态')] = None,
+    ip: Annotated[str | None, Query(description='IP 地址')] = None,
 ) -> ResponseSchemaModel[PageData[GetLoginLogDetail]]:
     log_select = await login_log_service.get_select(username=username, status=status, ip=ip)
     page_data = await paging_data(db, log_select)
@@ -37,13 +37,13 @@ async def get_pagination_login_logs(
 
 @router.delete(
     '',
-    summary='（批量）删除登录日志',
+    summary='批量删除登录日志',
     dependencies=[
         Depends(RequestPermission('log:login:del')),
         DependsRBAC,
     ],
 )
-async def delete_login_log(pk: Annotated[list[int], Query(...)]) -> ResponseModel:
+async def delete_login_log(pk: Annotated[list[int], Query(description='登录日志 ID 列表')]) -> ResponseModel:
     count = await login_log_service.delete(pk=pk)
     if count > 0:
         return response_base.success()

backend/app/admin/api/v1/log/opera_log.py

@@ -18,17 +18,17 @@
 
 @router.get(
     '',
-    summary='（模糊条件）分页获取操作日志',
+    summary='分页获取操作日志',
     dependencies=[
         DependsJwtAuth,
         DependsPagination,
     ],
 )
 async def get_pagination_opera_logs(
     db: CurrentSession,
-    username: Annotated[str | None, Query()] = None,
-    status: Annotated[int | None, Query()] = None,
-    ip: Annotated[str | None, Query()] = None,
+    username: Annotated[str | None, Query(description='用户名')] = None,
+    status: Annotated[int | None, Query(description='状态')] = None,
+    ip: Annotated[str | None, Query(description='IP 地址')] = None,
 ) -> ResponseSchemaModel[PageData[GetOperaLogDetail]]:
     log_select = await opera_log_service.get_select(username=username, status=status, ip=ip)
     page_data = await paging_data(db, log_select)
@@ -37,13 +37,13 @@ async def get_pagination_opera_logs(
 
 @router.delete(
     '',
-    summary='（批量）删除操作日志',
+    summary='批量删除操作日志',
     dependencies=[
         Depends(RequestPermission('log:opera:del')),
         DependsRBAC,
     ],
 )
-async def delete_opera_log(pk: Annotated[list[int], Query(...)]) -> ResponseModel:
+async def delete_opera_log(pk: Annotated[list[int], Query(description='操作日志 ID 列表')]) -> ResponseModel:
     count = await opera_log_service.delete(pk=pk)
     if count > 0:
         return response_base.success()

backend/app/admin/api/v1/monitor/redis.py

@@ -19,5 +19,8 @@
     ],
 )
 async def get_redis_info() -> ResponseModel:
-    data = {'info': await redis_info.get_info(), 'stats': await redis_info.get_stats()}
+    data = {
+        'info': await redis_info.get_info(),
+        'stats': await redis_info.get_stats(),
+    }
     return response_base.success(data=data)

backend/app/admin/api/v1/oauth2/linux_do.py

@@ -19,16 +19,16 @@
 _linux_do_oauth2 = FastAPIOAuth20(_linux_do_client, admin_settings.OAUTH2_LINUX_DO_REDIRECT_URI)
 
 
-@router.get('', summary='获取 Linux Do 授权链接')
+@router.get('', summary='获取 LinuxDo 授权链接')
 async def linux_do_auth2() -> ResponseSchemaModel[str]:
     auth_url = await _linux_do_client.get_authorization_url(redirect_uri=admin_settings.OAUTH2_LINUX_DO_REDIRECT_URI)
     return response_base.success(data=auth_url)
 
 
 @router.get(
     '/callback',
-    summary='Linux Do 授权自动重定向',
-    description='Linux Do 授权后，自动重定向到当前地址并获取用户信息，通过用户信息自动创建系统用户',
+    summary='LinuxDo 授权自动重定向',
+    description='LinuxDo 授权后，自动重定向到当前地址并获取用户信息，通过用户信息自动创建系统用户',
     dependencies=[Depends(RateLimiter(times=5, minutes=1))],
 )
 async def linux_do_login(
@@ -45,6 +45,6 @@ async def linux_do_login(
         response=response,
         background_tasks=background_tasks,
         user=user,
-        social=UserSocialType.linuxdo,
+        social=UserSocialType.linux_do,
     )
     return RedirectResponse(url=f'{admin_settings.OAUTH2_FRONTEND_REDIRECT_URI}?access_token={data.access_token}')

backend/app/admin/api/v1/sys/__init__.py

@@ -16,7 +16,7 @@
 
 router = APIRouter(prefix='/sys')
 
-router.include_router(config_router, prefix='/configs', tags=['系统配置'])
+router.include_router(config_router, prefix='/configs', tags=['系统参数配置'])
 router.include_router(dept_router, prefix='/depts', tags=['系统部门'])
 router.include_router(dict_data_router, prefix='/dict-datas', tags=['系统字典数据'])
 router.include_router(dict_type_router, prefix='/dict-types', tags=['系统字典类型'])