aiteamutils 0.2.31__tar.gz → 0.2.33__tar.gz

aiteamutils-0.2.33/.cursorrules

@@ -0,0 +1,90 @@
+- 에러 처리는 `core/app/utils/CustomException`의 `CustomException` 클래스를 사용:
+  - 형식: `CustomException(ErrorCode, detail=value, source_function="function_name")`
+  - **ErrorCode**: `core/app/utils/CustomException`에 정의된 값 사용.
+  - **detail**: 검증/처리 중인 값 자체만 포함 (예: 전화번호 검증 시 전화번호 값만)
+    - 단일 값: 해당 값만 포함 (예: `detail=phone_number`)
+    - 복합 값: 파이프(|)로 구분 (예: `detail=f"{table}|{column}|{value}"`)
+    - 추가 텍스트나 설명 없이 값만 포함
+  - **source_function**: 에러 발생 함수명을 문자열로 입력.
+  
+# 에러 처리 규칙
+1. 에러 응답 형식:
+   ```json
+   {
+       "error_code": 3003,        // 숫자 형식
+       "error_type": "DUPLICATE_ERROR",
+       "status_code": 409,
+       "path": "/companies",
+       "method": "POST",
+       "client_ip": "172.20.0.2",
+       "user_agent": "Mozilla/5.0..."
+   }
+   ```
+
+2. 에러 로그 형식:
+   ```json
+   {
+       "error_code": 3003,
+       "error_type": "DUPLICATE_ERROR",
+       "status_code": 409,
+       "path": "/companies",
+       "method": "POST",
+       "client_ip": "172.20.0.2",
+       "user_agent": "Mozilla/5.0...",
+       "detail": "companies|id|test-company",
+       "source_function": "DatabaseService.validate_unique_fields",
+       "error_chain": [
+           {
+               "error_code": "ErrorCode.DUPLICATE_ERROR",
+               "detail": "companies|id|test-company",
+               "source_function": "DatabaseService.validate_unique_fields",
+               "original_error": null
+           },
+           {
+               "error_code": "ErrorCode.DUPLICATE_ERROR",
+               "detail": "companies|id|test-company",
+               "source_function": "OrganizationRepository.create_company",
+               "original_error": null
+           }
+       ],
+       "original_error": null
+   }
+   ```
+
+3. detail 형식:
+   - 단일 필드 중복: `{테이블명}|{필드명}|{값}`
+   - 복수 필드 중복: `{테이블명}|{필드1}:{값1}|{필드2}:{값2}`
+   - 외래키 위반: `{참조테이블명}|{필드명}|{값}`
+   - 유효성 검사: `{검증값}`
+
+4. 에러 체인 구성:
+   - 에러는 최초 발생 지점부터 시작하여 호출 스택을 따라 전파
+   - 각 레이어는 자신의 컨텍스트 정보를 추가하여 에러를 상위로 전달
+   - `parent_source_function`을 통해 호출 경로 추적
+   - 원본 에러 정보는 `original_error`로 보존
+
+5. 레이어별 에러 처리:
+   - Database 레이어:
+     - 중복 검사: `DUPLICATE_ERROR`
+     - 외래키 위반: `FOREIGN_KEY_VIOLATION`
+     - 쿼리 실패: `DB_QUERY_ERROR`
+   - Repository 레이어:
+     - 원본 에러 보존 및 컨텍스트 추가
+   - Service 레이어:
+     - 비즈니스 로직 실패: `INTERNAL_ERROR`
+     - 트랜잭션 실패: `TRANSACTION_ERROR`
+   - API 레이어:
+     - 입력값 검증: `VALIDATION_ERROR`
+     - 권한 검증: `UNAUTHORIZED`, `FORBIDDEN`
+
+6. 에러 처리 원칙:
+   - 클라이언트 응답에서는 `detail`, `source_function`, `error_chain` 제외
+   - 로그에는 모든 정보를 포함하여 디버깅 용이성 확보
+   - 에러는 발생 지점에서 바로 처리하고 적절한 에러 코드 사용
+   - 중첩된 try-except 블록 대신 early return 패턴 사용
+   - 모든 예외는 `CustomException`으로 변환하여 일관된 처리
+
+7. 에러 코드 관리:
+   - 모든 에러 코드는 `ErrorCode` enum에 정의
+   - 도메인별로 구분된 에러 코드 범위 사용
+   - 각 에러 코드는 고유한 숫자 값과 HTTP 상태 코드 매핑

