feat(settings): Add StorageSettings for shared storage configuration

[ywkim]

개요

공용 라이브러리로 사용할 Google Cloud Storage 설정을 aioia_core에 추가합니다.

변경사항

StorageSettings 클래스 추가

• 위치: aioia_core/settings.py
• 필드:
  • enabled (bool): GCS 활성화 여부 (기본값: False)
  • bucket_name (str): GCS 버킷명
  • project_id (str | None): Google Cloud 프로젝트 ID
  • credentials_path (str | None): 서비스 계정 JSON 키 파일 경로
  • credentials_json (str | None): 서비스 계정 자격증명 JSON 문자열

환경변수 설정

STORAGE_ 프리픽스를 사용하여 다음과 같이 설정:

STORAGE_ENABLED=true
STORAGE_BUCKET_NAME=my-bucket
STORAGE_PROJECT_ID=my-project
STORAGE_CREDENTIALS_PATH=/path/to/key.json
STORAGE_CREDENTIALS_JSON={"type":"service_account",...}

테스트

• ✅ Lint: 10.00/10
• ✅ Type Check: No issues
• ✅ Unit Tests: 26/26 passed

[gemini-code-assist]

Code Review

이 PR은 aioia_core에 공용 Google Cloud Storage 설정을 위한 StorageSettings 클래스를 추가합니다. 전반적으로 깔끔하게 작성되었으며, pydantic-settings를 활용하여 환경 변수로부터 설정을 잘 불러오고 있습니다. 다만, enabled가 True일 때 필수 필드인 bucket_name이 설정되었는지 확인하는 유효성 검사 로직을 추가하면 코드가 더욱 견고해질 것입니다. 관련하여 상세한 리뷰 의견을 남겼습니다.

[gemini-code-assist]

StorageSettings 클래스에 enabled가 True일 때 bucket_name이 설정되었는지 확인하는 유효성 검사기를 추가하는 것이 좋습니다.

현재 enabled가 True이고 bucket_name이 빈 문자열이면, 나중에 GCS 클라이언트를 사용하려고 할 때 런타임 오류가 발생할 수 있습니다.

FishAudioSettings나 HedraSettings의 check_api_key처럼 model_validator를 사용하여 설정이 로드될 때 이를 검증하면 더 안전한 코드가 됩니다.

class StorageSettings(BaseSettings):
    """
    Storage settings class for configuring storage clients.

    Environment variables:
        STORAGE_ENABLED: Enable/disable Google Cloud Storage (default: False)
        STORAGE_BUCKET_NAME: The name of the Google Cloud Storage bucket to use
        STORAGE_PROJECT_ID: Google Cloud project ID (optional)
        STORAGE_CREDENTIALS_PATH: Path to the Google Cloud service account JSON key file (optional)
        STORAGE_CREDENTIALS_JSON: JSON string of Google Cloud service account credentials (optional)
    """

    INI_SECTION: ClassVar[str] = "storage"

    enabled: bool = False
    bucket_name: str = ""
    project_id: str | None = None
    credentials_path: str | None = None
    credentials_json: str | None = None

    @model_validator(mode="after")
    def check_bucket_name(self) -> "StorageSettings":
        """Validate that bucket_name is present if the service is enabled."""
        if self.enabled and not self.bucket_name:
            raise ValueError("Bucket name is required when storage is enabled.")
        return self

    class Config:
        env_prefix = "STORAGE_"

References

1. 개발 가이드의 'Guard Clause' 원칙(11번 라인)에 따라, 서비스 활성화 시 필수 값(bucket_name)을 미리 검증하여 런타임 오류를 방지하는 것이 좋습니다. ^(link)