hansoo/Obsidian

Fork 0

Files

hansoo 266674cc0e 초기 커밋

2025-03-26 18:16:46 +09:00

4.4 KiB

Raw Blame History

ZELLYY Core와 서비스 간 통신 설계

개요

이 문서는 ZELLYY Core와 각 서비스(적자 탈출 가계부, Subscription Manager, ZELLYY Card) 간의 통신 구조와 API 설계를 정의합니다.

통신 아키텍처

기본 원칙

API 게이트웨이 패턴 - 모든 요청은 ZELLYY Core API 게이트웨이를 통해 라우팅
JWT 기반 인증 - 모든 서비스 간 통신은 JWT 토큰으로 인증
이벤트 기반 통신 - 서비스 간 데이터 동기화는 이벤트 기반으로 구현

통신 흐름

클라이언트 → ZELLYY Core API → 개별 서비스 API
            ↑        ↓
            └─ Supabase Auth

API 엔드포인트 구조

Core API (공통)

/api/v1/auth     # 인증 관련 API
  /login         # 로그인
  /register      # 회원가입
  /refresh-token # 토큰 갱신
  /logout        # 로그아웃
  /verify-email  # 이메일 인증

/api/v1/users    # 사용자 관리 API
  /me            # 현재 사용자 정보
  /services      # 사용자의 서비스 접근 권한
  /profile       # 프로필 관리

/api/v1/services # 서비스 관리 API
  /list          # 사용 가능한 서비스 목록
  /switch        # 서비스 전환
  /access        # 서비스 접근 권한 관리

서비스별 API

각 서비스는 다음 패턴으로 API를 제공:

/api/v1/{service-name}/...  # 서비스별 고유 API

예: 적자 탈출 가계부 API

/api/v1/budget/accounts     # 계좌 관리
/api/v1/budget/transactions # 거래 내역
/api/v1/budget/categories   # 카테고리 관리
/api/v1/budget/reports      # 리포트 생성

인증 및 권한 부여

JWT 구조

{
  "sub": "user-uuid",        // 사용자 ID
  "iss": "zellyy-core",      // 토큰 발행자
  "exp": 1634567890,         // 만료 시간
  "iat": 1634564290,         // 발행 시간
  "services": ["budget", "subscription"], // 접근 가능한 서비스
  "roles": {                 // 서비스별 사용자 역할
    "budget": "admin",
    "subscription": "user"
  }
}

권한 검증 흐름

클라이언트가 요청 시 JWT를 Authorization 헤더에 포함
Core API 게이트웨이에서 토큰 유효성 검증
요청된 서비스에 대한 접근 권한 확인
권한이 있으면 요청을 해당 서비스로 라우팅, 없으면 403 Forbidden 반환

데이터 공유 메커니즘

서비스 간 직접 데이터 접근

제한된 상황에서만 허용:

// 예: 구독 관리자가 가계부 데이터에 접근해야 하는 경우
const subscriptionCost = await coreAPI.fetchFromService({
  service: 'budget',
  endpoint: '/api/v1/budget/transactions',
  query: { 
    category: 'subscriptions',
    timeframe: 'monthly' 
  }
});

이벤트 기반 데이터 동기화

서비스 간 데이터 일관성을 위한 이벤트 발행/구독 패턴:

// 이벤트 정의 예시
{
  "type": "transaction.created",
  "service": "budget",
  "payload": {
    "user_id": "user-uuid",
    "amount": 9900,
    "category": "subscription",
    "description": "Netflix 월 구독"
  },
  "timestamp": "2023-10-18T15:30:00Z"
}

에러 처리 및 로깅

표준 에러 응답 형식

{
  "error": {
    "code": "auth/invalid-credentials",
    "message": "이메일 또는 비밀번호가 올바르지 않습니다.",
    "details": { ... }
  },
  "requestId": "req-uuid-123456"
}

중앙 집중식 로깅

모든 서비스는 구조화된 로그를 Core의 중앙 로깅 시스템으로 전송:

logger.info('user.login.success', {
  userId: 'user-uuid',
  service: 'budget',
  device: 'mobile-ios',
  ipAddress: '192.168.1.1'
});

API 버저닝 및 하위 호환성

URL 기반 버저닝 - /api/v1/..., /api/v2/...
점진적 변경 - 하위 호환성을 유지하며 API 발전
폐기 정책 - API 변경 시 충분한 마이그레이션 기간 제공

성능 최적화

API 캐싱 - 자주 요청되는 데이터 캐싱
일괄 요청 - 여러 리소스를 한 번에 요청할 수 있는 배치 API 제공
필드 필터링 - 클라이언트가 필요한 필드만 요청할 수 있는 기능

다음 단계

API 게이트웨이 구현 및 테스트
서비스별 API 스펙 상세 정의
인증 및 권한 부여 시스템 구현
모니터링 및 로깅 인프라 설정

4.4 KiB Raw Blame History