# YouTube Automation v1 — Implementation Task Breakdown

> **Doc maintenance:** This file is indexed in `docs/current/README.md`. If you change this file's role, scope, status, or filename, update `docs/current/README.md` in the same edit.


작성: 2026-03-28  
상태: **execution-ready draft**

## 목표
Kling 기반 유튜브 자동화 v1을 구현하기 위해 필요한 작업을 실제 개발 단위로 분해한다.

## Freeze checklist
- [ ] AK/SK → JWT auth code path 고정
- [ ] v1 endpoint constants confirmed/provisional 구분
- [ ] model_name allowlist 정리
- [ ] query single/list path deliverable 반영
- [ ] callback permissive debug mode 정의
- [ ] deterministic routing heuristics 정의
- [ ] endpoint-specific payload builders / validators 정의
- [ ] task schema metadata 확장

---

## Phase 1. Foundation

### T1. 환경/설정 계층
- [ ] Kling API base URL 상수화
- [ ] API token 로딩 방식 정의 (`~/.zshenv` 또는 런타임 env)
- [ ] callback base URL 설정 방식 정의
- [ ] endpoint constants 파일 작성

산출물:
- `configs/kling.py` 또는 `configs/kling.ts`
- `configs/env.example`

### T2. 데이터 구조 정의
- [ ] Project / Scene / KlingTask / Asset schema 정의
- [ ] JSON 파일 기반으로 갈지 SQLite로 갈지 결정
- [ ] task status enum 정의
- [ ] endpoint_type enum 정의

산출물:
- `schemas/`
- `data/README.md`

---

## Phase 2. API wrapper

### T3. 공통 HTTP client
- [ ] Authorization header 주입
- [ ] JSON request/response logging
- [ ] error normalization
- [ ] timeout/retry 기본값 정의

### T4. create_task wrapper
- [ ] `create_omni_video()`
- [ ] `create_text_to_video()` *(provisional wrapper; no implied stable default policy)*
- [ ] `create_image_to_video()` *(provisional wrapper; no implied stable default policy)*
- [ ] `create_reference_to_video()` *(provisional wrapper; no implied stable default policy)*
- [ ] `create_extend_video()`
- [ ] 공통 `create_kling_task()` 추상화

### T5. query/status wrapper
- [ ] 공식 query endpoint 확인 후 상태조회 함수 작성
- [ ] callback fallback poller용 인터페이스 정의

산출물:
- `scripts/kling_client.*`
- `scripts/kling_tasks.*`

---

## Phase 3. Callback + persistence

### T6. callback receiver
- [ ] HTTP endpoint 생성
- [ ] raw payload 저장
- [ ] signature/auth 검증 필요 여부 확인
- [ ] task_id 기준 내부 task 매핑

### T7. persistence layer
- [ ] task row 생성/업데이트
- [ ] asset row 생성
- [ ] 다운로드 경로 구조 정의
- [ ] logs/callbacks 저장 규칙 정의

산출물:
- `server/callback_receiver.*`
- `data/tasks/`
- `data/assets/`
- `logs/callbacks/`

---

## Phase 4. Scene pipeline

### T8. scene router
- [ ] scene_type → endpoint_type 라우팅 규칙 구현
- [ ] current stable policy는 Omni-first로 고정하고, non-Omni 라우팅은 feature-flag 또는 caller-explicit mode로 분리
- [ ] continuity scene 분기 구현
- [ ] extend 조건 구현

### T9. dispatcher / scheduler
- [ ] active concurrency counter
- [ ] queue 구현
- [ ] callback completion 시 slot release
- [ ] timeout watcher 구현

산출물:
- `scripts/scene_router.*`
- `scripts/scheduler.*`

---

## Phase 5. Quality / recovery

### T10. asset downloader
- [ ] callback 결과 URL 즉시 다운로드
- [ ] 만료 전 보존
- [ ] 파일명 규칙 정의

### T11. QC checks
- [ ] clip 존재 여부
- [ ] duration 체크
- [ ] decode 가능 여부
- [ ] 간단한 시각적 sanity check

### T12. retry policy
- [ ] transient failure retry
- [ ] quality failure retry
- [ ] endpoint escalation 규칙
- [ ] extend retry 규칙

---

## Phase 6. Integration

### T13. end-to-end smoke test
- [ ] single scene text flow
- [ ] single scene image_ref flow
- [ ] callback round-trip 확인
- [ ] asset persistence 확인

### T14. mini batch test
- [ ] 3~5 scene dispatch
- [ ] concurrency 제어 확인
- [ ] partial failure recovery 확인

### T15. render handoff
- [ ] final stitching 입력 포맷 정의
- [ ] clips → render pipeline handoff

---

## 권장 구현 순서
1. T1 환경/상수
2. T3 공통 client
3. T4 create_task wrapper
4. T6 callback receiver
5. T7 persistence
6. T8 router
7. T9 scheduler
8. T10 downloader
9. T13 smoke test
10. T11/T12 QC+retry
11. T14/T15 integration

---

## 즉시 결정 필요 항목
- 구현 언어: Python vs TypeScript
- persistence: JSON vs SQLite
- callback receiver: standalone server vs existing service 내 포함
- asset 저장 위치 표준화

---

## 추천
현재 workspace 특성과 기존 스크립트 흐름상 v1은 아래가 가장 현실적이다:
- **Python 구현**
- **SQLite 또는 JSON+filesystem 혼합**
- **작은 callback receiver 서버**
- **filesystem 기반 asset 저장**