feat(frontend):优化前端页面设计

kilostar/utils/access.py

@@ -14,46 +14,57 @@
 
 from __future__ import annotations
 
-import jwt
 import os
 from datetime import datetime, timedelta, timezone
-from typing import Optional
-from fastapi import HTTPException, status, Request
+from typing import TYPE_CHECKING, Optional
+
+import jwt
+from fastapi import HTTPException, Request, status
 from pydantic import BaseModel, ValidationError
 from pwdlib import PasswordHash
 
+if TYPE_CHECKING:
+    from kilostar.core.postgres_database.model.user import User
+
+
+ALGORITHM = "HS256"
+ACCESS_TOKEN_EXPIRE_MINUTES = 60 * 24
+_INSECURE_SECRETS = {"secret", "114514", "changethiskey12345"}
+
 
 class TokenData(BaseModel):
-    """TokenData 核心组件类。
-    这是一个领域数据模型或功能封装类，承载了 TokenData 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。"""
+    """JWT 解码后的用户身份载荷。"""
 
     user_id: str
     username: Optional[str] = None
     exp: Optional[int] = None
 
 
-SECRET_KEY = os.getenv("SECRET_KEY")
-ALGORITHM = "HS256"
-ACCESS_TOKEN_EXPIRE_MINUTES = 60 * 24
+def _get_secret_key() -> str:
+    """读取并校验 SECRET_KEY 环境变量。
+
+    校验在首次实际使用 JWT 时进行，避免在模块导入阶段抛错，
+    从而把"环境约束"和"模块加载"解耦。
+    """
+    key = os.getenv("SECRET_KEY")
+    if not key or key in _INSECURE_SECRETS:
+        raise RuntimeError(
+            "未提供有效的 SECRET_KEY 或使用了不安全的默认值，请设置一个高熵的随机字符串"
+        )
+    return key
 
-if not SECRET_KEY or SECRET_KEY in {"secret", "114514"}:
-    raise RuntimeError("未提供有效的 SECRET_KEY 或使用了不安全的默认值")
 
 password_hasher = PasswordHash.recommended()
 
 
 class Accessor:
-    """Accessor 核心组件类。
-    这是一个领域数据模型或功能封装类，承载了 Accessor 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。"""
+    """封装认证与口令哈希相关的静态工具方法。"""
 
     @staticmethod
     def _decode_token(token: str) -> TokenData:
-        """执行与  decode token 相关的核心业务流转操作。
-        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
-        Args:        token (str): 由认证中心颁发的 JWT 或长期访问令牌，用于跨服务调用时的身份自证与权限校验。
-        Returns:         (TokenData): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """解码并校验 JWT，返回 TokenData；过期或无效时抛 401。"""
         try:
-            payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+            payload = jwt.decode(token, _get_secret_key(), algorithms=[ALGORITHM])
             return TokenData(**payload)
         except jwt.ExpiredSignatureError:
             raise HTTPException(
@@ -68,31 +79,22 @@ class Accessor:
 
     @staticmethod
     def _create_access_token(data: dict) -> str:
-        """创建并持久化新的  access token 实体。
-        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
-        Args:        data (dict): 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。
-        Returns:         (str): 处理流程所输出的具体字符串产物，可能是新生成的 ID 序列、格式化好的文本片段或 LLM 推理的回答内容。"""
+        """根据 payload 生成带过期时间的 JWT 访问令牌。"""
         to_encode = data.copy()
         expire = datetime.now(timezone.utc) + timedelta(
             minutes=ACCESS_TOKEN_EXPIRE_MINUTES
         )
         to_encode.update({"exp": int(expire.timestamp())})
-        return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
+        return jwt.encode(to_encode, _get_secret_key(), algorithm=ALGORITHM)
 
     @staticmethod
     def verify_password(plain_password: str, hashed_password: str) -> bool:
-        """执行与 verify password 相关的核心业务流转操作。
-        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
-        Args:        plain_password (str): 控制逻辑流向的具体字符串参数，指定了期望的 plain password 内容。        hashed_password (str): 控制逻辑流向的具体字符串参数，指定了期望的 hashed password 内容。
-        Returns:         (bool): 一个布尔型结果标志，明确返回 True 表示该操作成功应用或条件达成，False 则表示失败或被拒绝。"""
+        """校验明文口令是否匹配数据库中存储的哈希。"""
         return password_hasher.verify(plain_password, hashed_password)
 
     @staticmethod
     def get_current_user(request: Request) -> TokenData:
-        """检索并获取特定的 current user 数据集合或实例对象。
-        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
-        Args:        request (Request): FastAPI 框架注入的原生 HTTP 请求对象，包含了完整的 Header 标头、查询参数和正文流。
-        Returns:         (TokenData): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """从 Authorization Bearer 头解析当前请求的用户身份。"""
         auth_header = request.headers.get("Authorization")
         if not auth_header or not auth_header.startswith("Bearer "):
             raise HTTPException(
@@ -103,11 +105,8 @@ class Accessor:
         return Accessor._decode_token(token)
 
     @staticmethod
-    def login_hashed_password(user: User, password: str) -> str:
-        """执行与 login hashed password 相关的核心业务流转操作。
-        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
-        Args:        user (User): 当前已通过鉴权流程的访问者实体对象，内部包含用户角色、权限层级及租户归属等核心元信息。        password (str): 控制逻辑流向的具体字符串参数，指定了期望的 password 内容。
-        Returns:         (str): 处理流程所输出的具体字符串产物，可能是新生成的 ID 序列、格式化好的文本片段或 LLM 推理的回答内容。"""
+    def login_hashed_password(user: "User", password: str) -> str:
+        """完成登录核验：找不到用户或密码错误抛 401，否则签发新令牌。"""
         if not user:
             raise HTTPException(
                 status_code=status.HTTP_401_UNAUTHORIZED,
@@ -123,10 +122,7 @@ class Accessor:
 
     @staticmethod
     def hash_password(password: str) -> str:
-        """执行与 hash password 相关的核心业务流转操作。
-        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
-        Args:        password (str): 控制逻辑流向的具体字符串参数，指定了期望的 password 内容。
-        Returns:         (str): 处理流程所输出的具体字符串产物，可能是新生成的 ID 序列、格式化好的文本片段或 LLM 推理的回答内容。"""
+        """对明文口令做强哈希；空值或长度不足 6 位会抛 ValueError。"""
         if not password:
             raise ValueError("密码不能为空")
         if len(password) < 6: