[✨Feat] 키워드 분석 시작 API 구현

[yong203]

목표

사용자가 첨삭 완료된 자기소개서에서 키워드 분석을 시작하거나 기존 키워드 분석을 재분석할 수 있도록 API-020 POST /cover-letters/{coverLetterId}/keyword-analysis를 구현한다.

이번 이슈는 키워드 분석 도메인의 첫 구현 단계로, 실제 LLM 키워드 추출 worker까지 만들지 않고 KeywordAnalysis persistence와 KEYWORD_ANALYSIS LLM Job 생성 계약을 먼저 고정한다.

작업 범위

• 관련 요구사항/API:

  • REQ-009
  • API-020

• 포함할 것:

  • keywordanalysis 기능 패키지 추가
  • KeywordAnalysis entity/repository/service/controller/dto 추가
  • KeywordAnalysisStatus: PROCESSING, COMPLETED, FAILED
  • POST /cover-letters/{coverLetterId}/keyword-analysis 구현
  • 현재 사용자 소유 active 자기소개서만 요청 가능
  • CoverLetter.status=REVIEWED이고 latestReviewVersionId가 있어야 분석 가능
  • sourceReviewVersionId가 있으면 해당 자기소개서의 첨삭 버전인지 검증
  • sourceReviewVersionId가 없으면 CoverLetter.latestReviewVersionId 사용
  • 기존 KeywordAnalysis가 없으면 새로 생성
  • 기존 KeywordAnalysis가 있으면 같은 리소스를 PROCESSING으로 재사용
  • 같은 자기소개서에 PENDING 또는 PROCESSING LLM Job이 있으면 LLM_JOB_ALREADY_RUNNING
  • LlmJob에 KEYWORD_ANALYSIS 생성 helper 추가
  • 생성된 Job은 targetType=COVER_LETTER, targetId=coverLetterId로 둬 기존 Job owner 검증 흐름을 재사용
  • 응답은 문서 계약대로 jobId, keywordAnalysisId, coverLetterId, status
  • docs/api/README.md, docs/status.md, 필요 시 docs/api/keyword-analysis.md 갱신

• 제외할 것:

  • API-021 GET /cover-letters/{coverLetterId}/keyword-analysis/latest
  • 실제 OpenAI 키워드 분석 client
  • 키워드 분석 worker
  • keyword_analysis_keywords 저장/조회
  • SSE 스트림
  • 자동 재시도 정책 구현
  • AI 면접 기능

완료 기준

• 키워드 분석 시작 요청이 새 KeywordAnalysis(PROCESSING)와 LlmJob(KEYWORD_ANALYSIS, PENDING)을 생성한다.
• 기존 KeywordAnalysis가 있으면 새 리소스를 만들지 않고 같은 id를 재사용해 PROCESSING으로 전환한다.
• sourceReviewVersionId 생략 시 최신 첨삭 버전을 사용한다.
• 다른 사용자 소유, 삭제된 자기소개서, REVIEWED가 아닌 자기소개서, 잘못된 sourceReviewVersionId는 계약된 에러로 처리한다.
• 진행 중인 LLM Job이 있으면 LLM_JOB_ALREADY_RUNNING을 반환한다.
• controller/service/repository 테스트가 추가된다.
• git diff --check, ./gradlew test, ./gradlew check가 통과한다.

참고

• docs/api/keyword-analysis.md
• docs/requirements.md REQ-009
• docs/decisions/keyword-analysis.md
• docs/erd.md의 keyword_analyses, keyword_analysis_keywords