GET /api/v1/quota

의도

현재 사용자의 주 quota 상태 조회.

인증

Bearer JWT 필수

응답

200 OK

{
  "weekly_used": 3,
  "weekly_limit": 10,
  "remaining": 7,
  "week_start": "2026-05-04T15:00:00Z",
  "next_reset_at": "2026-05-11T15:00:00Z"
}

필드	설명
weekly_used	이번 주 reveal 사용 횟수. 음수 가능 — 광고 시청 시 -1 (선납 효과).
weekly_limit	주 무료 quota (기본 10, WEEKLY_FREE_QUOTA 환경변수)
remaining	실제 사용 가능 횟수 = weekly_limit - weekly_used, 0 미만은 0 으로 클램프
week_start	이번 주 시작 시각 (월요일 00:00 KST 의 UTC 표현, 즉 일요일 15:00 UTC) RFC3339
next_reset_at	다음 reset 시각 (= week_start + 7d). 클라이언트 카운트다운용

curl 예제

# 로컬
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/quota | jq

# prod
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.dartbrief.com/api/v1/quota | jq

비즈니스 메모

• quota row 가 없으면 자동 초기화 (GetOrInit) — weekly_used=0, quota_week_start=이번 주 월요일 KST
• 주 reset: quota_week_start != currentWeekStart() 이면 weekly_used 0 으로 초기화 (음수였어도 0). 다음 GET 호출 시 또는 reveal/ad reward 호출 시 자동 적용.
• ad_bonus 컬럼 없음 — V4 (2026-05-06) 에서 제거. 광고 보상은 weekly_used -= 1 로 표현. ad_reward_transactions 테이블은 SSV idempotency (중복 콜백 차단) 전용.
• 비용 모델: LLM 호출은 공시당 1회 (스케줄러), reveal 은 캐시 조회 → 사용자 횟수와 LLM 비용 무관. 자세한 정책 결정 맥락: docs/policies/quota-ad-v3.md §V4

---

POST /api/v1/quota/ad-reward

의도

광고 시청 보너스 지급 (dev/local 전용 legacy 경로). 백엔드는 weekly_used -= 1 (음수 허용) 적용.

prod 에서는 404 반환 — prod 보상은 AdMob SSV 콜백 (GET /api/v1/admob/ssv) 이 처리.

인증

Bearer JWT 필수

응답

200 OK — GET /api/v1/quota 와 동일 스키마

404 Not Found — 비-local/dev 환경

curl 예제 (로컬/dev only)

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/quota/ad-reward | jq