清理项目配置文件，移除不再使用的.idea文件和更新文档中的Python版本要求

pkg/password.py

@@ -2,18 +2,32 @@ import secrets
 from loguru import logger
 from argon2 import PasswordHasher
 from argon2.exceptions import VerifyMismatchError
+from enum import StrEnum
 
 _ph = PasswordHasher()
 
-class Password():
+class PasswordStatus(StrEnum):
+    """密码校验状态枚举"""
+
+    VALID = "valid"
+    """密码校验通过"""
+
+    INVALID = "invalid"
+    """密码校验失败"""
+
+    EXPIRED = "expired"
+    """密码哈希已过时，建议重新哈希"""
+
+class Password:
+    """密码处理工具类，包含密码生成、哈希和验证功能"""
 
     @staticmethod
     def generate(
-        length: int = 8
+            length: int = 8
     ) -> str:
         """
         生成指定长度的随机密码。
-        
+
         :param length: 密码长度
         :type length: int
         :return: 随机密码
@@ -23,7 +37,7 @@ class Password():
 
     @staticmethod
     def hash(
-        password: str
+            password: str
     ) -> str:
         """
         使用 Argon2 生成密码的哈希值。
@@ -37,38 +51,29 @@ class Password():
 
     @staticmethod
     def verify(
-        stored_password: str,
-        provided_password: str,
-        debug: bool = False
-    ) -> bool:
+            hash: str,
+            password: str
+    ) -> PasswordStatus:
         """
         验证存储的 Argon2 哈希值与用户提供的密码是否匹配。
 
-        :param stored_password: 数据库中存储的 Argon2 哈希字符串
-        :param provided_password: 用户本次提供的密码
-        :param debug: 是否输出调试信息
+        :param hash: 数据库中存储的 Argon2 哈希字符串
+        :param password: 用户本次提供的密码
         :return: 如果密码匹配返回 True, 否则返回 False
         """
-        if debug:
-            logger.info(f"验证密码: (哈希) {stored_password}")
-
         try:
             # verify 函数会自动解析 stored_password 中的盐和参数
-            _ph.verify(stored_password, provided_password)
+            _ph.verify(hash, password)
 
             # 检查哈希参数是否已过时。如果返回True，
             # 意味着你应该使用新的参数重新哈希密码并更新存储。
             # 这是一个很好的实践，可以随着时间推移增强安全性。
-            if _ph.check_needs_rehash(stored_password):
+            if _ph.check_needs_rehash(hash):
                 logger.warning("密码哈希参数已过时，建议重新哈希并更新。")
+                return PasswordStatus.EXPIRED
 
-            return True
+            return PasswordStatus.VALID
         except VerifyMismatchError:
             # 这是预期的异常，当密码不匹配时触发。
-            if debug:
-                logger.info("密码不匹配")
-            return False
-        except Exception as e:
-            # 捕获其他可能的错误
-            logger.error(f"密码验证过程中发生未知错误: {e}")
-            return False
+            return PasswordStatus.INVALID
+        # 其他异常（如哈希格式错误）应该传播，让调用方感知系统问题

pkg/utils.py

@@ -16,7 +16,7 @@ from starlette.status import (
     HTTP_504_GATEWAY_TIMEOUT, 
 )
 
-# --- Request and Response Helpers ---
+# --- 400 ---
 
 def ensure_request_param(to_check: Any, detail: str) -> None:
     """
@@ -30,21 +30,21 @@ def raise_bad_request(detail: str = '') -> NoReturn:
     """Raises an HTTP 400 Bad Request exception."""
     raise HTTPException(status_code=HTTP_400_BAD_REQUEST, detail=detail)
 
-def raise_not_found(detail: str) -> NoReturn:
-    """Raises an HTTP 404 Not Found exception."""
-    raise HTTPException(status_code=HTTP_404_NOT_FOUND, detail=detail)
+def raise_unauthorized(detail: str) -> NoReturn:
+    """Raises an HTTP 401 Unauthorized exception."""
+    raise HTTPException(status_code=HTTP_401_UNAUTHORIZED, detail=detail)
 
-def raise_internal_error(detail: str = "服务器出现故障，请稍后再试或联系管理员") -> NoReturn:
-    """Raises an HTTP 500 Internal Server Error exception."""
-    raise HTTPException(status_code=HTTP_500_INTERNAL_SERVER_ERROR, detail=detail)
+def raise_insufficient_quota(detail: str = "积分不足，请充值") -> NoReturn:
+    """Raises an HTTP 402 Payment Required exception."""
+    raise HTTPException(status_code=HTTP_402_PAYMENT_REQUIRED, detail=detail)
 
 def raise_forbidden(detail: str) -> NoReturn:
     """Raises an HTTP 403 Forbidden exception."""
     raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail=detail)
 
-def raise_unauthorized(detail: str) -> NoReturn:
-    """Raises an HTTP 401 Unauthorized exception."""
-    raise HTTPException(status_code=HTTP_401_UNAUTHORIZED, detail=detail)
+def raise_not_found(detail: str) -> NoReturn:
+    """Raises an HTTP 404 Not Found exception."""
+    raise HTTPException(status_code=HTTP_404_NOT_FOUND, detail=detail)
 
 def raise_conflict(detail: str) -> NoReturn:
     """Raises an HTTP 409 Conflict exception."""
@@ -54,6 +54,12 @@ def raise_too_many_requests(detail: str) -> NoReturn:
     """Raises an HTTP 429 Too Many Requests exception."""
     raise HTTPException(status_code=HTTP_429_TOO_MANY_REQUESTS, detail=detail)
 
+# --- 500 ---
+
+def raise_internal_error(detail: str = "服务器出现故障，请稍后再试或联系管理员") -> NoReturn:
+    """Raises an HTTP 500 Internal Server Error exception."""
+    raise HTTPException(status_code=HTTP_500_INTERNAL_SERVER_ERROR, detail=detail)
+
 def raise_not_implemented(detail: str = "尚未支持这种方法") -> NoReturn:
     """Raises an HTTP 501 Not Implemented exception."""
     raise HTTPException(status_code=HTTP_501_NOT_IMPLEMENTED, detail=detail)
@@ -65,8 +71,3 @@ def raise_service_unavailable(detail: str) -> NoReturn:
 def raise_gateway_timeout(detail: str) -> NoReturn:
     """Raises an HTTP 504 Gateway Timeout exception."""
     raise HTTPException(status_code=HTTP_504_GATEWAY_TIMEOUT, detail=detail)
-
-def raise_insufficient_quota(detail: str = "积分不足，请充值") -> NoReturn:
-    raise HTTPException(status_code=HTTP_402_PAYMENT_REQUIRED, detail=detail)
-
-# --- End of Request and Response Helpers ---