# Subscription Manager - API 설계

## 개요
이 문서는 Subscription Manager 앱의 API 설계를 정의합니다. 초기 MVP에서는 로컬 데이터베이스만 사용하지만, 향후 클라우드 동기화 및 외부 서비스 연동을 위한 API 설계를 미리 준비합니다.

## API 설계 원칙
- **RESTful 원칙 준수**: 자원 중심 설계, HTTP 메소드 활용
- **JSON 포맷**: 모든 요청/응답은 JSON 형식 사용
- **버전 관리**: API 경로에 버전 정보 포함 (예: /api/v1/...)
- **인증 필수**: 모든 API 요청은 인증 필요 (JWT 토큰 기반)
- **에러 처리 표준화**: 일관된 에러 응답 형식 제공

## 인증 및 보안
- **인증 방식**: JWT (JSON Web Token)
- **토큰 갱신**: Refresh Token 메커니즘 활용
- **HTTPS 필수**: 모든 API 통신은 HTTPS로 암호화
- **Rate Limiting**: 과도한 요청 방지를 위한 제한 적용

## API 엔드포인트

### 사용자 관리
```
POST   /api/v1/auth/register     - 사용자 등록
POST   /api/v1/auth/login        - 로그인
POST   /api/v1/auth/refresh      - 토큰 갱신
POST   /api/v1/auth/logout       - 로그아웃
GET    /api/v1/users/me          - 현재 사용자 정보 조회
PUT    /api/v1/users/me          - 사용자 정보 업데이트
```

### 구독 관리
```
GET    /api/v1/subscriptions     - 구독 목록 조회
POST   /api/v1/subscriptions     - 새 구독 추가
GET    /api/v1/subscriptions/:id - 특정 구독 조회
PUT    /api/v1/subscriptions/:id - 구독 정보 업데이트
DELETE /api/v1/subscriptions/:id - 구독 삭제
```

### 카테고리 관리
```
GET    /api/v1/categories        - 카테고리 목록 조회
POST   /api/v1/categories        - 새 카테고리 추가
GET    /api/v1/categories/:id    - 특정 카테고리 조회
PUT    /api/v1/categories/:id    - 카테고리 정보 업데이트
DELETE /api/v1/categories/:id    - 카테고리 삭제
```

### 결제 내역
```
GET    /api/v1/payments                      - 결제 내역 목록 조회
POST   /api/v1/payments                      - 새 결제 내역 추가
GET    /api/v1/payments/:id                  - 특정 결제 내역 조회
PUT    /api/v1/payments/:id                  - 결제 내역 업데이트
DELETE /api/v1/payments/:id                  - 결제 내역 삭제
GET    /api/v1/subscriptions/:id/payments    - 특정 구독의 결제 내역 조회
```

### 사용량 관리
```
GET    /api/v1/usages                       - 사용량 목록 조회
POST   /api/v1/usages                       - 새 사용량 기록 추가
GET    /api/v1/usages/:id                   - 특정 사용량 기록 조회
PUT    /api/v1/usages/:id                   - 사용량 기록 업데이트
DELETE /api/v1/usages/:id                   - 사용량 기록 삭제
GET    /api/v1/subscriptions/:id/usages     - 특정 구독의 사용량 기록 조회
```

### 분석 및 통계
```
GET    /api/v1/analytics/monthly            - 월별 비용 분석
GET    /api/v1/analytics/category           - 카테고리별 비용 분석
GET    /api/v1/analytics/trend              - 비용 추이 분석
GET    /api/v1/analytics/summary            - 요약 통계
```

### 설정 및 환경설정
```
GET    /api/v1/settings          - 설정 조회
PUT    /api/v1/settings          - 설정 업데이트
```

### 데이터 동기화
```
POST   /api/v1/sync              - 데이터 동기화 요청
GET    /api/v1/sync/status       - 동기화 상태 확인
```

