refactor: 가정통신문 분석 API 스펙 정의

[deli-minju]

📌 작업 요약

• 요약:
  • POST /ai/newsletters/analyze 엔드포인트 추가
  • 기존 dateCandidates 요청 형식과 items 응답 형식 유지
  • 분석 응답에 BE 저장에 필요한 title, summary, items, meta 포함
  • AI 서버는 DB 저장을 직접 알지 않고 분석 결과 JSON만 반환하도록 경계 정리
  • 가정통신문 분석 API 요청/응답 스펙 문서화
• 관련 이슈: closes [TASK] AI 서버 가정통신문 전체 분석 API 스펙 확정 #3

🌿 브랜치 정보

• Source: refac/#3-newsletter-analyze-api-spec
• Target: develop (기본)

✅ 체크리스트

• 브랜치 컨벤션 준수 (feat/refac/hotfix/chore/design/bugfix)
• 커밋 컨벤션 준수 (feat/fix/refactor/docs/style/chore)
• self-review 완료
• 테스트 및 로컬 실행 확인 완료

🧪 테스트 결과

.\.venv\Scripts\python.exe -m ruff check .
# All checks passed!

.\.venv\Scripts\python.exe -m compileall app
# app 모듈 컴파일 확인

.\.venv\Scripts\python.exe -c "from app.main import app; schema=app.openapi(); ref=chr(36)+'ref'; analyze=schema['paths']['/ai/newsletters/analyze']['post']; print(analyze['requestBody']['content']['application/json']['schema'][ref]); print(analyze['responses']['200']['content']['application/json']['schema'][ref])"
# #/components/schemas/NewsletterAnalysisRequest
# #/components/schemas/NewsletterAnalysisResponse

Summary by CodeRabbit

새 기능 및 업데이트

• 새 기능

  • 가정통신문 종합 분석 API 엔드포인트(POST /ai/newsletters/analyze) 추가: 제목, 요약, 항목을 한 번에 분석하여 반환하며, 신뢰도 및 사용자 확인 관련 정보를 포함합니다.

• 문서

  • API 스펙 및 요청/응답 스키마에 대한 상세 문서 업데이트

[coderabbitai]

Warning

Rate limit exceeded

@deli-minju has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 47 minutes and 38 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 627149d9-491e-4451-b81f-801c55769c04

📥 Commits

Reviewing files that changed from the base of the PR and between 84ea064 and 4c68c2b.

📒 Files selected for processing (2)

• app/services/newsletter_extractor.py
• docs/newsletter-extraction.md

📝 Walkthrough

📋 개요

이 PR은 가정통신문 분석을 위한 새로운 API 엔드포인트 POST /ai/newsletters/analyze를 추가하여, 제목·요약·항목을 함께 반환하는 분석 계약을 수립합니다. 기존 항목 추출 로직을 재구성하고 프롬프트 스키마를 통일하며 API 문서를 갱신합니다.

---

📝 변경사항

가정통신문 분석 API 추가

레이어 / 파일	설명
요청/응답 스키마 계약 정의 app/schemas.py	NewsletterAnalysisRequest를 신규 기본 요청 스키마로 정의하고, NewsletterExtractionRequest를 호환용 래퍼로 재구성하며, NewsletterAnalysisResponse를 새 응답 계약으로 추가하여 title, summary, items, meta 필드를 포함합니다.
분석 API 엔드포인트 추가 app/routers/newsletters.py	POST /ai/newsletters/analyze 라우트 핸들러를 추가하여 분석 요청을 처리하고, prompt-preview의 응답 스키마를 통일된 ANALYSIS_RESPONSE_SCHEMA로 변경합니다.
프롬프트 및 응답 스키마 구조화 app/services/newsletter_prompt.py	SELECTED_DATE_CANDIDATE_SCHEMA와 ITEM_RESPONSE_SCHEMA로 공통화한 뒤, EXTRACTION_RESPONSE_SCHEMA를 재구성하고 ANALYSIS_RESPONSE_SCHEMA를 신규 추가하며, 프롬프트 빌더 함수들의 입력 타입을 NewsletterAnalysisRequest 기반으로 변경합니다.
제목·요약·항목 추출 로직 구현 app/services/newsletter_extractor.py	analyze_newsletter 함수를 추가하여 제목 추출(_extract_document_title), 요약 생성(_summarize_document), 항목 추출(_extract_items)을 공용 헬퍼로 조합하고, 메타 데이터 빌딩(_build_meta)을 분리합니다.
API 문서 및 README 업데이트 README.md, docs/newsletter-extraction.md	README에서 AI 서버 역할과 주요 엔드포인트를 재정리하고, 분석 API의 요청/응답 스키마, 필드 정의, BE/AI 서버 책임 경계, 유지 여부 검토 조건을 상세히 문서화합니다.

