# 다음 세션 착수 Brief — Phase 0 실행

> 이 문서는 **다음 세션 시작 시 먼저 읽는 brief**다.
> 이번 세션(2026-04-17): 분석 통합 완료. 다음 세션: Phase 0 실행.

---

## 0. 먼저 해야 할 일

### 0.1 미커밋 변경 확인 및 처리

이번 세션 + 이전 세션의 변경이 아직 `shot-more` 브랜치에 미커밋:

**v0.5.3 코드 수정 (이전 세션)**:
- Critical 4건 (`main.py` WARNING, `toggle_shot_selection` 트랜잭션, ProjectDetail 멤버 핸들러, fetchAllStillImages)
- Important 8건 + 2차 리뷰 5건

**신규 문서 (이번 세션)**:
- `docs/architecture-refactor-final/` 5개 문서 (README, 00-integrated-analysis, 01-principles-revised, 02-final-roadmap, 03-comparison, 04-next-session-brief)

**Git 상태 예상** (미변경):
```
M  CHANGELOG.md
M  backend/app/api/v1/steps.py
M  backend/app/core/pipeline_gate.py
M  backend/app/core/steps/detail_steps.py
M  backend/app/core/steps/scene_consistency_step.py
M  backend/app/main.py
M  backend/app/services/image_service.py
M  frontend/package.json
M  frontend/src/components/layout/Sidebar.tsx
M  frontend/src/components/shared/LLMConfigPanel.tsx
M  frontend/src/components/shared/PipelineStepsPanel.tsx
M  frontend/src/components/shared/SceneVariationCard.tsx
M  frontend/src/pages/EpisodeDetail.tsx
M  frontend/src/pages/Episodes.tsx
M  frontend/src/pages/ProjectDetail.tsx
M  frontend/src/pages/PromptManager.tsx
M  frontend/vite.config.ts
?? frontend/src/vite-env.d.ts
?? docs/architecture-refactor-final/  # 이번 세션
```

**커밋 전략 (권장)**:
- 커밋 1: v0.5.3 코드 수정 (CHANGELOG.md + 코드 변경 + `vite-env.d.ts`)
- 커밋 2: 아키텍처 리팩토링 문서 세트 (`docs/architecture-refactor-final/`)
- 둘 다 **Codex + Claude 병행 리뷰** (feedback_dual_code_review.md 준수)

---

### 0.2 분석 폴더 정리 결정

현재 3개 분석 폴더가 공존:
- `docs/architecture-refactor/` — Claude 초안 (6 문서, 3,730줄)
- `docs/architecture-refactor-codex/` — Codex 검토 (1 문서, 609줄)
- `docs/architecture-refactor-final/` — 통합 확정 (5 문서, 이번 세션)

**권고**: 전부 유지. 초안과 검토는 확정안의 근거 역할. 다만 `final/README.md`에 명시된 대로 **실행 기준은 final만 사용**.

---

### 0.3 Feature branch 생성

```bash
git checkout -b refactor/phase-0-contract-alignment
```

### 0.4 스냅샷 저장

E2E 테스트용 요괴전 프로젝트 1개 선택 → UI에서 스냅샷 저장 (롤백용).

---

## 1. Phase 0 작업 목록 (3~5일)

### 1.1 테스트 baseline 복구 (4시간)

**파일**: `backend/tests/test_step_manifest_v3.py`

**수정 범위**:
- `test_total_step_count` (line 9-11): 26 → 48
- `test_analysis_steps_count` (line 13-15): 20 → 41
- `test_image_steps_count` (line 17-19): 4 → 5
- `test_auxiliary_steps_count` (line 21-23): 유지 (2)
- `test_new_steps_exist` (line 25-32): 현재 active step 목록으로 갱신
- `test_scene_director_depends_on_entity_and_scene` (line 64): 현행 의존 반영
- `test_scene_detail_depends_on_all_prior` (line 70-76): **완전 재작성** — 현재 의존: `shot_dependency`, `shot_director`, `outlook_phase3`, `entity_t2i`, `shot_staging`, `set_design`, `scene_consistency`
- `test_vah_step_is_scene_director` (line 118-120): `"씬 감독 (V/A/H)"` → `"씬 감독 (물리적 존재)"`

**실행**:
```bash
cd backend && .venv/bin/python -m pytest tests/test_step_manifest_v3.py -v
```

**목표**: 121줄 테스트 파일 전부 통과. 실패 테스트 0.

---

### 1.2 `step_manifest.py` 주석 갱신 (15분)

**파일**: `backend/app/core/step_manifest.py`

**Before (line 1-5)**:
```python
"""파이프라인 Step Manifest v4 — 33단계 정의, 의존성, 설정.

이 파일이 파이프라인의 단일 진실 소스(Single Source of Truth).
v4: beat→shot 기반 파이프라인 (분석 28 + 이미지 3 + 보조 2 = 33단계).
"""
```

