# 작업 사양: E1b — 촬영 설계(storyboard.json) → job.json 변환기 `plan`

## 목표
`apps/studio/tools/pipeline/studio_run.py`에 `plan` 명령을 추가한다. Studio 촬영 설계 데이터 `storyboard.json`을 읽어, 실행기 입력인 `job.json`을 만든다.
크레딧과 네트워크는 쓰지 않는다. Dreamina CLI(`dreamina-canvas`)를 절대 호출하지 않는다.

## 먼저 읽을 파일 (읽기만)
- `apps/studio/tools/pipeline/README.md`, `studio_run.py`, `engine/job.py`, `presets/drama.json`
- `apps/studio/tools/pipeline/examples/coffee-v2/job.json`: 출력 형식 견본
- `apps/studio/works/mugi-yeo/elements.json`: 인물. `aliases`로 이름을 매칭하고, `desc_ko`는 외형 문구, `seedance_cli`가 있으면 등록된 인물
- `apps/studio/episodes/2026-11-10_mugi-yeo/storyboard.json`: 입력 견본(33컷)

## 수정·생성 가능한 파일 (이외는 수정 금지)
- 새 파일: `apps/studio/tools/pipeline/engine/plan.py`
- 새 파일: `apps/studio/tools/pipeline/tests/test_plan.py`
- 새 폴더·파일: `apps/studio/tools/pipeline/examples/mugi-yeo-s1-3/job.json` (변환 결과)
- 수정: `apps/studio/tools/pipeline/studio_run.py`. `plan` 서브커맨드 등록만 하고, 기존 함수는 바꾸지 않는다.
- 수정: `apps/studio/tools/pipeline/engine/job.py`. `validate()`에 아래 "검사 추가" 한 가지만 넣는다.
- 수정: `apps/studio/tools/pipeline/README.md`. "지금 되는 것"에 plan 한 줄을 추가한다.
- **episodes/ 아래 파일, storyboard.json, elements.json, routes/, engine/dreamina.py, contracts/는 수정 금지**

## 명령
```
python studio_run.py plan <storyboard.json 경로> <출력 폴더> --work mugi-yeo [--shots A08,C04] [--force]
```
- 출력 폴더에 `job.json`을 쓴다. 이미 파일이 있으면 `--force` 없이는 거부한다(exit 1).
- 다 쓴 뒤 그 폴더에 대해 기존 `check` 로직을 실행해 결과를 출력한다. check가 실패해도 job.json은 남긴다. exit code는 check 결과를 따른다.

## 변환 규칙
1. `kind`
   - `dialogue` → 대사 컷
   - `silent` → 무대사 컷
   - `voice_source`(N1, N2 내레이션) → **변환하지 않는다.** 경고로 "영상 아님, 건너뜀"을 출력한다.
2. 인물 매칭
   - `characters`와 `speaker` 값을 elements.json 각 인물의 `aliases`와 비교해 키(areum, jeongim, kang, jihye, han)로 바꾼다.
   - 매칭되지 않는 이름은 오류로 출력한다.
   - 사용한 인물만 `cast`에 `{키: 키}`로 넣는다.
3. 배경·시작 이미지
   - `start_image`가 있으면 `<storyboard 폴더>/src/assets/visuals/<start_image>`를 `assets`에 넣는다.
   - 키는 파일명에서 확장자를 뺀 것(예: `A08-start`)이고, `{"path": 절대경로, "sha256": 실제 해시}` 형식이다.
   - 파일이 없으면 오류.
   - 같은 이미지를 쓰는 컷이 여럿이면 asset 하나를 공유한다.
4. 길이
   - 대사 컷: `speech_sec`를 넣지 않는다(프리셋의 글자 수 추정을 쓰게). `gen_sec`도 넣지 않는다(프리셋 최소값 자동).
   - 단, storyboard의 `generation_seconds_target`이 그 최소값보다 크면 그 값을 `gen_sec`로 넣는다.
   - 무대사 컷: `generation_seconds_target`을 `gen_sec`로 넣는다. 4초 미만이면 4로 올리고 경고를 출력한다(Seedance 최소 4초).
5. `line` = `line_for_prompt` (그대로)
6. 프롬프트 (한국어, coffee-v2 견본 문체). 순서는 다음과 같다.
   ```
   {asset:<시작이미지키>} 의 장면. <등장 인물마다 "{cast:<키>} <desc_ko>"를 공백으로 연결>.
   카메라: <camera>. <action>
   [대사 컷] {cast:<화자키>} 가 한국어로 말한다: '<line_for_prompt>' 등록된 목소리로 말한다. 대사 외 임의 발화 없음.
   [무대사 컷] 아무도 말하지 않는다. 입을 편안히 다문다.
   실사 한국 드라마 톤. 모든 대사는 한국어. 화면에 글자·자막·간판 글씨 없음.
   ```
   - start_image가 없으면 첫 부분(`{asset:..} 의 장면.`)을 생략한다.
   - 대사 컷의 `line`은 프롬프트 안에 **글자 그대로** 들어가야 한다. 기존 check 규칙이 이것을 검사한다.
7. 필수 항목: `camera`, `action`이 비었으면 오류. 대사 컷은 `speaker`, `line_for_prompt`도 필수다.
8. 촬영 7대 항목 경고
   - storyboard에는 렌즈·빛·색감 필드가 없다. 따라서 컷마다 "렌즈/빛/색감 미기재" 경고를 **한 줄로 요약해서**(예: `경고 33컷: 렌즈·빛·색감 미기재`) 출력한다.
   - 이 경고는 거부 사유가 아니다.
9. job.json 머리
   - `schema: 1`, `work`, `preset: "drama"`, `set: null`
   - `note`: 원본 storyboard 경로와 변환 시각
   - 각 shot에 `source: {"storyboard_id": id, "scene": scene}`을 넣는다.

## 검사 추가 (engine/job.py `validate`)
- cast 인물이 elements.json에 있어도, 그 인물 항목에 컷의 route 이름(`seedance_cli`) 키가 없으면 오류로 처리한다.
- 오류 문구: `"{sid}: 인물 '{key}' 는 {route} Element 미등록 (E7 elements register 필요)"`
- 같은 인물이 여러 컷에 나와도 인물마다 한 번만 출력해도 된다.

## 완료 증거 (보고에 그대로 붙일 것)
1. `python -m unittest tests.test_job tests.test_plan -v` 출력. 기존 7개 + 새 테스트 모두 통과해야 한다.
   - 새 테스트는 최소 4개: 내레이션 건너뜀 / 미매칭 인물 오류 / 대사 line이 프롬프트에 포함 / 무대사 4초 미만은 4로
2. 아래 명령의 전체 출력
   ```
   python studio_run.py plan ../../episodes/2026-11-10_mugi-yeo/storyboard.json examples/mugi-yeo-s1-3 --work mugi-yeo
   ```
   - 예상 결과: kang, jihye, han 미등록 때문에 check가 **실패하는 것이 정상**이다. 거부 사유 목록이 보여야 한다.
3. `python studio_run.py check examples/coffee-v2` 출력. 여전히 통과해야 한다(회귀 없음).
4. `git -C C:/Ai_Coding status --short apps/studio` 출력. 허용 목록 밖 변경이 없어야 한다.

비고: 위 2번에서 check가 non-zero로 끝나는 것은 실패가 아니라 **예상된 결과**다. 테스트 실패나 허용 목록 밖 파일 변경이 있으면 Task 실패다.
