Skip to main content

2025년 12월 변경 사항

  • Date: 2025-12-30
  • Documents:
  • Summary:
    • 워크플로우 시스템 아키텍처 대규모 개편 (Multi-Variant Workflow System):
      • 목적: 다양한 입력 조합(예: 이미지 1장, 2장 등)을 가진 워크플로우를 하나의 '상품'으로 묶어 관리하기 위함입니다.
      • 엔티티 구조 변경 (1:N):
        • 기존 단일 Workflow 엔티티를 삭제하고, **WorkflowGroup (Parent)**과 WorkflowVariant (Child) 구조로 분리했습니다.
        • WorkflowGroup: 상품명, 설명, 가격, 카테고리 등 메타데이터 관리.
        • WorkflowVariant: 실제 ComfyUI JSON, 매핑 정보, 그리고 inputConfig (입력 명세) 관리.
      • 동적 라우팅 로직 구현:
        • GenerationService가 사용자의 입력 데이터(텍스트/이미지 개수)를 분석하여, 해당 그룹 내에서 가장 적합한 Variant를 자동으로 찾아 실행하도록 개선 예정입니다.
      • 확장성 확보: 향후 비디오, 오디오 등 복합적인 입력이 필요한 모델도 코드 수정 없이 데이터(Variant) 추가만으로 지원 가능해질 예정입니다.
  • Date: 2025-12-29
  • Documents:
  • Summary:
    • 인프라 운영 및 트러블슈팅 가이드 문서화:
      • 환경 변수 및 시크릿 관리 가이드 (TROUBLESHOOTING_ENV_VARS.md):
        • Kubernetes Secret에 민감 정보(API Key 등)를 추가할 때 Base64 인코딩 및 YAML 파일 수정 방법을 상세히 기술했습니다.
        • Deployment 설정에서 name(코드상 변수명)과 key(시크릿 키 이름)의 매핑 중요성을 강조하고, 잘못된 매핑으로 인한 에러("Configuration key ... does not exist") 해결 방법을 안내했습니다.
        • Frontend에 공개 환경 변수(NEXT_PUBLIC_...)를 추가할 때 Secret 없이 직접 value로 주입하는 방법을 설명했습니다.
      • 리소스 부족 및 노드 장애 대응 가이드 (TROUBLESHOOTING_RESOURCES.md):
        • Pod가 Pending 상태에서 멈추는 원인이 CPU/Memory 요청량(requests) 초과임을 설명하고, YAML 파일에서 리소스 요청량을 줄이는 해결책을 제시했습니다.
        • 노드가 NotReady 상태일 때 AWS EC2 인스턴스를 강제 종료하여 Auto Scaling Group이 자동으로 새 노드를 생성하도록 유도하는 복구 절차를 문서화했습니다.
  • Date: 2025-12-26
  • Documents:
  • Summary:
    • 결제 시스템 (Payment System) 설계 및 명세 확정:
      • 방식 선정: 스마트 컨트랙트 배포 대신 "온체인 송금 + 백엔드 검증 (On-chain Transaction + Backend Verification)" 방식을 채택하여 개발 속도와 수수료 효율성을 극대화했습니다.
      • 아키텍처 정의: Wallet -> Blockchain -> Backend -> DB로 이어지는 결제 및 검증 파이프라인의 시퀀스 다이어그램을 작성했습니다.
      • 데이터 모델: 중복 처리를 방지하기 위한 Unique Index(txHash)가 적용된 PaymentHistory 엔티티 설계를 확정했습니다.
      • 보안 정책: 더블 스펜딩 방지, 수신자 지갑 검증, 금액 유효성 검사 등 핵심 보안 고려사항을 명시했습니다.
  • Date: 2025-12-22
  • Summary:
    • Vivid Token (VT) 및 크레딧 시스템 고도화 및 관리 기능 완성:
      • 핵심 로직: 비관적 락(pessimistic_write)을 적용한 CreditsService를 통해 동시성 문제를 해결하고 안전한 VT 차감/지급 로직을 완성했습니다.
      • 자동화 파이프라인: 생성 작업 실패 시 즉시 VT가 복구되는 자동 환불(REFUND) 시스템을 CreationsService에 통합했습니다.
      • 관리자 도구: 유저 목록에서 잔액 확인, 다중 조건 검색(주소, 닉네임, UUID), 정렬 기능을 추가하고, 상세 페이지에서 관리자가 직접 VT를 지급/회수(ADMIN_ADD, ADMIN_SUBTRACT)할 수 있는 기능을 구현했습니다.
      • 동적 가격제: 워크플로우 템플릿별로 SD/HD 단가를 설정하고, 배치 사이즈에 따라 최종 비용이 계산되도록 생성 로직을 개선했습니다.
      • 리팩토링: 레거시 coins 모듈을 완전히 제거하고 모든 명칭을 Credits와 Vivid Token으로 통일했습니다.
  • Date: 2025-12-19
  • Documents:
  • Summary:
    • Vivid Token (VT) 및 크레딧 시스템 설계 수립:
      • 명칭 확정: 사용자 노출 명칭은 Vivid Token (VT), 시스템 내부 명칭은 Credit으로 정의하여 외부 암호화폐와의 혼동을 방지했습니다.
      • 설계 원칙: 데이터 무결성(DECIMAL 타입), 동시성 제어(비관적 락), 독립성(은행 시스템 모델)을 핵심 원칙으로 정의했습니다.
      • 어뷰징 방지: 가입 시 초기 잔액을 0 VT로 설정하여 Sybil Attack을 원천 차단했습니다.
      • 아키텍처: Wallet(잔액)과 CreditTransaction(불변 원장) 엔티티를 정의하고, 입출금 로직을 독립적인 CreditsModule로 구현하는 계획을 수립했습니다.
  • Date: 2025-12-17
  • Documents:
  • Summary:
    • 실시간 이미지 생성 피드백 아키텍처 문서화 (Optimistic UI):
      • 아키텍처 명세 (ARCHITECTURE.md): API 응답이 PENDING 상태여도 프론트엔드에서 이미지를 즉시 표시할 수 있는 원리인 '낙관적 업데이트(Optimistic Update)' 및 '캐시 직접 주입(Cache Injection)' 메커니즘을 상세히 기술했습니다.
      • 프론트엔드 문서 (frontend/README.md): WebSocket(IMAGE_ADDED) 이벤트를 수신하여 React Query 캐시를 실시간으로 수정하는 하이브리드 데이터 동기화 로직을 설명하는 섹션을 추가했습니다.
      • 백엔드 문서 (backend/README.md): AiRealtimeGateway가 Redis Pub/Sub을 통해 AI 서버의 이벤트를 수신하고 프론트엔드로 중계하는 '메시지 브로드캐스터(Message Broadcaster)' 역할을 수행함을 명확히 했습니다.
  • Date: 2025-12-11
  • Documents:
  • Summary:
    • 워크플로우 템플릿 관리 시스템 아키텍처 대규모 개편:
      • 역할 재정의:
        • Required Mappings: 워크플로우 내 노드와의 연결(Mapping) 정보만 관리하도록 역할을 축소했습니다. (단, Seed는 예외적으로 포함)
        • User Inputs: 사용자가 입력하는 모든 필드(필수/선택)의 스키마, 유효성 검사(min/max), 기본값(defaultValue) 설정을 전담하도록 역할을 확대했습니다.
      • 관리자(Admin) UI 개선:
        • 필수 파라미터 매핑 시 자동으로 User Inputs 항목을 생성하여 설정의 일관성을 보장합니다.
        • 이미 매핑된 노드 속성은 시각적으로 구분하여 중복 설정을 방지하고, 필수 항목은 삭제할 수 없도록 잠금 기능을 추가했습니다.
      • 백엔드 로직 리팩토링 (GenerationService):
        • queueGenerationJobFromTemplate 메서드의 비대한 로직을 분리하여 Seed 생성, User Inputs 검증, 화이트리스트 검사, 값 주입 로직을 각각의 Private Helper 메서드로 추출했습니다.
        • 입력값이 없을 경우 User Inputs에 정의된 defaultValue를 자동으로 주입하는 로직을 강화했습니다.
      • 사용자 경험(UX) 개선:
        • 프론트엔드 생성 페이지에서 템플릿 선택 시, 설정된 기본값(특히 Default Prompt)이 입력창에 즉시 반영되도록 구현했습니다.
  • Date: 2025-12-09
  • Documents:
  • Summary:
    • 협업 및 온보딩 가이드 문서 생성:
      • 프론트엔드 동료 개발자를 위한 ONBOARDING.md 문서를 신설했습니다.
      • Git 전략: prod 중심의 브랜치 전략, dev 브랜치 격리, --no-ff 병합 규칙을 명시했습니다.
      • 개발 환경: Node.js v22.20.0 사용 및 환경 변수 설정 방법을 안내했습니다.
      • 백엔드 연동: Swagger, Web3 인증(apiClient), WebSocket 이벤트, S3 이미지 처리에 대한 핵심 내용을 요약했습니다.
  • Date: 2025-12-05
  • Documents:
  • Summary:
    • Post-Processing Worker Production 배포 및 문서화:
      • 전용 문서 신설: post-processing-worker의 아키텍처, 환경 변수, 배포 방법(Dev vs Prod)을 상세히 기술한 전용 문서를 작성했습니다.
      • Prod 환경 보안 강화 (IRSA): Prod 환경에서는 Access Key 대신 IAM Roles for Service Accounts (IRSA)를 사용하여 보안을 강화하고, 이를 인프라 문서에 반영했습니다.
      • Docker 보안: .dockerignore 설정 누락으로 인한 .env 노출 사고를 방지하기 위한 가이드를 추가했습니다.
      • 아키텍처 명세: 전체 시스템 아키텍처 문서에 후처리 워커의 역할(상태 업데이트, S3 업로드)과 데이터 흐름을 명확히 했습니다.
      • 로드맵 업데이트: Prod 워커 배포 완료 상태를 반영했습니다.
  • Date: 2025-12-04
  • Documents:
  • Summary:
    • Production 배포 트러블슈팅 및 보안 가이드 강화:
      • GitHub Actions OIDC 이슈 해결:
        • IAM OIDC Provider의 썸프린트가 유효하지 않아 발생하는 InvalidIdentityToken 에러 해결 방법(최신 DigiCert Root CA 썸프린트 업데이트)을 추가했습니다.
        • AWS IAM 역할 이름의 대소문자 구분(Github vs GitHub)으로 인한 AccessDenied 에러와 워크플로우 파일 수정 가이드를 추가했습니다.
        • GitHub Actions의 release 트리거가 태그 생성 시점의 코드 스냅샷을 사용하여, 워크플로우 수정 후에는 새 릴리스 발행이 필요함을 명시했습니다.
      • Kubernetes Secret 보안 및 인코딩:
        • Base64 인코딩 시 원본 데이터가 바이너리이거나 잘못되어 발생하는 CreateContainerError (Invalid UTF-8) 원인과 해결책을 추가했습니다.
        • Secret Manifest 파일을 Git에 커밋하지 않고, GitHub Secrets를 통해 배포 시점에 동적으로 생성하여 적용하는 보안 모범 사례를 CI/CD 섹션에 추가했습니다.
      • 클러스터 정리:
        • Dev 클러스터 내의 중복된 Deployment(backend-deployment, frontend-deployment)를 정리하고, 환경별 리소스(-dev 접미사) 관리 원칙을 재확인했습니다.