[TeamBlog] 문서 분석 및 알림 흐름 이력 (AI BE) - 100-hours-a-week/9-team-Devths-WIKI GitHub Wiki
문서 분석 및 알림 흐름 이력 (AI + BE)
9-team-Devths 프로젝트에서 이력서·채용공고 문서 분석 및 비동기 분석 완료 알림과 관련하여 AI·BE 2개 저장소에서 진행한 작업을 시간 흐름순으로 정리한 문서입니다.
핵심 이슈: 비동기 분석 완료 알림 시스템, AI 분석 실패 시 fallback 처리, OCR Fallback 전략, DocumentAnalysisRequest DTO·검증
- AI 저장소: 9-team-Devths-AI
- BE 저장소: 9-team-Devths-BE
Part 1.
분석 API 연동 기반 (BE ↔ AI)
1. 이력서/채용 공고 분석 FastAPI 연동 (BE)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-BE |
| 커밋 | 4c35c03 |
| 메시지 | feat: 이력서/채용 공고 분석 FastAPI와 연동 (#55) |
처리 내용
- 이력서·채용 공고 분석을 FastAPI(AI 서버) 와 연동.
- 분석 요청·비동기 task 생성·폴링·결과 수신 플로우 구현.
- 이후 404/500/비동기 오류 대응 및 분석 완료 알림의 토대가 됨.
목적
- BE ↔ AI 서버 간 문서 분석 API 연동 및 오류·재시도·알림 연동 가능한 구조 확보.
2. 이력서 분석 비동기 처리 self-invocation Lazy 처리 (BE)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-BE |
| 커밋 | 65460a8 |
| 메시지 | feat: 이력서 분석 비동기 처리 self-invocation Lazy 처리 (#55) |
처리 내용
- 이력서 분석 비동기 처리 시 같은 빈 내부 호출(self-invocation)로 트랜잭션·프록시 이슈가 나지 않도록 Lazy 방식으로 호출하도록 수정.
목적
- 비동기 작업이 DB 커밋 전에 조회되며 발생하던 “비동기 작업을 찾을 수 없습니다” 유형 오류 제거 → 분석 완료 알림·폴링 안정화.
3. "비동기 작업을 찾을 수 없습니다" 문제 해결 (BE)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-BE |
| 커밋 | 0ca1689 |
| 메시지 | fix: '비동기 작업을 찾을 수 없습니다' 문제 해결을 위해 DB 커밋 전에 task를 조회하던 로직 수정 |
처리 내용
- 비동기 분석 task를 DB 커밋 전에 조회해 "비동기 작업을 찾을 수 없습니다"가 나던 문제 수정.
- 트랜잭션 커밋 순서·task 조회 시점을 조정해 폴링 시 task가 항상 조회되도록 함.
목적
- 분석 결과 폴링·분석 완료 알림 연동 시 404/무한 폴링 원인 제거.
3-1. 비동기 작업 무한 폴링 문제 해결 (BE)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-BE |
| 커밋 | ba2a0ff (Merge PR #72) |
| 메시지 | bug: 이력서 분석 요청 시 '비동기 작업을 찾을 수 없습니다' 문제 발생 |
처리 내용
- 11개 파일 변경 (+145, −28줄).
AiOcrResult도메인 엔티티·Repository·Service 신규 추가. AsyncAnalysisProcessor대폭 수정 — 비동기 작업 생명주기 재구성.- 분석 요청 후 결과 폴링 시 "비동기 작업을 찾을 수 없습니다" 에러가 무한 반복되던 문제를 작업 생명주기 재설계로 근본 해결.
목적
- 비동기 분석 작업의 상태 추적을 안정화하여 FE에서 결과를 정상 수신할 수 있도록 함.
3-2. 분석 엔드포인트 URI 매핑 실패 해결 (BE)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-BE |
| 커밋 | dc10953 |
| 메시지 | fix: 이력서 분석 엔드포인트 URI 매핑 실패 해결 (#70) |
처리 내용
DocumentAnalysisController.javaURI 매핑 오류 수정 (+2, −2줄).
목적
- 분석 API 엔드포인트가 정상 매핑되어 FE·AI 간 연동 동작 보장.
3-3. taskId 로깅 추가 (BE)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-BE |
| 커밋 | 0fb3055 |
| 메시지 | fix: taskId 로깅 추가 |
처리 내용
FastApiClient.java에 AI 서버 호출 시taskId로그 기록 추가 (+5, −1줄).
목적
- 비동기 분석 요청·폴링 디버깅 시 taskId 기반 추적 지원.
3-4. 404 에러 시 재시도 처리 (BE)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-BE |
| 커밋 | c9f4520 |
| 메시지 | fix: 404 에러 시 재시도 처리 (#70) |
처리 내용
AsyncAnalysisProcessor.java에 재시도 로직 추가 (+16줄).- AI 서버가 작업을 아직 등록하지 않은 상태에서 BE가 폴링하면 404 반환 → 일정 횟수까지 재시도.
목적
- AI 서버 비동기 작업 등록과 BE 폴링 사이 타이밍 차이로 인한 404 에러 안정 처리.
Part 2.
AI 오프닝 메시지·분석 단계별 분할·fallback (AI)
4. 분석 후 AI 오프닝 메시지 생성 기능 추가 (AI)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-AI |
| 커밋 | f27a05d, ef757bd |
| 메시지 | feat: 분석 후 AI 오프닝 메시지 생성 기능 추가 |
처리 내용
- 이력서·채용공고 분석이 완료된 뒤 대화 시작 시 사용자에게 보여줄 오프닝 메시지를 AI가 생성하도록 기능 추가.
- 분석 결과 컨텍스트를 바탕으로 “OO회사 OO 직무에 지원하시는군요…” 등 맞춤 인사·요약 문장 생성.
- 텍스트 추출·분석 파이프라인 내에서 오프닝 메시지 생성 실패 시 로깅·fallback 처리로 빈 맥락 방지.
목적
- 문서 분석 완료 후 채팅 진입 시 사용자 경험 개선 및 분석 결과를 자연어로 안내.
5. Gemini 빈 응답 해결 및 분석 API 단계별 분할 호출 (AI)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-AI |
| 커밋 | 4af8155 |
| 메시지 | fix: Gemini 빈 응답 문제 해결 - 분석 API 단계별 분할 호출 |
처리 내용
- 분석 API를 단계별 분할 호출로 변경: 이력서 분석 → 채용공고 분석 → 매칭도 분석 순으로 각각 별도 LLM 호출.
- 한 번에 긴 분석을 요청하던 방식에서 3단계(이력서/채용공고/매칭) 로 나누어 타임아웃·빈 응답 위험 감소.
- Gemini 빈 응답 시 None 체크·재시도 로직 보강(1ff6498 등과 연계).
목적
- 분석 구간에서 LLM 불안정으로 인한 스트리밍 중단·500 오류 감소 및 오프닝 메시지 품질 확보.
6. 분석 API 안정 모델·재시도 로직 (AI)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-AI |
| 커밋 | 03f1eaf, 1ff6498 |
| 메시지 | fix: 분석 API에 안정 모델(gemini-2.0-flash) 사용 및 재시도 로직 추가 / fix: Gemini 빈 응답 시 None 체크 추가 |
처리 내용
- 분석 구간에 안정 모델(gemini-2.0-flash) 적용 및 재시도 로직 추가.
- Gemini 응답이 None/빈 문자열일 때 None 체크 후 재시도 또는 fallback 반환.
목적
- 분석 실패 시 사용자에게 빈 화면이 나오지 않도록 방어.
7. 분석 결과 JSON 파싱 및 fallback·빈 맥락 방지 (AI)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-AI |
| 커밋 | 5b64cea (JSON 파싱 실패 수정), 93e0033 (Gemini JSON 모드 적용), 414ed2d (분석 실패 시 fallback·빈 맥락 방지) |
처리 내용
- Gemini 응답에서 코드 블록(
```json ```) 등이 섞여 JSON 파싱 실패 →_parse_json_response()로직 보강. - Gemini JSON 모드 적용 (
response_mime_type: "application/json")으로 순수 JSON 응답 보장. - 분석 실패 시 fallback 구조에
matching필드 추가 (KeyError 방지). formatted_text에 사용자 안내 메시지 추가: "상세 분석이 일시적으로 반영되지 않았습니다."- 에러 로깅에
exc_info=True추가로 스택 트레이스 기록.
목적
- AI 분석 실패 시에도 BE·FE에 일관된 구조 전달 및 오프닝 메시지 빈 값 방지.
7-1. CLOVA OCR 우선, Gemini 폴백 전략 구현 (AI)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-AI |
| 커밋 | 53129d9 |
| 메시지 | feat(ocr): CLOVA OCR 우선, Gemini 폴백, EasyOCR 주석 처리 |
처리 내용
ocr_service.py에 3단 Fallback 전략 구현:- CLOVA OCR 시도 (메인)
- 품질 검증 — 텍스트 길이, 한글 비율 등으로 추출 품질 판단
- 품질 부족 시 Gemini Fallback —
llm_service.extract_text_from_file()호출
- EasyOCR은 주석 처리 (v2에서 별도 GPU 서버로 분리 예정).
- 결과에
ocr_engine(사용된 엔진명),fallback_reason(전환 사유) 필드 추가.
목적
- CLOVA OCR이 실패하거나 품질이 낮을 때 Gemini VLM으로 자동 전환하여 문서 텍스트 추출 신뢰성 확보.
7-2. 분석 리포트 및 면접 질문 프롬프트 개선 (AI)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-AI |
| 커밋 | 736a7f5 |
| 메시지 | feat: 분석 리포트 및 면접 질문 프롬프트 개선 |
처리 내용
- 분석 리포트 최대 길이를 1,500자로 제한.
- 강점·약점 항목 수를 5개 → 3개로 축소.
- 프롬프트 최적화로 Gemini 응답 품질·안정성 향상.
목적
- 분석 리포트가 지나치게 길어져 오프닝 메시지 생성·SSE 전송에 부담을 주는 문제 해결. 핵심 정보만 전달하도록 간결화.
Part 3.
DocumentAnalysisRequest DTO·검증 (BE)
8. DocumentAnalysisRequest DTO 수정·Validation 강화 (BE)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-BE |
| 커밋 | ba44e81 (DocumentAnalysisRequest cascade Valid), 36788ea (Size 어노테이션 범위 변경), 54c1e4e (이력서/채용공고/닉네임 길이 제한) |
처리 내용
- DocumentAnalysisRequest 및 중첩 DocumentInfo에
@Validcascade 적용으로 하위 객체 검증 누락 방지. @Size어노테이션 범위 수정으로 이력서·채용공고·닉네임 등 입력 길이 제한 정확히 적용.- 잘못된 요청이 AI Server까지 도달하기 전에 BE에서 422로 차단.
목적
- 분석 요청 스키마·길이 제한 통일로 422/500 예방 및 AI 부하 완화.
9. jobPost DTO 필드명 매칭 문제 해결 (BE)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-BE |
| 커밋 | a8d769f |
| 메시지 | fix: jobPost DTO 필드명 매칭 문제 해결 (#68) |
처리 내용
- 채용 공고 분석 시 jobPost DTO 필드명이 AI 서버 또는 내부 스키마와 불일치해 발생하던 오류(422/500 유사) 수정.
목적
- 분석 요청 시 DTO 매핑 오류로 인한 실패 제거.
Part 4.
분석 완료 알림·채팅방 제목 업데이트 (BE)
10. 분석 완료 알림 읽음 처리 (BE)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-BE |
| 커밋 | 6b873a3 |
| 메시지 | 분석 완료 알림 읽음 처리 (#150) |
처리 내용
- 비동기 분석 완료 시 사용자에게 알림을 보내고, 사용자가 채팅방에 입장하거나 알림을 확인하면 읽음 처리되도록 구현.
- 채팅방에 바로 입장한 경우에도 분석 완료 알림이 읽음 처리되도록 로직 보완.
목적
- 비동기 분석 완료 알림 시스템의 일관된 상태 관리 및 중복 알림·미읽음 잔존 방지.
11. 채팅방 제목 업데이트 (summary → title) (BE)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-BE |
| 커밋 | 766074e |
| 메시지 | summary → title 업데이트 (#120) |
처리 내용
- AI Server 분석 결과의 summary 필드(회사명·직무 등)로 채팅방 제목 자동 업데이트.
- 분석 완료 후 채팅방 목록에서 분석 대상(회사/직무)을 즉시 식별할 수 있도록 함.
목적
- 분석 완료 알림·채팅 진입 시 UX 일관성 및 채팅방 목록 가독성 향상.
12. ExternalTaskId 제거 및 백엔드 taskId 통합 (BE)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-BE |
| 커밋 | 342aced |
| 메시지 | feat: ExternalTaskId 제거 후 백엔드 taskId로 통합 (#70) |
처리 내용
- ExternalTaskId 제거 후 백엔드 taskId 하나로 통일.
- 클라이언트·AI 서버와의 task 식별자 계약 단순화로 분석 요청·폴링·알림 연동 시 매핑 오류 감소.
목적
- 분석 완료 알림·폴링 시 task 조회 실패·404 원인 제거.
13. OCR 데이터 저장 로직 추가 (BE)
| 항목 | 내용 |
|---|---|
| 저장소 | 9-team-Devths-BE |
| 커밋 | fc5c743 |
| 메시지 | feat: OCR 데이터 저장 로직 추가 (#70) |
처리 내용
- 분석 결과 중 OCR 결과를 DB에 저장하는 로직 추가.
- 분석 플로우 완결 및 결과 조회·재활용·알림 연동 시 데이터 일관성 확보.
목적
- 분석 500/데이터 부재로 인한 후속 오류 감소 및 분석 이력·알림 정합성 유지.
요약: 문서 분석·알림 유형별 대응
| 유형 | 담당 | 대응 커밋/내용 | 조치 요약 |
|---|---|---|---|
| 분석 API 연동 | BE | 4c35c03, 65460a8, 0ca1689 | FastAPI 연동, 비동기 Lazy, task 조회 시점 수정 |
| 비동기 폴링 안정화 | BE | ba2a0ff, dc10953, 0fb3055, c9f4520 | 무한 폴링 해결, URI 매핑 수정, taskId 로깅, 404 재시도 |
| 오프닝 메시지 | AI | f27a05d, ef757bd | 분석 완료 후 AI 오프닝 메시지 생성 |
| 분석 단계별 분할·fallback | AI | 4af8155, 03f1eaf, 1ff6498, 5b64cea, 93e0033, 414ed2d | 단계별 분할, 재시도·None 체크·JSON 모드·fallback·빈 맥락 방지 |
| OCR Fallback 전략 | AI | 53129d9 | CLOVA OCR 우선, Gemini 폴백, 품질 검증 |
| 프롬프트 최적화 | AI | 736a7f5 | 리포트 1,500자 제한, 항목 3개로 축소 |
| DocumentAnalysisRequest DTO | BE | ba44e81, 36788ea, 54c1e4e, a8d769f | cascade Valid, Size 범위, 필드명 매칭 |
| 분석 완료 알림 | BE | 6b873a3, 766074e | 알림 읽음 처리, summary→채팅방 제목 업데이트 |
| taskId 통합·OCR 저장 | BE | 342aced, fc5c743 | taskId 단일화, OCR 결과 저장 |
회고 포인트
비동기 분석 완료 알림 시스템
- BE가 분석 요청 후 비동기 task를 생성하고, AI 서버 분석 완료 시 결과 저장·알림 생성까지 한 흐름으로 처리.
- 분석 완료 알림 읽음 처리(6b873a3)로 “채팅방 입장 시·알림 확인 시” 읽음 상태가 일관되게 반영됨.
- task 조회 시점(0ca1689), taskId 통합(342aced)으로 폴링·알림 연동 시 404/미조회 이슈를 줄임.
AI 분석 실패 시 fallback 처리
- AI 측에서 단계별 분할 호출(4af8155), 재시도·안정 모델(03f1eaf, 1ff6498), JSON 파싱 fallback·빈 맥락 방지(5b64cea, 93e0033, 414ed2d)를 적용해, 분석 일부 실패 시에도 fallback 구조를 반환하고 오프닝 메시지가 비어 보이지 않도록 함.
- OCR 3단 Fallback(CLOVA → Gemini → 기본 메시지, 53129d9)으로 문서 추출 실패 최소화.
- 분석 리포트 길이 제한·항목 축소(736a7f5)로 Gemini 응답 안정성·SSE 전송 효율 개선.
- BE는 DocumentAnalysisRequest 검증 강화(ba44e81, 54c1e4e)로 잘못된 요청을 422로 차단해 AI 부하·실패 경로를 줄임.
문서 이력
| 날짜 | 내용 |
|---|---|
| (초안) | AI·BE 저장소 문서 분석·알림 관련 커밋 반영, SSE·면접 통합 이력 문서 형식에 맞춰 작성 |
| 2026-02-09 | BE 비동기 폴링 안정화 커밋 4건(ba2a0ff, dc10953, 0fb3055, c9f4520), AI OCR Fallback(53129d9), 프롬프트 개선(736a7f5), JSON 파싱 수정(5b64cea) 추가 보강 |