# 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. 모니터링 및 로깅 인프라 설정
```