**After**:
```python
"""파이프라인 Step Manifest v4 — 48단계 정의, 의존성, 설정.

이 파일이 파이프라인의 단일 진실 소스(Single Source of Truth).
v4 + shot-more: beat→shot 기반 파이프라인.

구성:
  - analysis: 41단계 (active ~36, on_demand 3, disabled 2)
  - image: 5단계 (active 4 + if_has_outlooks 1)
  - auxiliary: 2단계 (on_demand)
"""
```

---

### 1.3 `docs/architecture/` 수치 갱신 (3시간)

**파일**:
- `docs/architecture/00-overview.md` (230줄)
- `docs/architecture/06-data-contracts.md` (716줄)

**주요 수정 포인트**:
- `00-overview.md:142-148` "5개 Phase 요약" 표 Active 단계 수 재측정
- `06-data-contracts.md:9` "Active 체크포인트 (34개)" → 40개로 (정확한 숫자는 측정 후)
- 양 문서에 **AnalysisService 경로 존재 명시** 추가 (Phase 4 이전까지 임시 경로)
- `06-data-contracts.md`에 step_type 개념 예시 추가

**검증**:
```bash
grep -rn "33단계\|26단계\|20단계\|34개" docs/architecture/ backend/app/
```
결과가 있으면 남은 곳 수정.

---

### 1.4 AnalysisService deprecated 선언 (1시간)

**파일**: `backend/app/api/v1/episodes.py`

**수정 위치**:
- `episodes.py:144-201` `@router.post("/{episode_id}/analyze")`
- `episodes.py:204-250` `@router.post("/{episode_id}/reanalyze-scenes")`

**변경**:
```python
@router.post("/{episode_id}/analyze", deprecated=True)  # OpenAPI deprecated
def analyze_episode(...):
    logger.warning(
        "DEPRECATED endpoint called: /episodes/%s/analyze. "
        "Use /steps/run-all?category=analysis instead. "
        "This endpoint will be removed in Phase 4 of architecture refactor.",
        episode_id,
    )
    ...
```

**검증**:
- 서버 재시작 → 로그 WARNING 출력 확인
- OpenAPI 문서에 deprecated 표시 확인 (`/docs`)
- 호출 기존처럼 동작

---

### 1.5 `baseline.md` 작성 (1시간)

**신규 파일**: `docs/architecture-refactor-final/baseline.md`

측정 항목:
```markdown
# Baseline Metrics — Phase 0 시작 시점

측정일: 2026-04-XX (다음 세션)

## 코드 크기
- `backend/app/services/image_service.py`: 5,281줄
- `backend/app/api/v1/steps.py`: 1,518줄
- `backend/app/services/analysis_service.py`: 1,137줄
- `backend/app/core/steps/detail_steps.py`: 1,021줄
- `backend/app/core/steps/image_steps.py`: 746줄
- `backend/app/core/step_manifest.py`: 598줄
- `backend/app/core/step_runner.py`: 343줄
- `frontend/src/pages/EpisodeDetail.tsx`: 1,358줄

## 함수 크기
- `_sync_checkpoints_to_db` (steps.py:768-1487): 722줄
- `_build_final_scene_prompt` (image_service.py): 388줄
- `SceneDetailStep._execute` (detail_steps.py): ~600줄

## Step 수
- `STEP_MANIFEST` 총: 48
- Active (always + if_*): 40
- on_demand: 5
- disabled: 3

## 결함 패턴 개수
- 하드코딩 downstream 위치: 4
- DELETE→INSERT 위반: 12+
- `except: pass`: 37
- API private 역의존: 2
- Image step 경계 붕괴 사례: 1 (ref → composite)

## 테스트
- `tests/test_step_manifest_v3.py`: 18개 테스트 (낡음)
- 전체 pytest: `pytest --collect-only -q | tail -5`로 확인

## Frontend
- `EpisodeDetail.tsx`: useState ~34, useEffect ~10+
- `ProjectDetail.tsx`: useState 12, useEffect 5
- `Episodes.tsx`: useState 6, useEffect 4
```

**목적**: Phase별 진행 추적 기준선. Phase 1~5 완료 시마다 재측정하여 비교.

---

## 2. Phase 0 완료 검증 체크리스트

- [ ] `pytest backend/tests/test_step_manifest_v3.py` 100% 통과
- [ ] `step_manifest.py` 주석의 "33단계" → "48단계" 수정
- [ ] `docs/architecture/00-overview.md`, `06-data-contracts.md` 수치 갱신
- [ ] `grep -rn "33단계\|26단계\|20단계\|34개"` 결과 0건
- [ ] `/episodes/{id}/analyze` 호출 시 WARNING 로그 확인
- [ ] OpenAPI `/docs`에 deprecated 표시
- [ ] `baseline.md` 작성 완료
- [ ] Codex + Claude 병행 리뷰 완료 및 수정 반영

---

## 3. 다음 단계 (Phase 1 준비)

