提交注释

lintsinghua · guimo3 · Mar 6, 2026 · Mar 6, 2026 · Mar 11, 2026 · Mar 6, 2026
commit bc3a5e3fdccb3175315fc6ae977e9daf412020a5
diff --git a/backend/alembic/env.py b/backend/alembic/env.py
@@ -1,3 +1,7 @@
+"""
+模块说明：Alembic 迁移环境与配置入口。
+"""
+
 import asyncio
 from logging.config import fileConfig


diff --git a/backend/app/__init__.py b/backend/app/__init__.py
@@ -0,0 +1,3 @@
+"""
+模块说明：包初始化与导出。
+"""
diff --git a/backend/app/api/__init__.py b/backend/app/api/__init__.py
@@ -0,0 +1,3 @@
+"""
+模块说明：API 路由与依赖定义：__init__。
+"""
diff --git a/backend/app/api/deps.py b/backend/app/api/deps.py
@@ -1,3 +1,7 @@
+"""
+模块说明：API 路由与依赖定义：deps。
+"""
+
 from typing import Generator, Optional
 from fastapi import Depends, HTTPException, status
 from fastapi.security import OAuth2PasswordBearer
@@ -19,32 +23,56 @@ async def get_current_user(
    db: AsyncSession = Depends(get_db),
    token: str = Depends(reusable_oauth2)
 ) -> User:
+    """
+    从请求令牌解析并返回当前用户。
+
+    处理流程：
+    - 解析并校验 JWT
+    - 构建 TokenPayload
+    - 查询用户并校验状态
+    """
+    # 解析并验证 JWT
    try:
+        # 解码令牌载荷
        payload = jwt.decode(
            token, settings.SECRET_KEY, algorithms=[security.ALGORITHM]
        )
+        # 将载荷解析为结构化数据
        token_data = token_schema.TokenPayload(**payload)
    except (JWTError, ValidationError):
+        # 令牌无效或格式不正确时返回 401
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="无法验证凭据",
            headers={"WWW-Authenticate": "Bearer"},
        )
-
+    # 查询用户记录
    result = await db.execute(select(User).where(User.id == token_data.sub))
+    # 提取用户对象
    user = result.scalars().first()
-
+    # 若用户不存在则返回 404
    if not user:
        raise HTTPException(status_code=404, detail="用户不存在")
+    # 若用户已被禁用则返回 400
    if not user.is_active:
        raise HTTPException(status_code=400, detail="用户已被禁用")
+    # 返回当前用户
    return user

 async def get_current_active_superuser(
    current_user: User = Depends(get_current_user),
 ) -> User:
+    """
+    校验当前用户是否为超级管理员。
+
+    处理流程：
+    - 依赖注入获取当前用户
+    - 检查超级管理员标识
+    """
+    # 若非超级管理员则拒绝访问
    if not current_user.is_superuser:
        raise HTTPException(
            status_code=400, detail="权限不足"
        )
+    # 返回通过校验的用户
    return current_user
diff --git a/backend/app/api/v1/__init__.py b/backend/app/api/v1/__init__.py
@@ -0,0 +1,3 @@
+"""
+模块说明：API 路由与依赖定义：__init__。
+"""
diff --git a/backend/app/api/v1/api.py b/backend/app/api/v1/api.py
@@ -1,3 +1,7 @@
+"""
+模块说明：API 路由与依赖定义：api。
+"""
+
 from fastapi import APIRouter
 from app.api.v1.endpoints import auth, users, projects, tasks, scan, members, config, database, prompts, rules, agent_tasks, embedding_config, ssh_keys


diff --git a/backend/app/api/v1/endpoints/__init__.py b/backend/app/api/v1/endpoints/__init__.py
@@ -0,0 +1,3 @@
+"""
+模块说明：API 路由与依赖定义：__init__。
+"""