Skip to content

CLAUDE.md

Latest commit

 

History

History
108 lines (84 loc) · 5.2 KB

CLAUDE.md

File metadata and controls

108 lines (84 loc) · 5.2 KB

CLAUDE.md — app/api/internal/

Spring Boot ↔ FastAPI 내부 통신 전용 라우터. Base URL: /internal 외부 사용자가 접근하지 않으며, X-Internal-Key 인증이 필수다.

현재 엔드포인트

메서드 경로 설명
GET /internal/health AI 서버 내부 헬스체크
DELETE /internal/questions/{question_id} 질문 삭제 시 ai_answers·rag_questions·FAISS 정리
POST /internal/summaries 4레벨 동시 요약 생성 (DP-300) — DynamoDB ai_summaries 저장 + RAG 임베딩. Backend DynamoDB miss 시 fallback 호출
POST /internal/quiz 4레벨 퀴즈 생성 (DP-265) — DynamoDB ai_quizzes 저장. Backend DynamoDB miss 시 fallback 호출
POST /internal/refine 질문 AI 개선 생성 (DP-231) — content_id 있으면 DynamoDB 청크 컨텍스트
POST /internal/answer 질문 AI 1차 답변 생성 (DP-234) — 아티클+RAG 컨텍스트, related_contents 주입, 질문 임베딩 저장
POST /internal/similar-questions 유사 질문 검색 (DP-235) — FAISS questions 인덱스 검색, 자기 자신 제외
POST /internal/similar-contents 유사 콘텐츠 검색 (DP-288) — FAISS devpick 인덱스 검색, content_id 기준 MAX 점수 집계
POST /internal/jobs/parse-jd JD 텍스트 → 필수/우대 기술 추출
POST /internal/jobs/interview-qa 공고·이력서 기반 면접 Q&A JSON 생성
POST /internal/jobs/skill-gap 부족 기술 → 로드맵·학습 리소스 추천
POST /internal/jobs/mock-interview/plan 모의면접 15문항 플랜 보강
POST /internal/jobs/mock-interview/turn 모의면접 턴 평가 + 다음 행동 결정
POST /internal/jobs/mock-interview/finalize 모의면접 종료 → 5영역 점수·모범답안·피드백
POST /internal/resume/parse 이력서 텍스트 → 마스터 이력서 JSON
POST /internal/resume/enrich 1차 파싱 스냅샷 + 원문 → 보강 패치 JSON
POST /internal/report/content-keywords 읽은 글 목록 → TF-IDF 키워드 추출 (DB 저장 없음)
POST /internal/report/question-keywords 기술/커리어 질문 → TF-IDF 키워드 추출 (DB 저장 없음)
POST /internal/trends 트렌드 수동 생성 (DP-385) — 디버그·장애 복구용. 0건→400, 5건미만→422
GET /internal/trends/latest unit+scope 기준 최신 트렌드 스냅샷 조회 (DP-385) — 없으면 404

요약·퀴즈 생성 흐름 (배치 vs fallback)

[배치] run_backfill_batch.py
  → ContentPipeline.process_content()
      → AllLevelsSummaryService + QuizService 자동 실행
      → DynamoDB ai_summaries + ai_quizzes 저장

[fallback] Backend DynamoDB miss 시
  → POST /internal/summaries  — 요약 생성 + DynamoDB 저장 + RAG 임베딩
  → POST /internal/quiz       — 퀴즈 생성 + DynamoDB 저장

POST /internal/summaries 처리 흐름 (DP-300)

1. PreprocessService.preprocess(body.text) → preprocessed
2. AllLevelsSummaryService.summarize_all(content_id, preprocessed, thumbnail_url)
3. SummaryRepository.save_all_levels(content_id, result) → DynamoDB [fire-and-forget]
4. EmbeddingOrchestrator.embed_and_store(content_id, preprocessed, result) → DynamoDB + FAISS [fire-and-forget]
5. AllLevelsSummaryResponse 반환

POST /internal/quiz 처리 흐름 (DP-265)

1. PreprocessService.preprocess(body.text) → preprocessed
2. QuizService.generate_all(content_id, preprocessed) → AllLevelsQuizResponse
3. QuizRepository.save(result) → DynamoDB ai_quizzes [fire-and-forget]
4. EventRepository.save_event(QUIZ_GENERATED) [fire-and-forget, user_id 있을 때만]
5. AllLevelsQuizResponse 반환

POST /internal/answer 처리 흐름 (DP-234)

1. content_id 있으면 → VectorRepository.find_by_content_id() → article_chunks
2. RAG 유사 검색 (항상) → RAGRetriever.search(top_k=5), content_id 동일 청크 필터 → rag_chunks
3. AnswerService.answer() → (AnswerResponse, references)
4. SummaryRepository.find_by_content_ids(references) → result.related_contents 주입
5. AnswerRepository.save(result, question_id, content_id) [fire-and-forget]
6. QuestionEmbeddingOrchestrator.embed_and_store(...) [fire-and-forget, question_id 있을 때만]
7. EventRepository.save_event(ANSWER_GENERATED) [fire-and-forget]

POST /internal/trends 처리 흐름 (DP-385)

1. period_start 없으면 compute_period(unit) 자동 계산
   period_start 있으면 compute_period_end(unit, period_start) 로 period_end 계산
2. ContentRepository.count_by_published_range(start_dt, end_dt)
   → 0건: 400 / < 5건: 422
3. TrendOrchestrator.run(unit, period_start, period_end, force=force_refresh)
   → TrendResponse 반환

자동 트리거는 run_trend_scheduler.py(DP-386)가 담당. 이 엔드포인트는 수동 재생성·디버그용.

작성 원칙

  • 모든 핸들러에 dependencies=[Depends(verify_internal_key)] 필수.
  • 핸들러는 얇게 유지. 실제 처리는 app/services/에 위임.
  • 응답은 JSON만 반환. HTTP 상태코드로 에러 표현.
  • fire-and-forget 단계는 try/except로 감싸고 실패해도 메인 응답에 영향 없음.