Skip to main content

Vivid Token (VT) 및 크레딧 시스템 설계

최종 수정일: 2026년 1월 19일 상태: 구현 완료

1. 개요 (Overview)​

vivid-ai 서비스의 내부 경제 시스템인 Vivid Token (VT) 시스템의 설계 및 구현 명세입니다. 사용자에게는 'Vivid Token'이라는 명칭으로 서비스 가치를 제공하며, 시스템 내부 코드에서는 이를 **Credit(크레딧)**이라는 단위로 관리합니다.

2. 핵심 원칙 (Core Principles)​

A. 명칭 정의​

  • Vivid Token (VT): 사용자에게 노출되는 서비스 내 공식 화폐 명칭입니다.
  • Credit (크레딧): 시스템 백엔드 코드, DB 테이블, API 내부에서 사용되는 기술적 명칭입니다. (예: CreditsService, Wallet.balance)

B. 데이터 무결성 및 동시성 제어​

  • 비관적 락 (Pessimistic Locking): 잔액 변경 시 TypeORM의 setLock('pessimistic_write')를 사용하여 데이터 경쟁 상태(Race Condition)를 원천 차단합니다.
  • 정밀도 보장: PostgreSQL의 DECIMAL(15, 2) 타입을 사용하여 부동소수점 연산 오차를 방지합니다.

C. 가입 및 지갑 생성​

  • 자동 생성: UsersService.findOrCreate 로직 내에서 지갑이 없는 유저에 대해 자동으로 지갑을 생성합니다.
  • 초기 잔액 0 VT: 어뷰징 방지를 위해 기본 잔액은 0으로 설정됩니다.

3. 상세 사양 (Specifications)​

A. 트랜잭션 유형 (CreditTransactionType)​

시스템 자동 로직과 관리자 수동 개입을 명확히 분리하여 관리합니다.

타입명칭방향설명
CHARGE결제 충전+사용자가 PG 또는 Web3 결제를 통해 토큰을 구매한 경우
USE서비스 사용-이미지/비디오 생성 시 워크플로우 가격에 따라 차감
REFUND자동 환불+생성 작업이 실패(FAILED)했을 때 시스템에 의해 자동 복구
BONUS시스템 보너스+이벤트 참여 등 시스템 로직에 의해 지급되는 보너스
CANCEL취소 복구+사용자의 요청 또는 시스템 오류로 인한 결제/사용 취소 시 복구
ADMIN_ADD관리자 지급+관리자 관리 도구에서 수동으로 지급 (운영 목적)
ADMIN_SUBTRACT관리자 회수-관리자 관리 도구에서 수동으로 회수 (운영 목적)

B. 품질 기반 동적 가격 정책 (Quality-based Pricing)​

생성 작업 시 사용되는 워크플로우 템플릿에 따라 차등적인 비용이 발생합니다.

  • SD (Standard Definition): 워크플로우의 priceSD 필드 값을 사용. (기본값: 1.0 VT)
  • HD (High Definition): 워크플로우의 priceHD 필드 값을 사용. (기본값: 3.0 VT)
  • FHD (Full High Definition): 워크플로우의 priceFHD 필드 값을 사용. (기본값: 5.0 VT)
  • Batch Size 연동: 최종 비용 = 단가(SD/HD/FHD) * batch_size.

C. 자동 환불 정책 (Auto-Refund Policy)​

시스템 장애, 연산 서버(Worker)의 비정상 종료, 또는 과도한 대기 상황에서 사용자의 자산을 보호하기 위해 다음과 같은 경우 자동으로 작업을 취소하고 전액 환불합니다.

  1. 명시적 실패 (Explicit Failure)
    • 조건: 작업 상태가 FAILED로 변경되는 즉시.
    • 동작: 사용된 크레딧을 즉시 지갑으로 환불(REFUND 타입).
  2. 대기 시간 초과 (Queue Timeout)
    • 조건: 작업이 SQS 대기열(PENDING) 상태에서 1시간 이상 머무를 경우. (예: 가용 워커가 하나도 없는 상황)
    • 동작: 시스템 스케줄러가 작업을 FAILED 처리하고 자동 환불.
  3. 워커 응답 없음 (Worker Crash / Zombie Task)
    • 조건: 작업 중(PROCESSING)인 워커로부터 10분 이상 진행률 업데이트(Redis/DB)가 없는 경우.
    • 동작: 워커 프로세스 장애로 간주하여 작업을 FAILED 처리하고 자동 환불.

4. 관리자 관리 기능 (Admin Features)​

관리자 페이지(/admin/users)를 통해 유저별 크레딧을 정밀하게 관리할 수 있습니다.

  1. 유저 목록 조회:
    • 모든 유저의 Wallet 주소와 현재 VT 잔액을 실시간으로 확인.
    • 지갑 주소, 닉네임, UUID를 통한 검색 지원.
    • 잔액, 가입일 등 주요 지표 기준 정렬 지원.
  2. 수동 조정 도구:
    • 특정 유저 상세 페이지에서 ADMIN_ADD / ADMIN_SUBTRACT 타입을 사용하여 즉시 잔액 수정.
    • 조정 시 반드시 '사유(Reason)'를 입력하도록 하여 감사(Audit) 로그 보존.

5. 기술적 구현 상세​

  • Backend: src/credits 모듈에서 캡슐화되어 관리됨. DataSource를 통한 수동 트랜잭션 제어로 원자성(Atomicity) 보장.
  • Frontend: React Query 기반의 useCredits 훅을 통해 실시간 잔액을 Sidebar 및 팝업에 동기화.
  • Common Enum: 백엔드와 프론트엔드 간의 타입 일치를 위해 CreditTransactionType 전역 관리.