본문으로 건너뛰기

원본 비디오 다운로드 정책

문서 정보​

  • 작성일: 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 사용 규칙 추가