{aiteamutils-0.2.31 → aiteamutils-0.2.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiteamutils
-Version: 0.2.31
+Version: 0.2.33
 Summary: AI Team Utilities
 Project-URL: Homepage, https://github.com/yourusername/aiteamutils
 Project-URL: Issues, https://github.com/yourusername/aiteamutils/issues

{aiteamutils-0.2.31 → aiteamutils-0.2.33}/aiteamutils/config.py

@@ -1,6 +1,7 @@
 """설정 모듈."""
 from typing import Union
 from .database import init_database_service
+from .exceptions import CustomException, ErrorCode
 
 class Settings:
     """기본 설정 클래스"""
@@ -74,8 +75,12 @@ def get_settings() -> Settings:
         Settings: 설정 객체
         
     Raises:
-        RuntimeError: 설정이 초기화되지 않은 경우
+        CustomException: 설정이 초기화되지 않은 경우
     """
     if _settings is None:
-        raise RuntimeError("Settings not initialized. Call init_settings first.")
+        raise CustomException(
+            ErrorCode.INTERNAL_ERROR,
+            detail="settings",
+            source_function="get_settings"
+        )
     return _settings 

{aiteamutils-0.2.31 → aiteamutils-0.2.33}/aiteamutils/database.py

@@ -26,10 +26,14 @@ def get_database_service() -> 'DatabaseService':
         DatabaseService: DatabaseService 인스턴스
         
     Raises:
-        RuntimeError: DatabaseService가 초기화되지 않은 경우
+        CustomException: DatabaseService가 초기화되지 않은 경우
     """
     if _database_service is None:
-        raise RuntimeError("DatabaseService not initialized. Call init_settings with db_url first.")
+        raise CustomException(
+            ErrorCode.DB_CONNECTION_ERROR,
+            detail="database_service",
+            source_function="get_database_service"
+        )
     return _database_service
 
 async def get_db() -> AsyncGenerator[AsyncSession, None]:
@@ -100,13 +104,21 @@ class DatabaseService:
             )
             self.db = session
         else:
-            raise ValueError("Either db_url or session must be provided")
+            raise CustomException(
+                ErrorCode.DB_CONNECTION_ERROR,
+                detail="db_url|session",
+                source_function="DatabaseService.__init__"
+            )
 
     @asynccontextmanager
     async def get_session(self) -> AsyncGenerator[AsyncSession, None]:
         """데이터베이스 세션을 생성하고 반환하는 비동기 컨텍스트 매니저."""
         if self.session_factory is None:
-            raise RuntimeError("Session factory not initialized")
+            raise CustomException(
+                ErrorCode.DB_CONNECTION_ERROR,
+                detail="session_factory",
+                source_function="DatabaseService.get_session"
+            )
         
         async with self.session_factory() as session:
             try:

{aiteamutils-0.2.31 → aiteamutils-0.2.33}/aiteamutils/dependencies.py

@@ -26,10 +26,14 @@ class ServiceRegistry:
             service_class (Type): Service 클래스
 
         Raises:
-            ValueError: 이미 등록된 서비스인 경우
+            CustomException: 이미 등록된 서비스인 경우
         """
         if name in self._services:
-            raise ValueError(f"Service '{name}' is already registered.")
+            raise CustomException(
+                ErrorCode.INTERNAL_ERROR,
+                detail=f"service|{name}",
+                source_function="ServiceRegistry.register"
+            )
         self._services[name] = (repository_class, service_class)
 
     def get(self, name: str) -> Tuple[Type, Type]:
@@ -42,10 +46,14 @@ class ServiceRegistry:
             Tuple[Type, Type]: (Repository 클래스, Service 클래스) 튜플
 
         Raises:
-            ValueError: 등록되지 않은 서비스인 경우
+            CustomException: 등록되지 않은 서비스인 경우
         """
         if name not in self._services:
-            raise ValueError(f"Service '{name}' is not registered.")
+            raise CustomException(
+                ErrorCode.NOT_FOUND,
+                detail=f"service|{name}",
+                source_function="ServiceRegistry.get"
+            )
         return self._services[name]
 
 # ServiceRegistry 초기화
@@ -60,10 +68,10 @@ def get_service(name: str):
     Returns:
         Callable: 서비스 인스턴스를 반환하는 의존성 함수
     """
-    def _get_service(db: AsyncSession = Depends(get_db)):
+    def _get_service(db_service: DatabaseService = Depends(get_database_service)):
         repository_class, service_class = service_registry.get(name)
-        repository = repository_class(db)
-        return service_class(repository, db)
+        repository = repository_class(db_service)
+        return service_class(repository, db_service)
     return _get_service
 
 oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/users/token")

{aiteamutils-0.2.31 → aiteamutils-0.2.33}/aiteamutils/security.py

@@ -157,8 +157,19 @@ def verify_password(plain_password: str, hashed_password: str) -> bool:
         
     Returns:
         bool: 비밀번호 일치 여부
+        
+    Raises:
+        CustomException: 비밀번호 검증 실패 시
     """
