본문으로 건너뛰기

원본 비디오 다운로드 정책

문서 정보

  • 작성일: 2026-04-05
  • 최종 업데이트: 2026-04-10
  • 버전: v1.1.0

TL;DR

원본 비디오 다운로드는 1회 결제(2,000 톨)당 10회 다운로드 사이클로 운영됩니다. 사이클에 만료 기간은 없으며, 10회 소진 시 재결제로 새 사이클을 시작합니다. 구매 즉시 다운로드 URL이 반환됩니다.


목차

  1. 개요
  2. 다운로드 사이클
  3. 가격
  4. GymStaff 다운로드 UX 계약
  5. 클라이언트 플로우
  6. 엔드포인트
  7. 다운로드 이력

개요

사용자는 앱에서 원본 영상을 스트리밍으로 시청할 수 있지만, 기기에 저장하려면 톨(Grain)으로 구매해야 합니다. 구매 시 다운로드 URL이 즉시 반환되며, 이후 다운로드 횟수가 남아있는 동안은 추가 과금 없이 다운로드할 수 있습니다.


다운로드 사이클

사이클 정책

항목
1회 결제당 다운로드 횟수10회
만료 기간무기한
사이클 소진 시동일 비용으로 재결제 → 새 10회 사이클

카메라별 개별 구매

원본 비디오 1개에는 여러 카메라 앵글이 포함되어 있지만, 다운로드는 카메라별로 개별 구매합니다. 각 카메라 앵글마다 별도의 다운로드 사이클이 생성됩니다.

사이클 상태

상태설명
ACTIVE다운로드 가능 (downloadCount < maxDownloads)
EXHAUSTED사이클 소진 (downloadCount >= maxDownloads), 재구매 필요

가격

콘텐츠길이가격
원본 비디오10분 (600초)2,000 grain

GymStaff 다운로드 UX 계약

GymStaff Dashboard는 active download cycle 재사용 정책을 유지합니다. 따라서 같은 카메라라도 어떤 항목은 이번 호출에서 차감되고, 어떤 항목은 기존 권한에 포함될 수 있습니다. 이 내부 정책은 FE가 추론하지 않고 서버 계산 결과를 그대로 사용해야 합니다.

핵심 규칙

필드의미
hasDownloadAccess추가 차감 없이 바로 다운로드 가능한 상태인지
pricingState=INCLUDED기존 active cycle에 포함되어 이번 호출 차감 없음
pricingState=CHARGED이번 호출에서 새 차감 필요
reusedActiveCycle=true단건 purchase 응답에서 기존 cycle을 재사용했음을 의미

FE 해석 규칙

  • hasDownloadAccess=false는 권한 없음이 아니라 신규 차감 필요 상태입니다.
  • 권한 없음은 별도 에러 코드(GYM_STAFF_MISMATCH)로만 판단합니다.
  • 요약 박스는 반드시 서버 summary를 사용하고, FE가 선택 항목 가격을 자체 합산하지 않습니다.

GymStaff 전용 엔드포인트

메서드경로설명
GET/gym-staff/me/balancelinked user grain 잔액 조회
GET/gym-staff/videos/:gymUuid/:videoUuid/cameras카메라 목록 + item별 가격 상태 조회
POST/gym-staff/videos/pricing-preview선택 항목의 item별 가격 상태 + summary 계산
POST/gym-staff/videos/:gymUuid/:videoUuid/purchase-download단건 다운로드 구매 + 실제 차감 결과 반환
POST/gym-staff/videos/bulk-purchase-download다중 다운로드 구매 + summary 반환

응답 필드 차이

  • pricing-preview.summary
    • selectedCount
    • includedCount
    • chargedCount
    • totalDeductedAmount
    • balanceAfter
    • message
  • purchase-download
    • priceCharged
    • balanceAfterPurchase
    • reusedActiveCycle
  • bulk-purchase-download
    • summary
    • downloads[]

클라이언트 플로우

  1. 이력/상태 조회canDownload 확인
  2. canDownload: true → 다운로드 URL 요청 (횟수 차감)
  3. canDownload: false → 구매 또는 재구매 (Grain 차감 + URL 즉시 반환)

엔드포인트

메서드경로설명
POST/videos/:videoUuid/purchase구매 + 다운로드 URL 즉시 반환
GET/videos/:videoUuid/purchase-status구매 상태 + 사이클 정보 조회
GET/user-schedules/:uuid/videos/:videoUuid/download-url다운로드 URL 요청 (횟수 차감)
GET/videos/:videoUuid/download-history다운로드 이력 조회

구매 요청

POST /videos/:videoUuid/purchase
Body: { cameraCode: string, userScheduleUuid: string }
Response: { downloadUrl, downloadCount, maxDownloads, remainingDownloads }

구매 상태 조회

GET /videos/:videoUuid/purchase-status?cameraCode=xxx
Response: { purchased, downloadCount, maxDownloads, remainingDownloads, canDownload }

다운로드 이력

사용자는 특정 비디오의 다운로드 사이클 이력과 각 다운로드 기록을 조회할 수 있습니다.

GET /videos/:videoUuid/download-history?cameraCode=xxx
Response: {
currentCycle: { uuid, downloadCount, maxDownloads, remainingDownloads, purchasedAt },
histories: [{ uuid, downloadedAt, ip, success }],
previousCycles: [{ uuid, downloadCount, maxDownloads, remainingDownloads, purchasedAt }]
}
  • currentCycle: 현재 활성 사이클 정보 (없으면 null)
  • histories: 현재 사이클의 다운로드 기록 (최신순)
  • previousCycles: 소진된 이전 사이클 목록
보안 모니터링

모든 다운로드 시 IP 주소와 User-Agent가 기록되어, 비정상적인 다운로드 패턴을 감지할 수 있습니다.


변경 이력

버전날짜변경 내용
v1.0.02026-04-05초기 문서 작성
- 다운로드 사이클 정책 (10회/1결제, 무기한)
- 카메라별 개별 구매
- 구매 시 URL 즉시 반환
- 다운로드 이력 조회 API
v1.1.02026-04-10GymStaff 다운로드 계약 보강
- balance / pricing-preview / bulk-purchase-download 추가
- included/charged 해석 규칙과 summary 사용 규칙 추가