[DP-385] 트렌드 내부 API 구현 (POST/GET /internal/trends)

[suheon98]

Summary

• POST /internal/trends: 수동 트리거 — 디버그·장애 복구용. 콘텐츠 0건→400, 5건 미만→422, force_refresh 지원
• GET /internal/trends/latest?unit=&scope=: unit+scope 기준 최신 스냅샷 조회, 없으면 404
• GET /internal/trends/{period_start}?unit=: 특정 기간 스냅샷 조회, 없으면 404

구현 내용

• ContentRepository.count_by_published_range() 추가 — 기간 내 콘텐츠 수 빠른 조회
• TrendGenerateRequest 업데이트: period_start optional화, Literal["daily","weekly","monthly"] 자동 검증, force_refresh 추가
• compute_period_end(unit, period_start) 헬퍼 추가 — period_start + unit → period_end 계산
• 자동 트리거는 run_trend_scheduler.py(DP-386)가 담당, 이 엔드포인트는 수동 재생성 전용

BE 팀 공유 (DP-387 참고용)

trend_snapshots.payload JSON 구조 (AI 서버 → BE 계약):

{
  "unit": "weekly",
  "period_start": "2026-04-14",
  "period_end": "2026-04-21",
  "date_label": "4월 14일 주간",
  "top_posts": [
    {
      "id": "content-uuid",
      "title": "원제목",
      "translated_title": "번역 제목 또는 null",
      "source_name": "Velog",
      "tags": ["Kubernetes", "Docker"],
      "view_count": 1234,
      "thumbnail_url": "https://...",
      "category": "Backend",
      "change_rate": 23.5
    }
  ],
  "top_posts_summary": "LLM 서사 요약 (실패 시 null)",
  "collection_summary": "수집 동향 요약 (daily는 항상 null, 실패 시 null)"
}

• is_my_interest는 payload에 없음 → BE가 user_tags JOIN으로 enrichment (DP-388)
• trending_keywords는 Phase 2 — FE 섹션 현재 숨김 처리

Test plan

• pytest tests/test_trend_endpoint.py — 13개 테스트 통과
• pytest -q — 434개 전체 통과
• ruff check . && black --check . — 클린

🤖 Generated with Claude Code