-    return pwd_context.verify(plain_password, hashed_password)
+    try:
+        return pwd_context.verify(plain_password, hashed_password)
+    except Exception as e:
+        raise CustomException(
+            ErrorCode.INVALID_PASSWORD,
+            detail=plain_password,
+            source_function="security.verify_password",
+            original_error=e
+        )
 
 def hash_password(password: str) -> str:
     """비밀번호를 해시화합니다.
@@ -168,8 +179,19 @@ def hash_password(password: str) -> str:
         
     Returns:
         str: 해시된 비밀번호
+        
+    Raises:
+        CustomException: 비밀번호 해시화 실패 시
     """
-    return pwd_context.hash(password)
+    try:
+        return pwd_context.hash(password)
+    except Exception as e:
+        raise CustomException(
+            ErrorCode.INTERNAL_ERROR,
+            detail=password,
+            source_function="security.hash_password",
+            original_error=e
+        )
 
 def rate_limit(
     max_requests: int,
@@ -288,10 +310,10 @@ async def create_jwt_token(
         required_fields = {"username", "ulid"}
         missing_fields = required_fields - set(user_data.keys())
         if missing_fields:
-            raise TokenCreationError(
-                detail=f"Missing required fields: {', '.join(missing_fields)}",
-                source_function="create_jwt_token",
-                token_type=token_type
+            raise CustomException(
+                ErrorCode.REQUIRED_FIELD_MISSING,
+                detail="|".join(missing_fields),
+                source_function="security.create_jwt_token"
             )
         
         if token_type == "access":
@@ -337,10 +359,10 @@ async def create_jwt_token(
                 algorithm=settings.JWT_ALGORITHM
             )
         except Exception as e:
-            raise TokenCreationError(
-                detail="Failed to encode JWT token",
-                source_function="create_jwt_token",
-                token_type=token_type,
+            raise CustomException(
+                ErrorCode.INTERNAL_ERROR,
+                detail=f"token|{token_type}",
+                source_function="security.create_jwt_token",
                 original_error=e
             )
         
@@ -362,13 +384,13 @@ async def create_jwt_token(
         
         return token
         
-    except (TokenCreationError, SecurityError) as e:
+    except CustomException as e:
         raise e
     except Exception as e:
-        raise SecurityError(
+        raise CustomException(
             ErrorCode.INTERNAL_ERROR,
             detail=str(e),
-            source_function="create_jwt_token",
+            source_function="security.create_jwt_token",
             original_error=e
         )
 
@@ -376,7 +398,18 @@ async def verify_jwt_token(
     token: str,
     expected_type: Optional[Literal["access", "refresh"]] = None
 ) -> Dict[str, Any]:
-    """JWT 토큰을 검증합니다."""
+    """JWT 토큰을 검증합니다.
+    
+    Args:
+        token: 검증할 JWT 토큰
+        expected_type: 예상되는 토큰 타입
+        
+    Returns:
+        Dict[str, Any]: 토큰 페이로드
+        
+    Raises:
+        CustomException: 토큰 검증 실패 시
+    """
     try:
         settings = get_settings()
         # 토큰 디코딩
@@ -390,25 +423,27 @@ async def verify_jwt_token(
         
         # 토큰 타입 검증 (expected_type이 주어진 경우에만)
         if expected_type and payload.get("token_type") != expected_type:
-            raise TokenError(
-                detail=f"Expected {expected_type} token but got {payload.get('token_type')}",
-                source_function="verify_jwt_token"
+            raise CustomException(
+                ErrorCode.INVALID_TOKEN,
+                detail=f"token|{expected_type}|{payload.get('token_type')}",
+                source_function="security.verify_jwt_token"
             )
         
         return payload
         
     except JWTError as e:
-        raise TokenError(
-            detail=str(e),
-            source_function="verify_jwt_token",
+        raise CustomException(
+            ErrorCode.INVALID_TOKEN,
+            detail=token[:10] + "...",
+            source_function="security.verify_jwt_token",
             original_error=e
         )
-    except (TokenError, SecurityError) as e:
+    except CustomException as e:
         raise e
     except Exception as e:
-        raise SecurityError(
+        raise CustomException(
             ErrorCode.INTERNAL_ERROR,
             detail=str(e),
-            source_function="verify_jwt_token",
+            source_function="security.verify_jwt_token",
             original_error=e
         ) 

aiteamutils-0.2.33/aiteamutils/version.py

@@ -0,0 +1,2 @@
+"""버전 정보"""
+__version__ = "0.2.33"

aiteamutils-0.2.31/aiteamutils/version.py

@@ -1,2 +0,0 @@
-"""버전 정보"""
-__version__ = "0.2.31"