docs: update IR Deck eval async flow and response endpoints

journey/plans/251201_ir_deck_gemini_fallback_api_expansion_plan.md

@@ -115,7 +115,7 @@
 ### 6. API 엔드포인트 응답 구성
 **파일**: `rb8001/app/router/ir_deck.py`
 
-- `evaluate_ir_deck` 엔드포인트에서 `EvaluationResponse` 생성 시 새 필드 포함
+- 평가 결과 조회 엔드포인트 (`GET /api/ir-deck/evaluation/{id}`)에서 `EvaluationResponse` 생성 시 새 필드 포함
 - 기존 평가 결과 조회 시에도 새 필드 포함 (있을 경우만)
 
 ---
@@ -157,7 +157,7 @@
   - Rate Limit 미발생 시에도 기본 모델(`gemini-2.5-flash-lite`) 사용 로그 확인
   
   **2. API 응답 구조 검증**:
-  - `/api/ir-deck/evaluate` 응답에 다음 필드 포함 확인:
+  - `GET /api/ir-deck/evaluation/{id}` 응답에 다음 필드 포함 확인:
     - `story_scores`: 10개 스토리별 점수 배열 (예: `[{"story": "문제 정의 (Problem)", "score": 85, "max_score": 100}, ...]`)
     - `summary`: 종합 결론 요약 텍스트 (문자열, 최소 100자 이상)
     - `investment_opinion`: 객체 형태 (`{"recommendation": str, "risks": List[str], "strengths": List[str]}`)
@@ -194,9 +194,9 @@
 - 새 필드가 Optional: 필드 누락 시에도 API 응답 정상 반환(하위 호환성)
 - 기존 필드와의 호환성: `total_score`, `grade`, `page_evaluations` 정상 반환 확인
 
-**통합 테스트** (검증 기준):
-- 전체 평가 워크플로우: `analyze()` 메서드 반환 Dict에 새 필드 3개 모두 포함 확인
-- API 엔드포인트 응답: `/api/ir-deck/evaluate` 응답 JSON에 새 필드 포함 확인
+  **통합 테스트** (검증 기준):
+  - 전체 평가 워크플로우: `analyze()` 메서드 반환 Dict에 새 필드 3개 모두 포함 확인
+  - API 엔드포인트 응답: `GET /api/ir-deck/evaluation/{id}` 응답 JSON에 새 필드 포함 확인
 
 ### Phase 2: 구현 (Green)
 - 테스트 통과할 때까지 구현
@@ -217,8 +217,8 @@
   - `_evaluate_page_comprehensive`: 페이지별 평가 (N회)
 - **비적용 대상**: 다른 서비스의 LLM 호출은 기존 동작 유지
 
-### API 응답 확장
-- **적용 대상**: `/api/ir-deck/evaluate` 엔드포인트
+  ### API 응답 확장
+  - **적용 대상**: 평가 결과 조회 엔드포인트 (`GET /api/ir-deck/evaluation/{id}`)
 - **하위 호환성**: 새 필드는 Optional이므로 기존 프론트엔드에도 영향 없음
 
 ---
@@ -297,4 +297,3 @@
 - TDD 사례: `DOCS/journey/troubleshooting/251201_ir_deck_template_sentence_fix.md`
 - FastAPI 원칙: `DOCS/book/300_architecture/311_FastAPI_구조_원칙.md`
 - LLM 호출 최적화: `DOCS/book/300_architecture/311_FastAPI_구조_원칙.md` (섹션 13)
-

journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md

@@ -158,14 +158,18 @@ CREATE TABLE ir_deck_feedback (
 ## 전체 플로우
 
 1. **업로드**: `POST /rb8001/api/ir-deck/upload` → `document_id` 반환
-2. **평가**: `POST /rb8001/api/ir-deck/evaluate` → 동기식으로 완료까지 대기 → `evaluation_id`, `total_score`, `grade`, `page_evaluations` 반환
-3. **조회**: `GET /rb8001/api/ir-deck/evaluation/{id}` → DB 조회 (폴링용)
+2. **평가 시작**: `POST /rb8001/api/ir-deck/evaluate` → 비동기 평가 시작, 즉시 `evaluation_id` + `status` 반환
+3. **평가 결과 조회**: `GET /rb8001/api/ir-deck/evaluation/{id}` → DB 조회 (프론트는 폴링로 결과 확인)
 
 **참고**: `/rb8001`는 Nginx 프록시 경로 (51123 → 51124:8001)
 
 ## 중요한 점
 
-- **동기식 평가**: `/evaluate` API는 평가 완료까지 대기 (페이지별 순차 실행, 타임아웃 주의)
+- **비동기 평가 시작 + 결과 조회 분리**: `/evaluate`는 평가를 비동기 작업으로 등록하고 `evaluation_id`만 즉시 반환, 실제 점수/등급은 `/evaluation/{id}`에서 조회 (프론트는 폴링)  
+  - rb8001/app/router/ir_deck.py:169-256  
+  - rb8001/app/services/ir_deck_analyzer.py:42-109  
+  - rb8001/app/state/ir_valuation_repository.py:104-169  
+  - frontend-ir-valuation/src/services/irDeckService.ts:12-81
 - **중복 방지**: `force_reevaluate=False` 시 기존 평가 반환
 - **의존 서비스**: skill-rag-file (포트 8508), 내장 LLM
 - **DB 테이블**: `ir_deck_evaluations`, `ir_deck_page_evaluations`, `ir_deck_feedback`
@@ -183,4 +187,3 @@ CREATE TABLE ir_deck_feedback (
 
 - [IR Deck 배치 테스트 문제점 분석](./251128_ir_deck_batch_test_issues.md) - 배치 테스트 결과 및 해결 사항
 - `DOCS/book/300_architecture/312_문서_작성_원칙.md` - 문서 작성 규칙
-