버전: 개발 버전 (최신)

시작 전 영상(인트로 비디오) 조회 API (v2)

시작 전 영상 조회 API는 로그인 직후 ~ 액세스 코드 활성화 전 단계에서, 활성 학습 번들의 첫 레슨(label=1)에 포함된 "시작 전 영상"을 제공하는 API입니다. 사용자가 활성화 전에 프로그램의 첫인상을 영상으로 경험하게 하여 온보딩 전환을 돕습니다.

주요 특징

활성화 전 호출 가능: cycle/레슨 해금 상태를 검증하지 않아, 액세스 토큰만 있으면(=로그인 직후) 호출됩니다.
GCS 직링크 영상: 응답의 media.urlString은 GCS 직링크이며 클라이언트가 직접 재생합니다(signed URL/프록시 아님).
캐싱 최적화: 추출 결과({ title, media })를 Redis 캐시(learning:intro-video:{bundleId}:{language}, TTL 1시간)하여 빠르게 응답합니다.
영상 없음 허용: 첫 레슨에 영상이 없거나 콘텐츠 조회에 실패하면 media: null로 200을 반환합니다.

주의사항

언어 헤더: Accept-Language가 없으면 기본값 de-DE로 처리됩니다 (de-DE, ko-KR, en-US 지원).
사용자 인증: 유효한 Access Token이 필요합니다 (JwtAuthGuard).
활성 번들 필요: 활성 학습 번들이 없으면 title: "" + media: null로 응답합니다.

`GET /v2/learning/onboarding/intro-video` ⭐

활성 학습 번들의 첫 레슨(label=1) 콘텐츠 JSON에서 첫 번째 영상(video) 미디어 노드를 추출하여 반환합니다.

Path: GET /v2/learning/onboarding/intro-video
인증: Access Token (JwtAuthGuard) — cycle/레슨 해금 상태는 검증하지 않음
Rate Limit: 60/분 (전역 default)
🔗 라이브 명세 (Swagger UI): dev

Request

Header	Value
`Authorization`	`Bearer <accessToken>` (필수)
`Accept-Language`	`de-DE` \| `ko-KR` \| `en-US` (미지정 시 `de-DE`)

동작

활성 학습 번들을 조회합니다.
번들의 첫 레슨(label=1)을 찾고, 해당 레슨 번역의 제목과 콘텐츠(wcs:// 참조 URI)를 조회합니다.
GCS에서 레슨 콘텐츠 JSON을 읽어, nodes[] 중 처음 등장하는 type: "media" 이면서 media.type === "video" 노드를 추출합니다.
추출 결과를 Redis에 캐시한 뒤 반환합니다. 영상이 없으면 media: null을 반환합니다.

Response 200 OK — `IntroVideoResponseDto`

200 OK - 영상 있는 경우

{
  "title": "Lektion 1. Grundlagen",
  "media": {
    "type": "video",
    "description": "BigBuckBunny.",
    "urlString": "https://storage.googleapis.com/dta-wide/prod/lesson/1.0.0/de-DE/lesson_01/videos/1.1.mp4"
  }
}

200 OK - 영상 없는 경우 (또는 활성 번들/콘텐츠 부재)

{
  "title": "Lektion 1. Grundlagen",
  "media": null
}

응답 필드

필드	타입	설명
`title`	string	첫 레슨(label=1)의 제목. 활성 번들/레슨이 없으면 빈 문자열
`media`	object \| null	인트로 영상 미디어. 영상이 없으면 `null`
`media.type`	string	미디어 타입 (`video`)
`media.description`	string	영상 설명
`media.urlString`	string	GCS 직링크 영상 URL (클라이언트가 직접 재생)

Errors

HTTP	code	message	발생 조건
401	2051	INVALID_TOKEN	Authorization 누락·무효·만료 (`JwtAuthGuard` 검증 실패)
429	1000	ThrottlerException: Too Many Requests	전역 throttle 60/분 초과

캐시 무효화

응답 결과는 learning:intro-video:{bundleId}:{language} 키로 1시간 캐시됩니다. 학습 번들 재import 시 캐시가 무효화되며, 번들 ID가 키에 포함되어 새 번들은 자동으로 분리됩니다. 콘텐츠 fetch에 실패한 경우(media: null)는 캐시하지 않습니다.

다음 단계

영상 시청 후 → 서비스 활성화: POST /v2/auth/user-cycle/activate (Authorization=user access token).
활성화 후 일일 학습 콘텐츠: 일일 콘텐츠 조회.

GET /v2/learning/onboarding/intro-video ⭐​

Request​

동작​

Response 200 OK — IntroVideoResponseDto​

응답 필드​

Errors​

다음 단계​