From b959e90dd29fff8ec93b2203a35f827772c6c536 Mon Sep 17 00:00:00 2001 From: happybell80 Date: Tue, 2 Dec 2025 02:12:30 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20IR=20Deck=20=ED=8F=89=EA=B0=80=20API=20?= =?UTF-8?q?=EC=9D=91=EB=8B=B5=20=EA=B5=AC=EC=A1=B0=20=EB=B0=8F=20=ED=94=84?= =?UTF-8?q?=EB=A1=A0=ED=8A=B8=EC=97=94=EB=93=9C=20=EC=B2=98=EB=A6=AC=20?= =?UTF-8?q?=EB=A1=9C=EC=A7=81=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 백엔드 아키텍처: 평가 시작 방식 설명 수정 (비동기 → 동기식 평가 후 결과 저장) - 프론트엔드 설정: API 응답 구조 업데이트 (story_scores, summary, investment_opinion 추가) - 페이지 평가 미표시: 런타임 에러 원인 추가 (page_evaluations undefined/null 처리) --- ..._ir_deck_valuation_backend_architecture.md | 10 ++++----- .../251128_ir_valuation_frontend_setup.md | 21 +++++++++++-------- ...aluation_page_evaluations_not_displayed.md | 13 ++++++------ 3 files changed, 23 insertions(+), 21 deletions(-) diff --git a/journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md b/journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md index 92f0562..ed5b47f 100644 --- a/journey/troubleshooting/251128_ir_deck_valuation_backend_architecture.md +++ b/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}`에서 조회 (프론트는 폴링) - - 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 +- **평가 시작 + 결과 조회 분리**: 프론트엔드는 `/evaluate` 응답에서 `evaluation_id`만 사용하고, 실제 점수/등급/페이지별 평가는 `/evaluation/{id}` 폴링으로 사용 + - frontend-ir-valuation/src/services/irDeckService.ts:61-96 + - frontend-ir-valuation/src/hooks/useEvaluation.ts:20-33, 103-129 - **중복 방지**: `force_reevaluate=False` 시 기존 평가 반환 - **의존 서비스**: skill-rag-file (포트 8508), 내장 LLM - **DB 테이블**: `ir_deck_evaluations`, `ir_deck_page_evaluations`, `ir_deck_feedback` diff --git a/journey/troubleshooting/251128_ir_valuation_frontend_setup.md b/journey/troubleshooting/251128_ir_valuation_frontend_setup.md index 2fa6957..67edd90 100644 --- a/journey/troubleshooting/251128_ir_valuation_frontend_setup.md +++ b/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) -- **프로덕션 환경 개선**: `ir-valuation.tsx:518-527` - 테스트 파일 업로드 버튼 개발 환경에서만 표시 -- **입력창 하단 고정**: `ir-valuation.tsx:489, 708` - `sticky bottom-0 z-10` 적용, 메시지 영역에 `pb-32` 추가 +- **에러 로깅 교체**: `src/pages/ir-valuation.tsx` - `console.error` → `logger.error()` +- **프로덕션 환경 개선**: `ir-valuation.tsx:640-668` - 테스트 파일 업로드 버튼을 `process.env.NODE_ENV === "development"` 조건으로 개발 환경에서만 표시 +- **입력창 하단 고정**: `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`: 잘된 점 배열 - - `weaknesses`: 아쉬운 점 배열 + - `strengths`: 장점 배열 + - `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. 투자 종합 점수 및 등급**: diff --git a/journey/troubleshooting/251201_ir_valuation_page_evaluations_not_displayed.md b/journey/troubleshooting/251201_ir_valuation_page_evaluations_not_displayed.md index 8e1b80b..58e91f6 100644 --- a/journey/troubleshooting/251201_ir_valuation_page_evaluations_not_displayed.md +++ b/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` 배열 포함 여부 -- `ir-valuation.tsx:275-294`의 `formatEvaluationResult()` 함수 로직 -- 빈 배열일 때 폴백 메시지 표시 여부 +- 백엔드 응답에 `page_evaluations` 배열 포함 여부 및 타입 (`Array` 여부) +- `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`: 빈 배열일 때 안내 메시지 또는 최소한의 기본 문구 표시 ## 교훈 - 평가 결과 표시 전 백엔드 응답 구조 검증 필수 - 빈 배열/누락 데이터에 대한 폴백 처리 필요 - 사용자에게 명확한 안내 메시지 제공 -