Aggregator Server PRD
배경 (Background)
현재 FE는 도메인 요청(watchlist, alert, account, order)을 BE(8080)에, 시그널·예측 요청을 ML(8000)에 직접 보낸다. 서비스가 늘어날수록 FE가 알아야 하는 서버 주소가 늘어나고, ML 장애 대응을 FE에서 해야 한다.
Problem (AS-IS)
FE(3000) ──► BE(8080) watchlist, alert, stock
FE(3000) ──► ML(8000) signal, prediction, recommendations, backtest
- FE가 서버 2개의 주소(
NEXT_PUBLIC_API_BASE_URL,NEXT_PUBLIC_SIGNAL_BASE_URL)를 직접 관리 - ML 장애 시 FE에서 fallback 구현 필요 → FE 복잡도 증가
- ML 재시작 시 캐시 유실 → 서비스 중단
- 서버 주소 변경 시 FE 배포 필요
Goal (TO-BE)
FE(3000)
│ (NEXT_PUBLIC_API_BASE_URL = 8090)
▼
Aggregator(8090) ─ /api/v1/signals/** ──► ML(8000) + Redis fallback
─ /api/v1/predictions/** ──► ML(8000) + Redis fallback
─ /api/v1/recommendations ──► ML(8000) + Redis fallback
─ /api/v1/backtest/** ──► ML(8000) (캐시 없음)
└ /api/v1/** (나머지) ──► BE(8080) reverse proxy
- FE는 Aggregator 주소 하나(
NEXT_PUBLIC_API_BASE_URL)만 안다. - ML 장애 시 Aggregator가 Redis 캐시에서 마지막 성공 응답을 반환한다.
- BE·ML 주소 변경은 Aggregator 설정만 수정하면 된다.
Requirements
| ID | 요구사항 | 우선순위 |
|---|---|---|
| R-01 | aggregator/ Kotlin + Spring Boot 신규 서비스 (포트 8090) | P0 |
| R-02 | Redis 컨테이너 추가 (docker-compose) | P0 |
| R-03 | GET /api/v1/signals/{symbol} — ML 호출, Redis 캐시(TTL 600s), fallback | P0 |
| R-04 | GET /api/v1/predictions/{symbol} — 동일 패턴 | P0 |
| R-05 | GET /api/v1/recommendations — ML 호출, Redis 캐시(TTL 300s), fallback | P0 |
| R-06 | GET /api/v1/backtest/{symbol} — ML 호출, 캐시 없음, 실패→503 | P0 |
| R-07 | 나머지 /api/v1/** — BE(8080)로 reverse proxy (watchlist·alert·stock 포함) | P0 |
| R-08 | FE 전체 API → Aggregator(8090) 단일 진입점, NEXT_PUBLIC_SIGNAL_BASE_URL 제거 | P0 |
| R-09 | ML 장애 + 캐시 없음 시 503 반환 | P0 |
| R-10 | 캐시 응답 헤더 X-Cache: HIT 포함 | P1 |
사용자 시나리오
시나리오 1 — ML 장애 시 시그널 조회 정상 서비스 사용자가 종목 상세 화면에서 시그널 데이터를 요청한다. ML(8000)이 일시 중단된 상태에서도 Aggregator가 Redis 캐시에서 마지막 성공 응답을 반환하여 사용자는 캐시된 시그널 데이터를 확인할 수 있다.
시나리오 2 — FE 단일 진입점 전환
개발자가 FE의 NEXT_PUBLIC_API_BASE_URL을 http://localhost:8090으로 변경하면, 기존에 BE와 ML로 분산되어 있던 모든 API 호출이 Aggregator를 통해 각각 적절한 서비스로 라우팅된다. NEXT_PUBLIC_SIGNAL_BASE_URL은 더 이상 필요 없다.
범위 외
- BE(8080) 코드 변경 없음
- ML(8000) 코드 변경 없음
- 인증/인가 레이어 없음 (현재 없으므로 유지)