docs: IR Deck evaluate API question 파라미터 추가 문서화

journey/troubleshooting/251129_ir_deck_evaluate_question_feature.md

@@ -0,0 +1,50 @@
+# IR Deck 평가 API question 파라미터 추가
+
+**날짜**: 2025-11-29  
+**작성자**: Auto  
+**관련 파일**:
+- `rb8001/app/router/ir_deck.py`
+- `rb8001/app/services/ir_deck_analyzer.py`
+
+---
+
+## 문제 상황
+
+프론트엔드에서 평가 시작 시 질문("기업분석해줘" 등)을 함께 전송하지만, 백엔드에서 무시됨. 일부 다른 질문을 넣는 경우 평가 맥락 없이 답변 생성되어 부정확함.
+
+## 해결 방안
+
+### 1. API 스펙 확장
+- `EvaluationRequest`에 `question: Optional[str]` 필드 추가
+- `EvaluationResponse`에 `answer: Optional[str]` 필드 추가
+- `ir_deck.py:36-40, 42-48`: Request/Response 모델 수정
+
+### 2. 비즈니스 로직 구현
+- `ir_deck_analyzer.py:370-436`: `generate_answer_with_evaluation_context()` 메서드 추가
+- 평가 결과 요약 생성 (점수, 등급, 페이지별 평가)
+- RAG 검색으로 문서 컨텍스트 가져오기
+- 평가 결과 + 문서 컨텍스트를 포함한 프롬프트로 LLM 호출
+
+### 3. 계층 분리 원칙 준수
+- `ir_deck.py:184-232, 256-305`: router에서 비즈니스 로직 제거
+- 서비스 계층 호출만 하도록 변경
+- 중복 코드 제거 (기존 평가/새 평가에서 동일 로직 통합)
+
+## 구현 완료
+
+- 커밋: `0cd884f` (refactor: 원칙 준수 - 비즈니스 로직을 services 계층으로 이동)
+- 커밋: `c32ba01` (feat: evaluate API에 question 파라미터 추가)
+- 테스트: question 없이 평가 시 answer 필드 없음 (정상), question 포함 시 533자 답변 생성 확인
+
+## 교훈
+
+### 계층 분리 원칙 위반 후 수정
+- 초기 구현에서 router에 비즈니스 로직 직접 작성 (평가 결과 요약, 프롬프트 구성)
+- 원칙 문서 확인 후 services 계층으로 이동
+- 교훈: 코드 작성 전 원칙 문서 확인 필수, router는 서비스 호출만
+
+### 중복 코드 제거
+- 기존 평가/새 평가에서 동일한 로직 반복
+- 통합 메서드로 중복 제거, 유지보수성 향상
+- 교훈: 중복 코드 발견 시 즉시 리팩토링
+