# 프로젝트 목적 달성을 위한 보강 로드맵

## 기준 목표

이 프로젝트의 핵심 목표는 다음 한 문장으로 정리된다.

"시나리오 PDF를 넣으면, 분석과 이미지 생성 결과가 반복 가능하고 회복 가능하며 검토 가능한 형태로 생산되어야 한다."

현재 저장소는 이 목표를 향한 핵심 기능은 갖췄다. 문제는 목표 자체보다, 그 목표를 안정적으로 반복 달성할 운영 품질이 아직 부족하다는 점이다.

## 우선순위 요약

### P0. 사실표 정합 회복

목표:

- 문서, manifest, 테스트, UI가 같은 현재 상태를 말하게 만든다.

작업:

1. step 총량과 applicability 분포를 자동 산출 가능한 표로 고정
2. refactor subset 결과와 repo 전체 결과를 문서에서 분리
3. `/analyze`와 `/steps/run-all`의 현재 정책을 문서/UX에 일치시킴
4. "완료" 문서는 아카이브와 현행 상태를 분리 표기

완료 기준:

- step 수/분포/품질 결과가 문서 간에 더 이상 어긋나지 않음

### P1. 실행 경로 수렴

목표:

- StepRunner/Catalog 중심으로 실제 런타임을 정렬한다.

작업:

1. 프런트 `Episodes`의 분석 시작도 `/steps/run-all` 기준으로 통일
2. `StepRunner`, `steps API`, read model이 `STEP_MANIFEST` 직접 참조를 줄이고 `step_catalog` 중심으로 재정렬
3. `_needs_presync`를 metadata-driven 정책으로 치환
4. deprecated API는 shim 역할만 하게 축소

완료 기준:

- 프런트에서 `/analyze` 직접 호출 0
- presync/downstream 정책이 하드코딩 튜플이 아니라 메타 또는 서비스 규칙으로 표현됨

### P2. startup / test boundary 정리

목표:

- 환경 초기화와 앱 lifecycle을 분리해 테스트와 운영을 예측 가능하게 만든다.

작업:

1. `init_db()` import-time 실행 제거
2. `@app.on_event("startup")`를 lifespan으로 전환
3. 기본 사용자 bootstrap을 명시적 초기화 단계로 분리
4. `ConfigDict` 전환 + insecure default 정책 재정비

완료 기준:

- `test_pipeline_e2e.py`의 SQLite startup coupling 제거
- deprecation warning 핵심 2종 제거

### P3. projection / sync 신뢰성 강화

목표:

- checkpoint 성공과 DB projection 실패를 운영에서 감지 가능하게 만든다.

작업:

1. mid/final sync 실패를 background job 결과와 UI에 반영
2. stale projection을 복구하는 공식 repair 경로 제공
3. `SceneStillSyncService`를 loader / normalizer / writer로 분해
4. partial 및 projection failure 정책을 사용자에게 보이는 상태로 올림

완료 기준:

- projection stale이 silent 상태로 남지 않음

### P4. 이미지 도메인 2차 분해

목표:

- 현재의 3-way split을 실제 유지보수 가능한 경계로 다듬는다.

작업:

1. `ImageService` shim 역할을 관리/조회 전용으로 축소하거나 대체
2. `SceneImageService`를 variation / validation / persistence / provenance 축으로 재분해
3. image API 호출자가 어떤 서비스가 공식 경로인지 명확히 보게 정리

완료 기준:

- 이미지 버그 원인 추적 범위가 한 파일/한 서비스로 과도하게 번지지 않음

### P5. 프런트 유지보수성 복구

목표:

- 기능은 유지한 채 정적 품질과 회귀 안전망을 세운다.

작업:

1. `SceneVariationCard`, `EpisodeStills`, `PipelineStepsPanel` 분해
2. `npm run lint` 0 기준선 확보
3. route/component code splitting
4. 최소 RTL/Vitest 테스트 도입
5. unused SSE 경로 정리 또는 실제 제품 플로우로 통합

완료 기준:

- lint green
- 프런트 smoke test lane 확보
- 대형 hotspot line 수 감소

### P6. 제품/운영 관점 보강

목표:

- "기술적으로 동작함"을 넘어 "현업이 신뢰하고 쓸 수 있음"으로 이동한다.

작업:

1. provenance / why-this-output 표시 강화
2. snapshot/restore UI 노출
3. HiTL 편집 흐름을 JSON 중심에서 작업자 중심으로 재설계
4. 다중 에피소드 연속성, 전역 canon, review/approval 흐름을 제품 백로그로 정리

완료 기준:

- 감독/작가 관점의 수정 가능성과 복구 가능성이 제품 UX로 드러남

## 권장 순서

```mermaid
flowchart LR
    P0[사실표 정합] --> P1[실행 경로 수렴]
    P1 --> P2[startup/test 경계]
    P2 --> P3[projection 신뢰성]
    P3 --> P4[이미지 도메인 2차 분해]
    P4 --> P5[프런트 유지보수성]
    P5 --> P6[제품/운영 보강]
```

이 순서를 권장하는 이유는 간단하다.

- 현재 무엇이 맞는지부터 정리하지 않으면 이후 리팩토링이 계속 엇나간다.
- 실행 경로가 둘이면 운영 이슈 재현이 어렵다.
- startup/test coupling을 먼저 끊어야 회귀를 믿고 줄일 수 있다.
- 그 다음에야 projection과 이미지 도메인, 프런트 분해가 비용 대비 효과를 낸다.

## 실제 첫 스프린트 추천 묶음

1. `Episodes`의 `/analyze` 제거
2. step/applicability/품질 결과 사실표 정리
3. `run_step`의 `_needs_presync` 메타화
4. startup bootstrap 분리
5. lint 최다 위반 파일 3개(`EpisodeStills`, `SceneVariationCard`, `ImageGalleryModal`) 우선 정리

이 다섯 개가 끝나면 저장소는 "무엇이 현재 계약이고, 어디가 아직 역사적 호환층인지"를 스스로 설명할 수 있게 된다.