본문으로 건너뛰기

추가콕 시스템

문서 정보​

  • 작성일: 2026-03-21
  • 최종 업데이트: 2026-03-21
  • 버전: v1.0.0
TL;DR

추가콕은 녹화 완료 후 영상 시청 중 특정 순간을 마킹하는 북마크 기능입니다. 개수/멤버십 제한 없이 자유롭게 추가/제거할 수 있으며, 원하는 순간을 마이콕으로 전환하여 영구 보관할 수 있습니다.

목차​

  1. 추가콕이란?
  2. 콕 vs 추가콕 vs 마이콕
  3. 전체 흐름
  4. 저장 구조
  5. 마이콕 전환
  6. 전환된 추가콕 조회
  7. 자동 정리
  8. FAQ

추가콕이란?​

추가콕(PinKok)은 "영상을 보면서 원하는 순간을 마킹" 하는 기능입니다.

녹화 중에만 콕을 찍을 수 있는 기존 콕과 달리, 추가콕은 녹화가 끝난 후 영상을 시청하면서 언제든 자유롭게 마킹할 수 있습니다. 마치 브라우저에서 북마크를 추가하듯이, 제한 없이 원하는 만큼 추가하고 제거할 수 있습니다.

비유로 이해하기

콕이 "경기 중 심판이 휘슬을 불어 순간을 기록"하는 것이라면, 추가콕은 "경기 영상을 다시 보면서 하이라이트 장면에 포스트잇을 붙이는 것"입니다. 포스트잇을 붙였다 떼었다 자유롭게 할 수 있고, 특별히 보관하고 싶은 장면은 마이콕으로 영구 저장할 수 있습니다.

콕 vs 추가콕 vs 마이콕​

구분콕(Kok)추가콕(PinKok)마이콕(MyKok)
성격녹화 중 타임스탬프시청 중 북마크영구 보관 클립
생성 시점녹화 중영상 시청 중콕/추가콕에서 전환
수명영상 만료까지영상 만료까지영구
저장소Firestore → DBFirestore만DB
개수 제한패스별 상이없음멤버십별 최대 개수
멤버십패스 보유자제한 없음PLUS 이상
리워드포인트 적립 대상없음없음
입력 소스APP / BEACONAPP만-

전체 흐름​

저장 구조​

추가콕은 Firestore에만 저장되며 서버 DB를 거치지 않습니다.

Firestore 경로​

gyms/{gymCode}/date/{YYYY-MM-DD}/hour/{hour}/users/{userId}/pin-timestamps/{docId}

기존 콕의 Firestore 경로와 나란한 구조입니다:

컬렉션용도
timestamps콕 (녹화 중 생성)
pin-timestamps추가콕 (시청 중 생성)

저장 필드​

필드타입설명
timestampFirestore Timestamp영상 내 마킹 시점 (녹화 시점 기준)
sourcestring항상 'APP' (BEACON은 녹화 중에만)
주의

timestamp는 사용자가 시청하는 현재 시각이 아니라, 영상 내 마킹한 순간에 해당하는 녹화 시점입니다.

예: 3월 19일 17:00~18:00 녹화 영상의 17:35 지점을 3월 21일에 마킹 → timestamp는 2026-03-19T17:35:00

크로스 디바이스​

Firestore의 실시간 동기화 덕분에, 앱에서 마킹한 추가콕이 웹에서도 즉시 보입니다.

마이콕 전환​

추가콕을 마이콕으로 전환하면 영상 만료 후에도 영구 보관됩니다.

전환 API​

**POST /api/v1/my-koks/{userScheduleUuid}/pin-kok**

필드타입설명
kokTimestampIdstringFirestore 문서 ID
videoUuidstring (UUID)시청 중인 영상 UUID
timeSlotnumber (0-5)시청 중인 타임슬롯
timestampnumber녹화 시점 타임스탬프 (Unix ms)
offsetInMsnumber (0-600000)10분 영상 내 재생 위치 (ms)

전환 시 서버 검증​

전환 후 저장되는 데이터​

전환된 마이콕은 기존 콕에서 전환된 마이콕과 동일한 구조이지만, 두 가지가 다릅니다:

필드콕 출처추가콕 출처
kokInfo.kokId부모 Kok 레코드 IDnull
kokInfo.source'APP' 또는 'BEACON''PIN'

이 차이는 DB 내부 식별용이며, 배치 클립 생성은 동일하게 처리됩니다.

전환된 추가콕 조회​

클라이언트가 추가콕 목록에서 "이미 마이콕으로 저장됨"을 표시하기 위한 API입니다.

조회 API​

**GET /api/v1/my-koks/{userScheduleUuid}/pin-koks/{timeSlot}**

[
  {
    "kokTimestampId": "pin_abc123xyz789",
    "myKokUuid": "019d0c07-9cb6-7762-a170-b8daa42a2c78"
  }
]

Firestore의 추가콕 목록과 이 응답을 대조하여:

  • 매칭됨 → 마이콕 저장됨 표시
  • 매칭 안 됨 → 전환 버튼 표시

자동 정리​

추가콕은 별도 삭제 처리가 필요 없습니다.

기존 Firestore cleanup 스케줄러가 날짜 폴더 단위로 재귀 삭제하기 때문에, pin-timestamps 컬렉션도 함께 정리됩니다.

gyms/{gymCode}/date/{YYYY-MM-DD}  ← 이 단위로 삭제
  ├── hour/{hour}/users/{userId}/timestamps/     ← 콕 (함께 삭제)
  └── hour/{hour}/users/{userId}/pin-timestamps/ ← 추가콕 (함께 삭제)

FAQ​

Q: 추가콕에 개수 제한이 있나요?​

없습니다. 영상 시청 중 원하는 만큼 자유롭게 추가/제거할 수 있습니다.

Q: 추가콕을 마킹하려면 멤버십이 필요한가요?​

아닙니다. 추가콕 마킹 자체는 누구나 가능합니다. 단, 마이콕으로 전환할 때는 PLUS 이상 멤버십이 필요합니다.

Q: 영상이 만료되면 추가콕은 어떻게 되나요?​

Firestore cleanup 스케줄러가 자동으로 삭제합니다. 마이콕으로 전환된 것은 서버 DB에 별도 저장되어 있으므로 영향 없습니다.

Q: 같은 추가콕을 두 번 마이콕으로 전환할 수 있나요?​

아닙니다. kokTimestampId 기반 중복 방지가 적용되어 409 Conflict가 반환됩니다.

Q: 추가콕으로 만든 마이콕과 기존 콕으로 만든 마이콕의 차이는?​

사용자 입장에서는 동일합니다. 내부적으로 source 필드가 'PIN'으로 표시되며, 배치 클립 생성도 동일한 파이프라인을 사용합니다.

관련 문서​

  • 마이콕 시스템
  • 추가콕 클라이언트 연동 가이드 (현재 docs-site 미포함)
  • ADR-013: PinKok → MyKok 전환 (docs/maintained/my-kok/client/adr/013-pin-kok-to-my-kok-conversion.md)

변경 이력​

버전날짜변경 내용
v1.0.02026-03-21초기 문서 작성 - 추가콕 개념 및 콕/마이콕 비교 - Firestore 저장 구조 - 마이콕 전환/조회 API - 자동 정리 메커니즘