### 미리 정의된 서비스
```
GET    /api/v1/predefined-services          - 미리 정의된 서비스 목록 조회
GET    /api/v1/predefined-services/:id      - 특정 미리 정의된 서비스 조회
```

## 요청/응답 형식

### 성공 응답 형식
```json
{
  "success": true,
  "data": { ... },
  "message": "성공 메시지"
}
```

### 에러 응답 형식
```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "에러 메시지",
    "details": { ... }
  }
}
```

## 주요 데이터 모델 (API 요청/응답용)

### 구독 (Subscription)
```json
{
  "id": "uuid-string",
  "name": "서비스 이름",
  "description": "서비스 설명",
  "amount": 9.99,
  "currency": "USD",
  "billingCycle": "monthly",
  "cycleDays": null,
  "startDate": "2023-01-01T00:00:00Z",
  "nextBillingDate": "2023-02-01T00:00:00Z",
  "categoryId": "category-uuid",
  "logoPath": "path/to/logo.png",
  "color": "#3A86FF",
  "reminderDays": 3,
  "notes": "사용자 메모",
  "isActive": true,
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-01T00:00:00Z"
}
```

### 카테고리 (Category)
```json
{
  "id": "uuid-string",
  "name": "카테고리 이름",
  "icon": "icon_code",
  "color": "#FF006E",
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-01T00:00:00Z"
}
```

### 결제 내역 (Payment)
```json
{
  "id": "uuid-string",
  "subscriptionId": "subscription-uuid",
  "amount": 9.99,
  "currency": "USD",
  "paymentDate": "2023-01-01T00:00:00Z",
  "status": "paid",
  "notes": "메모",
  "createdAt": "2023-01-01T00:00:00Z"
}
```

### 사용량 (Usage)
```json
{
  "id": "uuid-string",
  "subscriptionId": "subscription-uuid",
  "date": "2023-01-01T00:00:00Z",
  "amount": 100,
  "unit": "API 호출",
  "notes": "메모",
  "createdAt": "2023-01-01T00:00:00Z"
}
```

## 페이지네이션
목록 조회 API는 페이지네이션을 지원합니다.

### 요청 파라미터
```
GET /api/v1/subscriptions?page=1&limit=10&sort=name&order=asc
```

### 응답 형식
```json
{
  "success": true,
  "data": {
    "items": [ ... ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 10,
      "pages": 10
    }
  }
}
```

## 필터링 및 검색
목록 조회 API는 필터링 및 검색을 지원합니다.

### 요청 파라미터
```
GET /api/v1/subscriptions?search=netflix&category=entertainment&minAmount=5&maxAmount=15
```

## API 버전 관리
API 변경 시 하위 호환성을 유지하기 위해 버전 관리를 적용합니다.
- 메이저 변경: 새 버전 경로 사용 (예: /api/v2/...)
- 마이너 변경: 기존 버전 유지하면서 기능 추가

## 에러 코드
- `AUTH_001`: 인증 실패
- `AUTH_002`: 토큰 만료
- `AUTH_003`: 권한 없음
- `VALIDATION_001`: 유효성 검사 실패
- `RESOURCE_001`: 리소스 찾을 수 없음
- `SERVER_001`: 서버 내부 오류

## API 사용량 제한
- 기본 제한: 분당 60 요청
- 프리미엄 사용자: 분당 300 요청

## API 문서화
- Swagger/OpenAPI 스펙을 사용한 API 문서 자동화
- 각 엔드포인트에 대한 상세 설명, 파라미터, 응답 예시 제공

## 클라이언트 구현 가이드
- HTTP 클라이언트: Dio 패키지 사용
- 인증 토큰 관리: 안전한 저장소에 JWT 토큰 저장
- 오프라인 지원: 요청 큐잉 및 자동 재시도 구현
- 에러 처리: 표준화된 에러 핸들링 적용

## 향후 확장 계획
- GraphQL API 추가 지원
- 웹훅 기능 추가
- 실시간 알림을 위한 WebSocket 지원
- 서드파티 API 연동 (구독 서비스 제공업체)