Phase 0 완료 후:
1. `docs/architecture-refactor-final/02-final-roadmap.md` §Phase 1 읽기
2. 새 branch: `git checkout -b refactor/phase-1-step-catalog`
3. Phase 1 작업:
   - `backend/app/core/step_catalog.py` 신설 (4시간)
   - `backend/app/core/applicability.py` 신설 (3시간)
   - 하드코딩 downstream 4곳 치환 (3시간)
   - `backend/app/core/checkpoint_io.py` 공통 유틸 (2시간)
   - manifest 필드 확장 (3시간)

**예상 Phase 1 소요**: 3~5일.

---

## 4. 주의 사항

### CLAUDE.md 절대 규칙 준수
- LLM 데이터 자르지 않기
- 시나리오 고유명사 코드/프롬프트에 넣지 않기
- UPSERT 사용 (DELETE→INSERT 금지)
- 프롬프트 파일 덮어쓰기 금지
- DB/프로젝트 파일 삭제 금지
- PostgreSQL 사용

### Phase 0 특수 규칙
- **코드 수정은 최소한**으로 (테스트 갱신 + 주석 + deprecation warning 3종만)
- **기능 변경 금지** (manifest 숫자만 맞추기, 실제 step 로직 수정 X)
- **실행 가능 상태 유지** (API 엔드포인트 현 기능 그대로)

### 테스트 절차
- 서버 재시작 후 smoke test: `backend/.venv/bin/python -c "from app.main import app; print('OK')"`
- Frontend 타입체크: `cd frontend && ./node_modules/.bin/tsc -b`
- Phase 0 후 pytest 통과 필수 (이게 Phase 0의 핵심 산출물)
- E2E 전 스냅샷 저장 (롤백용)

---

## 5. 결정 보류 항목 (Phase 1 착수 시 결정)

1. **`resume_sensitive` 플래그의 적용 대상** — `scene_camera_flow`, `scene_consistency`, `shot_staging` 셋 확정 + 추가 검토 필요한 것 있는지
2. **React Query 도입 시기** — Phase 5 전에 시범 페이지 있을지
3. **outlook 테이블 분리** — Phase 4 이후 독립 프로젝트로 평가 시점
4. **shot_extract 재설계 (이월)** — 리팩토링과 독립이라 Phase 사이에 삽입 가능 여부
5. **scene_image_pipeline의 sub_steps 처리** — 7개 sub_step이 manifest에 진입할 필요 있는지

---

## 6. 긴급 시 롤백

리팩토링 중 문제 발생:
1. `git checkout main` — 안정 버전으로
2. 또는 `git reset --hard <commit>` (신중히)
3. DB 스냅샷 복원 (해당 시)
4. 체크포인트 스냅샷 복원 (UI에서)

CLAUDE.md "destructive 명령 피하고 근본원인 수정 우선" 원칙 준수.

---

## 7. 메모리 파일 업데이트 (다음 세션 마지막에)

이번 세션 종료 전 `~/.claude/.../memory/project_architecture_refactor.md` 업데이트:
```
- docs/architecture-refactor-final/ 폴더 언급
- Phase 0 → 5로 확장, 약 3개월
- 공식 경로: StepRunner로 결정
```

`MEMORY.md` index에 추가 (선택):
```
- [project_architecture_refactor_final.md](...) - 최종 확정안 (docs/architecture-refactor-final/)
```

---

## 8. 관련 문서 지도

| 파일 | 용도 | 언제 읽음 |
|---|---|---|
| `README.md` | 인덱스 + 요약 | 세션 시작 |
| `00-integrated-analysis.md` | 13개 결함 상세 | 리팩토링 근거 확인 |
| `01-principles-revised.md` | 9원칙 상세 | 설계 의문 발생 시 |
| `02-final-roadmap.md` | Phase 0~5 상세 | **구현 중 상시** |
| `03-comparison.md` | 초안 ↔ Codex ↔ 최종 | 왜 이렇게 했는지 확인 |
| `04-next-session-brief.md` (본 문서) | 다음 세션 착수 | 세션 시작 |
| `baseline.md` (Phase 0 생성) | 지표 추적 | 각 Phase 완료 시 |

---

## 9. Phase 0 ~ 5 전체 한눈에

```
[Phase 0: 3~5일]  계약 정리 → 테스트 복구, 문서 정합, AnalysisService deprecated
   ↓
[Phase 1: 3~5일]  Step Catalog → applicability validator, 하드코딩 제거, atomic util
   ↓
[Phase 2: 1~2주]  Service 레이어 → _sync 5-way 분해, ShotSelection/Snapshot Service
   ↓
[Phase 3: 2~3주]  Image 도메인 → step 경계 재정의 + 3 Service + DTO
   ↓                                                    ↓
[Phase 4: 1~2주]  Legacy convergence → AnalysisService 제거
   ↓
[Phase 5: 2~4주]  Frontend → React Query + EpisodeDetail 분할 + except: pass

총 ~3개월
```

Phase 3/4는 독립 가능 — 병렬 진행 시 1주 단축 가능.