[feat] Add extraction result schema and worker extraction interface

[KyungminPark-steck]

📖 배경

processing job 결과에 LLM 기반 추출 결과를 포함해야 합니다.

최종적으로는 인스타그램 게시글/릴스 caption에서 가게명, 주소, 근거 문장, confidence 성격의 certainty 등을 추출하고, 이후 HF endpoint 호출, fallback 모델, DB 저장, API 응답까지 연결해야 합니다.

그 전에 API 응답 필드와 내부 도메인 모델, worker 파이프라인의 추출 단계 인터페이스를 먼저 정리해 두어야 실제 LLM endpoint 없이도 테스트 가능한 구조로 개발을 이어갈 수 있습니다.

🎯 목표

job result 응답에 extraction_result가 포함될 수 있도록 schema와 도메인 모델을 추가합니다.

worker 파이프라인에는 mock 가능한 extraction client 인터페이스를 추가해, 실제 HF endpoint 연결 전에도 추출 단계의 흐름을 테스트할 수 있게 합니다.

🛠️ 구현 내용

• API result 응답 schema에 extraction_result 필드 추가
• 추출 결과 도메인 모델 추가
  • ExtractionResult
  • ExtractionCertainty
• LLM 응답 파싱용 schema 추가
  • ExtractionLLMResponse
• worker processor에 extraction client 인터페이스 추가
  • caption이 있는 경우 extraction client 호출
  • 추출 실패 시 job 전체 실패로 처리하지 않고 기존 crawl 결과는 저장 가능하도록 처리
• HF extraction client 초안 추가
  • endpoint URL/token 기반 호출 구조
  • HF 응답 payload에서 generated text 추출
  • generated text에서 JSON object 파싱
  • schema validation 후 domain model로 변환
• 설정값 추가
  • HF_EXTRACTION_ENDPOINT_URL
  • HF_EXTRACTION_API_TOKEN
  • HF_EXTRACTION_MODEL_NAME
  • HF_EXTRACTION_TIMEOUT_SECONDS
  • HF_EXTRACTION_MAX_NEW_TOKENS
• 관련 테스트 추가 및 기존 테스트 수정
  • extraction schema validation
  • HF extraction client 응답 파싱
  • worker processor가 caption을 extraction client에 전달하는지 검증
  • job result response가 extraction_result를 포함할 수 있는지 검증

⚠️ 고려사항

• 이번 이슈에서는 실제 HF endpoint 운영 연결은 제외합니다.
• 이번 이슈에서는 DB 컬럼 추가 및 migration은 제외합니다.
• 실제 endpoint 장애가 job 전체 실패로 번지지 않도록, extraction 실패 시 extraction_result는 비워두고 crawl 결과 저장은 계속 가능해야 합니다.
• 외부 API 필드명은 확장성을 고려해 extraction_result로 통일합니다.
• .env는 로컬 개발용으로만 사용하며 Git에 포함하지 않습니다.

✅ 완료 조건

• JobResultResponse에서 extraction_result 필드를 받을 수 있다.
• worker processor가 caption을 extraction client에 전달할 수 있다.
• extraction client는 mock/fake로 대체 가능해 실제 HF endpoint 없이 테스트할 수 있다.
• HF extraction client 초안이 generated text/JSON/schema validation 흐름을 처리한다.
• 관련 테스트가 추가되어 전체 pytest가 통과한다.

테스트 명령:
.\.venv\Scripts\python.exe -m pytest