feat: exams/services/analysis_orchestrator.py 신규 작성

[6ye0m]

작업 내용:

• exams/services/analysis_orchestrator.py 신규 작성 (E-AI-01/02/03 대응)

  • analyze_and_estimate(study_material): task_extractor(AI 분석) 호출 후 각 StudyTask에 time_estimator(BE1) 결과를 반영하고, StudyMaterial.status를 PROCESSING→COMPLETED/FAILED로 갱신 (E-AI-01)
  • get_analysis_status(study_material): 현재 분석 상태와 실패 사유 조회 (E-AI-02)
  • retry_analysis(study_material): FAILED 상태일 때만 재시도 허용, PROCESSING/COMPLETED는 거부 (E-AI-03)
  • 내부적으로 _run_analysis_and_estimate()를 별도 @transaction.atomic으로 분리해서, 분석 실패 시 StudyTask는 롤백되지만 FAILED 상태/실패사유는 정상 저장되도록 처리

  확인이 필요한 부분:

• 재시도 횟수 제한(명세서상 "재시도 초과 시 직접 입력 안내")은 구현 안 함 - StudyMaterial에 재시도 횟수 필드가 없어서 필드 추가가 먼저 필요함. 필요한지 팀 논의 부탁드려요.

• COMPLETED 상태에서 사용자가 명시적으로 재분석을 원하는 경우의 별도 경로는 이 PR에 포함 안 됨 (필요시 View단계에서 사용자 확인 받고 상태를 직접 조작하는 식으로 처리 필요)

참고) View 구현 시 E-AI-01, E-AI-03(기능명세서) 모두 task_extractor.analyze_study_material()가 아니라 이 analyze_and_estimate()를 호출해야 함

[wngjs8114]

AI 분석 → 예상시간 계산 → 상태 갱신을 별도 오케스트레이션 계층으로 분리한 방향은 좋습니다. View에서 task_extractor와 time_estimator를 각각 호출하지 않고 하나의 서비스 진입점으로 처리하는 구조도 적절합니다.

관련 정책은 아래와 같이 확정하겠습니다.

1. 상태 필드 분리

기존 StudyMaterial.status와 error_message는 PDF/텍스트 추출 상태와 추출 오류를 나타내는 필드로 유지합니다.

AI 분석 상태는 별도 필드로 관리합니다.

• analysis_status
• analysis_error_message
• analysis_retry_count

초기값은 아래와 같이 설정하면 됩니다.

• analysis_status=PENDING
• analysis_retry_count=0

2. 분석 상태 전이

분석 상태는 아래 흐름만 허용합니다.

• 최초 분석: PENDING → PROCESSING → COMPLETED 또는 FAILED
• 재시도: FAILED → PROCESSING → COMPLETED 또는 FAILED
• PROCESSING 상태에서는 중복 분석 요청 거부
• COMPLETED 상태에서는 MVP 기준 재분석 미지원

분석 완료 후 결과를 수정해야 하는 경우 AI 재분석이 아니라 작업 검토 화면에서 사용자가 직접 수정하도록 하겠습니다.

View에서 상태를 직접 변경한 뒤 강제로 재분석하는 방식은 사용하지 않습니다.

3. 사용자 재시도 정책

최초 분석 실패 후 사용자가 재시도할 수 있는 횟수는 최대 2회로 확정합니다.

최초 분석은 재시도 횟수에 포함하지 않으며, analysis_retry_count는 사용자가 실제로 재시도한 횟수만 기록합니다.

• 최초 분석 실패: analysis_retry_count=0
• 1차 재시도 시작: analysis_retry_count=1
• 2차 재시도 시작: analysis_retry_count=2
• 2차 재시도까지 실패한 경우 추가 재시도 거부
• 추가 재시도 대신 직접 작업 입력 화면으로 안내

따라서 최초 분석 1회와 사용자 재시도 2회를 합쳐 총 최대 3번까지 분석을 시도할 수 있습니다.

task_extractor 내부에서 AI 응답 형식 검증을 위해 수행하는 자체 재요청은 사용자 재시도 횟수에 포함하지 않습니다.

4. 빈 분석 결과 처리

AI 분석 결과 생성된 StudyTask가 0개라면 분석 성공으로 처리하지 않고 FAILED 상태로 처리합니다.

위 정책을 기준으로 병합 전에 아래 사항을 보완 부탁드립니다.

1. 전체 파이프라인 예외 처리

현재 analyze_and_estimate()가 AIAnalysisError만 처리하고 있습니다.

time_estimator, bulk_update 등 후속 처리에서 예외가 발생해도 analysis_status가 FAILED로 변경되고 실패 사유가 저장되도록 분석과 예상시간 계산 전체의 예외를 처리해 주세요.

• AIAnalysisError: 사용자에게 표시 가능한 기존 분석 실패 사유 저장
• 예상하지 못한 예외: 상세 내용은 로그에 기록하고, 사용자용 analysis_error_message에는 일반적인 오류 메시지 저장

2. 중복 실행 및 재시도 횟수 원자적 처리

현재 상태 확인 없이 바로 PROCESSING으로 변경하면 중복 요청이 동시에 실행될 수 있습니다.

최초 분석은 PENDING 상태에서만 시작되고, 재시도는 FAILED 상태이면서 analysis_retry_count < 2인 경우에만 시작되도록 DB 조건부 update 방식으로 처리해 주세요.

재시도 시작 시에는 analysis_retry_count가 원자적으로 1 증가해야 합니다.

3. 분석 상태 관련 함수 수정

get_analysis_status()와 retry_analysis()도 기존 추출 상태 필드가 아니라 새로 추가한 AI 분석 상태 필드를 사용하도록 변경해 주세요.

4. 자동 테스트 추가

아래 항목에 대한 테스트를 추가 부탁드립니다.

• 최초 분석 성공 시 COMPLETED 상태 저장
• 최초 분석이 analysis_retry_count를 증가시키지 않는지 확인
• AI 분석 실패 시 FAILED 상태 저장 및 생성 작업 롤백
• 예상시간 계산 실패 시 FAILED 상태 저장 및 생성 작업 롤백
• 생성된 작업이 0개인 경우 FAILED 처리
• PROCESSING 상태에서 중복 분석 요청 거부
• COMPLETED 상태에서 재분석 요청 거부
• FAILED 상태에서 1차 재시도 가능
• 1차 재시도 실패 후 2차 재시도 가능
• 2차 재시도 실패 후 추가 재시도 거부
• 재시도 시작 시 analysis_retry_count가 정확히 증가하는지 확인
• task_extractor 내부 재요청이 analysis_retry_count를 증가시키지 않는지 확인
• AI 분석 과정에서 기존 추출 상태 필드가 변경되지 않는지 확인

AI 네트워크 호출이 transaction.atomic 내부에서 수행되는 문제는 기존 task_extractor 구조까지 수정해야 하는 사항이므로, 이번 PR의 병합 차단 사항에서는 제외하고 후속 리팩터링 이슈로 분리하겠습니다.