---

🎯 추정 코드 리뷰 난이도

🎯 3 (보통) | ⏱️ ~25분

---

🔗 관련 PR

• GACHI-Project/GACHI-AI#2: PR #2에서 도입한 app/schemas.py, app/routers/newsletters.py, app/services/newsletter_extractor.py, app/services/newsletter_prompt.py의 기존 항목 추출 로직(/extract-items, prompt-preview)을 바탕으로, 본 PR이 이들 스키마와 계약을 NewsletterAnalysis* 타입으로 전환하고 POST /ai/newsletters/analyze 엔드포인트와 분석 로직을 추가합니다.

---

🏷️ 제안 라벨

chore

---

👥 제안 리뷰어

• Hminkyung

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	PR 제목은 가정통신문 분석 API 스펙 정의라는 주요 변경사항을 명확하고 간결하게 요약하고 있습니다.
Description check	✅ Passed	PR 설명은 작업 요약, 브랜치 정보, 체크리스트, 테스트 결과를 포함하여 필요한 대부분의 섹션을 다루고 있습니다.
Linked Issues check	✅ Passed	PR의 모든 변경사항이 이슈 #3의 목표를 충족합니다: POST /ai/newsletters/analyze 엔드포인트 추가, title/summary/items/meta 응답 포함, 기존 형식 유지, API 스펙 문서화 완료.
Out of Scope Changes check	✅ Passed	모든 변경사항이 이슈 #3의 요구사항과 관련이 있으며, 범위를 벗어난 변경사항이 없습니다. README 업데이트, 엔드포인트 추가, 스키마 재구성, 문서화가 모두 API 스펙 정의 목표에 부합합니다.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refac/#3-newsletter-analyze-api-spec

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@app/services/newsletter_extractor.py`:
- Around line 237-243: The current summary logic uses request.translated_text
directly so a whitespace-only translated_text causes _split_sentences to return
empty and trigger an incorrect fallback; change the selection to use a trimmed
translated_text (e.g., translated = (request.translated_text or "").strip()) and
if that is empty fall back to request.original_text before calling
_split_sentences; update the code around variables request.translated_text,
request.original_text and the call to _split_sentences to reflect this trimmed
fallback.

In `@docs/newsletter-extraction.md`:
- Line 25: 문서의 표현이 모순됩니다: `/ai/newsletters/analyze`에 대해 "기존 `extract-items` 입력
형식을 그대로 사용"한다고 하면서도 `startOffset`/`endOffset`를 필수로 표기한 부분(`startOffset`,
`endOffset`)이 있어 하위 호환이 깨지는 것으로 보입니다; 수정 방법은 두 가지 중 하나를 택해 일관성 있게 반영하되 구현 세부 심볼을
명확히 변경하세요 — (A) 호환 유지 시: `startOffset`과 `endOffset`의 필수 표시를 `아니오`로 바꿔 문서에서 선택적
필드로 표시하고 `/ai/newsletters/analyze` 문장(현 "기존 형식 그대로 사용")을 그대로 두기, 또는 (B) 필드를 실제로
필수로 만들 경우: `/ai/newsletters/analyze` 설명의 "기존 형식 그대로 사용" 문구를 "기존 형식 확장
(startOffset, endOffset 필수)" 같은 문구로 변경하고 필드 설명(`startOffset`, `endOffset`)을 필수로
명확히 표기; 관련 텍스트(현재 문제로 지적된 문장과 `startOffset`/`endOffset` 표기)를 함께 업데이트해 불일치가 없도록 해
주세요.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4178b5f5-4f0e-43ed-8255-7cc7fd812b90

📥 Commits

Reviewing files that changed from the base of the PR and between 629ad96 and 84ea064.

📒 Files selected for processing (6)

• README.md
• app/routers/newsletters.py
• app/schemas.py
• app/services/newsletter_extractor.py
• app/services/newsletter_prompt.py
• docs/newsletter-extraction.md

[Hminkyung]

확인했씁니다!! 고생하셨습니다~