# YouTube Automation — Kling 3.0 Refresh Plan

> **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  
상태: **refined pre-implementation plan**

## 목표
새로 확보한 `KlingAI Series 3.0 Model API Specification`를 반영해 파이프라인 문서/설계/코드 스캐폴드를 최신화한다.

## 핵심 원칙
- **확인된 사실**과 **미검증 계약**을 분리한다.
- **v1 핵심 구현 범위**와 **관찰됐지만 아직 smoke-test 전인 항목**을 구분한다.
- wrapper/repackaged docs는 capability 확인용으로만 사용하고, field-level truth는 공식/공식 연결 문서 우선으로 본다.
- 실 API smoke test 전까지는 provisional endpoint/path/model을 명시한다.

## Pre-implementation freeze checklist
1. Auth 방식 고정: **AK/SK → JWT Bearer**
2. v1 endpoint constants 상태 구분
   - confirmed
   - provisional
3. endpoint별 model_name allowlist 정리
4. Query Single/List 구조를 placeholder가 아닌 deliverable로 반영
5. callback receiver를 **permissive debug mode** + local shared-secret mode로 구분
6. deterministic scene routing heuristics 명시
7. endpoint-specific payload builders / validators 도입
8. task schema에 model/path/retry/error metadata 확장

## 작업 범위
### A. 문서 최신화
1. 메인 파이프라인 문서에 3.0 반영 포인트 추가
2. v1 구현 스펙에 auth/query/model/provisional contract 반영
3. implementation task 문서에 freeze checklist 반영

### B. 설계 최신화
1. scene taxonomy 재정의
   - `text_single`
   - `text_multi_shot`
   - `image_single`
   - `image_multi_shot`
   - `continuity`
   - `extend`
2. deterministic routing heuristics 정의
3. model selection 규칙 정의
4. query single/list recovery 전략 정의
5. callback receiver modes 정의
   - permissive debug mode
   - shared-secret local mode

### C. 코드 스캐폴드 최신화
1. auth layer를 AK/SK → JWT 기준으로 정리
2. endpoint constants에 confirmed/provisional 주석 반영
3. endpoint-specific payload builders / validators 추가
4. task schema에 path/model/retry/error/submitted/finished metadata 확장
5. query helper를 capability-aware placeholder로 정리
6. receiver에 permissive debug mode 추가

### D. 비목표
- real API smoke test 자체 수행
- QC / retry / batch 구현 완료
- production hardening 완료

## 완료 기준
- 문서/설계/코드가 3.0 정보와 모순 없이 정렬됨
- v1에서 confirmed/provisional 경계가 명확함
- auth/query/model/routing/validation/drift 주의점이 문서와 코드에 모두 반영됨