docs: IR Deck 평가 API 응답 구조 및 프론트엔드 처리 로직 업데이트

- 백엔드 아키텍처: 평가 시작 방식 설명 수정 (비동기 → 동기식 평가 후 결과 저장)
- 프론트엔드 설정: API 응답 구조 업데이트 (story_scores, summary, investment_opinion 추가)
- 페이지 평가 미표시: 런타임 에러 원인 추가 (page_evaluations undefined/null 처리)

journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md

@@ -158,18 +158,16 @@ CREATE TABLE ir_deck_feedback (
 ## 전체 플로우
 
 1. **업로드**: `POST /rb8001/api/ir-deck/upload` → `document_id` 반환
-2. **평가 시작**: `POST /rb8001/api/ir-deck/evaluate` → 비동기 평가 시작, 즉시 `evaluation_id` + `status` 반환
+2. **평가 시작**: `POST /rb8001/api/ir-deck/evaluate` → 평가 실행 및 결과 저장, `evaluation_id` 포함 응답
 3. **평가 결과 조회**: `GET /rb8001/api/ir-deck/evaluation/{id}` → DB 조회 (프론트는 폴링로 결과 확인)
 
 **참고**: `/rb8001`는 Nginx 프록시 경로 (51123 → 51124:8001)
 
 ## 중요한 점
 
-- **비동기 평가 시작 + 결과 조회 분리**: `/evaluate`는 평가를 비동기 작업으로 등록하고 `evaluation_id`만 즉시 반환, 실제 점수/등급은 `/evaluation/{id}`에서 조회 (프론트는 폴링)  
+- **평가 시작 + 결과 조회 분리**: 프론트엔드는 `/evaluate` 응답에서 `evaluation_id`만 사용하고, 실제 점수/등급/페이지별 평가는 `/evaluation/{id}` 폴링으로 사용  
-  - rb8001/app/router/ir_deck.py:169-256  
+  - frontend-ir-valuation/src/services/irDeckService.ts:61-96  
-  - rb8001/app/services/ir_deck_analyzer.py:42-109  
+  - frontend-ir-valuation/src/hooks/useEvaluation.ts:20-33, 103-129
-  - 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`

journey/troubleshooting/251128_ir_valuation_frontend_setup.md

@@ -116,9 +116,9 @@ curl -X POST http://localhost/rb8001/api/ir-deck/evaluate \
 ### 변경 사항
 - **파비콘 추가**: `public/favicon.svg` 생성, `index.html:6-7` 링크 추가
 - **로깅 유틸리티**: `src/utils/logger.ts` 생성 (환경별 일관된 로깅)
-- **에러 로깅 교체**: `src/pages/ir-valuation.tsx` - `console.error` → `logger.error()` (4곳: 100, 116, 162, 225)
+- **에러 로깅 교체**: `src/pages/ir-valuation.tsx` - `console.error` → `logger.error()`
-- **프로덕션 환경 개선**: `ir-valuation.tsx:518-527` - 테스트 파일 업로드 버튼 개발 환경에서만 표시
+- **프로덕션 환경 개선**: `ir-valuation.tsx:640-668` - 테스트 파일 업로드 버튼을 `process.env.NODE_ENV === "development"` 조건으로 개발 환경에서만 표시
-- **입력창 하단 고정**: `ir-valuation.tsx:489, 708` - `sticky bottom-0 z-10` 적용, 메시지 영역에 `pb-32` 추가
+- **입력창 하단 고정**: `ir-valuation.tsx:915-950` - 입력 영역을 `sticky bottom-0 z-10`로 고정, 메시지 영역 여백 확보
 
 ### 교훈
 - 프로덕션 환경에서도 에러 로그 기록 필요: `logger.error()`는 모든 환경에서 동작
@@ -134,14 +134,17 @@ curl -X POST http://localhost/rb8001/api/ir-deck/evaluate \
   - `grade`: 등급 (S/A/B/C)
   - `page_evaluations`: 페이지별 평가 배열
     - `page_number`: 페이지 번호
-    - `strengths`: 잘된 점 배열
+    - `strengths`: 장점 배열
-    - `weaknesses`: 아쉬운 점 배열
+    - `weaknesses`: 개선점 배열
+  - `story_scores`: Sequoia 10가지 스토리별 점수 배열
+  - `summary`: 종합 요약 텍스트
+  - `investment_opinion`: 투자 의견 객체 (권고, 리스크, 강점)
   - `message` 또는 `formatted_message`: 포맷팅된 메시지 (선택적)
 
-- **프론트엔드 표시** (`ir-valuation.tsx:283-312`, `formatEvaluationResult()`):
+- **프론트엔드 표시** (`ir-valuation.tsx:335-428`, `formatEvaluationResult()`):
-  - 종합 점수/등급만 표시
+  - 1. 투자 종합 점수 및 등급 (마크다운 섹션 + 스토리별 점수 테이블)
-  - 페이지별 잘된 점/아쉬운 점 리스트
+  - 2. 장표별 장점과 개선점 요약 (페이지별 장점/개선점 리스트)
-  - 마크다운 렌더링 (헤더, 리스트)
+  - 3. 종합 결론 및 투자 종합 의견 (요약, 권고, 리스크, 강점)
 
 ### 목표 ChatGPT 형식
 1. **1. 투자 종합 점수 및 등급**:

journey/troubleshooting/251201_ir_valuation_page_evaluations_not_displayed.md

@@ -23,11 +23,13 @@
 1. **백엔드 데이터 문제**: `page_evaluations` 배열이 비어 있거나 누락
 2. **프론트엔드 렌더링 문제**: `formatEvaluationResult()` 함수가 빈 배열 처리 미흡
 3. **데이터 구조 불일치**: 백엔드 응답과 프론트엔드 기대 형식 불일치
+4. **프론트엔드 런타임 에러**: `result.page_evaluations`가 `undefined`/null/비배열인 상태에서 `.map()` 호출로 `TypeError` 발생
 
 ### 확인 필요
-- 백엔드 응답에 `page_evaluations` 배열 포함 여부
+- 백엔드 응답에 `page_evaluations` 배열 포함 여부 및 타입 (`Array` 여부)
-- `ir-valuation.tsx:275-294`의 `formatEvaluationResult()` 함수 로직
+- `ir-valuation.tsx:335-381`의 `formatEvaluationResult()` 함수 로직
-- 빈 배열일 때 폴백 메시지 표시 여부
+- `ir-valuation.tsx:220-247`의 `page_evaluations` 매핑 코드에서 방어적 처리 여부  
+  - 참고: `DOCS/journey/troubleshooting/251202_ir_valuation_gateway_timeout_and_frontend_fallback.md`
 
 ## 해결 방안
 
@@ -36,12 +38,11 @@
 - `page_evaluations` 배열이 실제로 포함되어 있는지 검증
 
 ### 2. 프론트엔드 처리 개선
-- `ir-valuation.tsx:275-294`: 빈 배열일 때 안내 메시지 표시
+- `ir-valuation.tsx:220-247`: `Array.isArray(result.page_evaluations)`로 타입 검증 후 map 수행, 누락/잘못된 타입인 경우 경고 로그만 남기고 빈 배열로 처리
-- 데이터 구조 검증 로직 추가
+- `ir-valuation.tsx:335-381`: 빈 배열일 때 안내 메시지 또는 최소한의 기본 문구 표시
 
 ## 교훈
 
 - 평가 결과 표시 전 백엔드 응답 구조 검증 필수
 - 빈 배열/누락 데이터에 대한 폴백 처리 필요
 - 사용자에게 명확한 안내 메시지 제공
-