초기 커밋

ZELLYY/zellyy core/core-service-communication.md

@@ -0,0 +1,170 @@
+# ZELLYY Core와 서비스 간 통신 설계
+
+## 개요
+
+이 문서는 ZELLYY Core와 각 서비스(적자 탈출 가계부, Subscription Manager, ZELLYY Card) 간의 통신 구조와 API 설계를 정의합니다.
+
+## 통신 아키텍처
+
+### 기본 원칙
+
+1. **API 게이트웨이 패턴** - 모든 요청은 ZELLYY Core API 게이트웨이를 통해 라우팅
+2. **JWT 기반 인증** - 모든 서비스 간 통신은 JWT 토큰으로 인증
+3. **이벤트 기반 통신** - 서비스 간 데이터 동기화는 이벤트 기반으로 구현
+
+### 통신 흐름
+
+```
+클라이언트 → 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 구조
+
+```javascript
+{
+  "sub": "user-uuid",        // 사용자 ID
+  "iss": "zellyy-core",      // 토큰 발행자
+  "exp": 1634567890,         // 만료 시간
+  "iat": 1634564290,         // 발행 시간
+  "services": ["budget", "subscription"], // 접근 가능한 서비스
+  "roles": {                 // 서비스별 사용자 역할
+    "budget": "admin",
+    "subscription": "user"
+  }
+}
+```
+
+### 권한 검증 흐름
+
+1. 클라이언트가 요청 시 JWT를 Authorization 헤더에 포함
+2. Core API 게이트웨이에서 토큰 유효성 검증
+3. 요청된 서비스에 대한 접근 권한 확인
+4. 권한이 있으면 요청을 해당 서비스로 라우팅, 없으면 403 Forbidden 반환
+
+## 데이터 공유 메커니즘
+
+### 서비스 간 직접 데이터 접근
+
+제한된 상황에서만 허용:
+
+```javascript
+// 예: 구독 관리자가 가계부 데이터에 접근해야 하는 경우
+const subscriptionCost = await coreAPI.fetchFromService({
+  service: 'budget',
+  endpoint: '/api/v1/budget/transactions',
+  query: { 
+    category: 'subscriptions',
+    timeframe: 'monthly' 
+  }
+});
+```
+
+### 이벤트 기반 데이터 동기화
+
+서비스 간 데이터 일관성을 위한 이벤트 발행/구독 패턴:
+
+```javascript
+// 이벤트 정의 예시
+{
+  "type": "transaction.created",
+  "service": "budget",
+  "payload": {
+    "user_id": "user-uuid",
+    "amount": 9900,
+    "category": "subscription",
+    "description": "Netflix 월 구독"
+  },
+  "timestamp": "2023-10-18T15:30:00Z"
+}
+```
+
+## 에러 처리 및 로깅
+
+### 표준 에러 응답 형식
+
+```json
+{
+  "error": {
+    "code": "auth/invalid-credentials",
+    "message": "이메일 또는 비밀번호가 올바르지 않습니다.",
+    "details": { ... }
+  },
+  "requestId": "req-uuid-123456"
+}
+```
+
+### 중앙 집중식 로깅
+
+모든 서비스는 구조화된 로그를 Core의 중앙 로깅 시스템으로 전송:
+
+```javascript
+logger.info('user.login.success', {
+  userId: 'user-uuid',
+  service: 'budget',
+  device: 'mobile-ios',
+  ipAddress: '192.168.1.1'
+});
+```
+
+## API 버저닝 및 하위 호환성
+
+1. **URL 기반 버저닝** - `/api/v1/...`, `/api/v2/...`
+2. **점진적 변경** - 하위 호환성을 유지하며 API 발전
+3. **폐기 정책** - API 변경 시 충분한 마이그레이션 기간 제공
+
+## 성능 최적화
+
+1. **API 캐싱** - 자주 요청되는 데이터 캐싱
+2. **일괄 요청** - 여러 리소스를 한 번에 요청할 수 있는 배치 API 제공
+3. **필드 필터링** - 클라이언트가 필요한 필드만 요청할 수 있는 기능
+
+## 다음 단계
+
+1. API 게이트웨이 구현 및 테스트
+2. 서비스별 API 스펙 상세 정의
+3. 인증 및 권한 부여 시스템 구현
+4. 모니터링 및 로깅 인프라 설정
+```