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