[FEATURE] 이미지 업로드 -> OCR 추출 -> 결과 확인/수정 -> 최종반영 + 업로드 히스토리 조회 기능 구현

[DaeunSon]

#️⃣ 요청 유형

해당되는 항목을 선택해주세요.

• 새로운 기능 추가
• 기존 기능 개선
• 성능 개선

---

#️⃣ 어떤 기능인가요?

사용자가 일정(포스터/캡처) 이미지를 업로드하면 AI 서버가 OCR을 수행하고, 백엔드는 해당 결과를 임시저장 후 사용자에게 검토/수정 UI를 제공한다. 사용자가 최종 확인하면 DB에 확정 반영한다. 또한 사용자는 OCR 업로드 히스토리를 조회할 수 있다.

생성 테이블

1. OCR_UPLOADS(id, user_id, image_url, title, start_date, end_date, category, memo, status, created_at, updated_at)

2. OCR_DETAIL(id, title, description, college, target, start_date, end_date, payment_date, require_document, college_id, ocr_uploads_id)

권장 상태값: status = DRAFT | EXTRACTED | CONFIRMED | FAILED

#️⃣ 이 기능이 필요한 이유는 무엇인가요?

• 포스터/공지 이미지만으로 일정 입력 자동화 → 입력 비용 절감 & 정확도 향상
• 검토/수정 단계를 통해 OCR 오류 보정 → 품질 보장
• 업로드 히스토리로 사용자는 이전 추출본을 재활용/수정 가능 → UX 향상
• 추후 크롤링 일정과의 중복 탐지/매칭을 위한 데이터 기반 마련

---

구현 방안 (선택)

1. 이미지 업로드

• 프론트에서 이미지 업로드 후 파일 URL을 백엔드에 전달
• OCR_UPLOADS(status=DRAFT) 레코드 생성

2. OCR 요청/콜백

• 백엔드가 AI서버에 OCR 요청(비동기)
  • 옵션 A: 콜백 방식 → AI 서버가 /api/ocr-uploads/{id}/callback 으로 결과 푸시
  • 옵션 B: 폴링 방식 → 백엔드가 AI 서버 결과를 주기적으로 조회
• 성공 시 OCR_UPLOADS(status=EXTRACTED) + OCR_DETAIL 생성/업데이트

3. 검토/수정 & 최종 반영

• 클라이언트가 /api/ocr-uploads/{id}로 결과 조회 -> 사용자 수정사항을 PATCH로 반영
• 확정 버튼 시 status=CONFIRMED, 필요한 경우 일정(Event)엔티티 연계

4. 업로드 히스토리

• 사용자별 페이지네이션 리스트, 상세 보기 제공

---

#️⃣ 작업 상세 내용

백엔드 도메인/상태

• OCR_UPLOADS.status : DRAFT(업로드 직후) -> EXTRACTED(AI 결과 저장) -> CONFIRMED(사용자 확정) -> FAILED(OCR 실패)
• OCR_DETAIL, OCR_UPLOADS_ID는 1:1

주요 플로우

1. POST /api/ocr-uploads

• 요청 바디 : imageUrl
• 응답 : id, status=DRAFT
• 백엔드 -> AI 서버에 OCR 요청 (비동기)

2. AI 서버 -> POST /api/ocr-uploads/{id}/callback

• OCR 추출 결과 전달 -> OCR_DETAIL upsert, status=EXTRACTED

3. 사용자 UI -> GET /api/ocr-uploads/{id} (결과 조회)

• 프론트 화면에서 필드 수정

4. 사용자 PATCH /api/ocr-uploads/{id} (수정 반영)

• OCR_UPLOADS/OCR_DETAIL 수정

5. 사용자 POST /api/ocr-uploads/{id}/confirm

• status=CONFIRMED
• Event 생성/연동, 태그/카테고리 매핑

6. 히스토리

• GET /api/ocr-uploads?cursor=$size= (페이지네이션)
• GET /api/ocr-uploads/{id} (상세)

데이터 검증

• 날짜: YYYY-MM-DD (백엔드 파싱/검증)
• 카테고리: enum/코드 테이블 매핑
• 필수: imageUrl, userId(토큰)
• 길이 제한: title/memo/description 최대 길이 설정

저장/트랜잭션

• OCR_UPLOADS 생성 ↔ OCR_DETAIL upsert는 트랜잭션 처리
• CONFIRMED 시 Event 생성도 같은 트랜잭션(또는 outbox/event-driven)

예외/에러 코드

• 400 INVALID_PARAM (잘못된 날짜/범위, 빈 title 등)

• 401 UNAUTHORIZED

• 403 FORBIDDEN_OWNER (다른 사용자 리소스 접근)

• 404 NOT_FOUND (없는 업로드 id)

• 409 INVALID_STATE (확정 이후 수정 시도)

• 422 OCR_EMPTY_RESULT (AI 결과 없음)

• 500 OCR_UPSTREAM_ERROR

• 엔티티/레포지토리 : OcrUpload + OcrDetail (+상태값 enum)

• 컨트롤러/DTO : 업로드 생성, 콜백, 조회, 수정, 확정 API

• 서비스 : OCR 요청 발행, 콜백 처리, 상태 전이, 검증

• S3 presigned 업로드(선택) + 이미지 URL 검증

• 업로드 히스토리 페이지네이션/정렬(createdAt desc)

• 권한/소유자 체크 @AuthenticationPrincipal

• 통합 테스트(MockMvc) + 단위 테스트(Service)

• OpenAPI(Swagger) 문서화

• 오류/예외 응답 규격 통일(ErrorResponse)

---