# 다음 세션 착수 Brief — 아키텍처 리팩토링 시작

> 이 문서는 **다음 세션 시작 시 먼저 읽을 요약**이다. 이번 세션(2026-04-17)에 분석 완료, 설계 완료. 다음 세션은 Phase 1 실행.

---

## 이전 세션에서 결정된 것

### 1. 현재 아키텍처의 10개 결함 식별
`00-analysis.md` 참조. 요약:
- **Critical**: 진실원 이중화(#2.1), `_sync_checkpoints_to_db` 722줄(#2.2), 하드코딩 downstream(#3.1), ImageService 5,281줄(#4.1)
- **High**: Applicability 런타임 미검증(#3.2), run-all 재시도(#3.3), detail_steps closure(#4.2), API 책임 오염(#4.3)
- **Medium**: 체크포인트 원자성(#2.3), Legacy 관리(#3.4), 설정 분산(#4.4), Frontend 상태(#4.5), 에러 처리(#4.6)

### 2. 목표 아키텍처 설계 완료
`01-target-design.md` 참조. 핵심:
- **진실원 계층화**: DB Primary + 체크포인트 Backup
- **단방향 레이어**: API → Service → Core → Steps → Model → DB
- **중앙 레지스트리**: Manifest (의존성), SettingsRegistry (설정), ApplicabilityValidators (조건부 applicability)
- **Service 분할**: `CheckpointSyncService`, `ShotSelectionService`, `SnapshotService`, `ReferenceImageService`, `SceneImageService`, `PromptService`

### 3. 실행 로드맵 (4 Phase, 약 2개월)
`03-roadmap.md` 참조.
- **Phase 1** (1~2일): 빠른 승리 — 하드코딩 제거, Validator 추가, 원자 쓰기 유틸화
- **Phase 2** (1주): Service 레이어 — `_sync` 분해
- **Phase 3** (2주): ImageService 분할 + DTO
- **Phase 4** (2~4주): Frontend React Query + 진실원 계층화

---

## 다음 세션 첫 작업: Phase 1 착수

### 작업 전 준비
1. 브랜치 생성: `git checkout -b refactor/phase-1-quick-wins`
2. 이번 세션 commit 확인 (v0.5.3 + 리뷰 수정 아직 미커밋 — 우선 커밋 결정 필요)
3. E2E 테스트 대상 프로젝트 1개 선택 (요괴전 중 하나 — PID 확인)
4. 스냅샷 저장 (롤백용)

### Phase 1 작업 목록 (순서대로)

#### 1.1 하드코딩 downstream 제거 (2시간)
**파일**: `backend/app/api/v1/steps.py`
```python
# Before (line 356-358)
downstream = ["scene_camera_flow", "shot_staging", ...]

# After
from app.core.step_manifest import get_all_downstream_recursive
downstream = get_all_downstream_recursive("shot_selection")
```
+ `_resume_sensitive` 리스트 (line 383)도 manifest 기반으로 전환. 
  - 방안 A: manifest에 `"supports_resume": True` 필드 추가 후 필터링
  - 방안 B: 휴리스틱 (downstream 중 체크포인트 파일이 있는 step)

#### 1.2 Applicability Validator 레지스트리 (3시간)
**신규**: `backend/app/core/applicability.py`
**수정**: `backend/app/core/step_runner.py` — `check_applicability` 교체
**manifest**: `set_design.applicability`를 `"always"` → `"if_set_design_enabled"` 변경

#### 1.3 체크포인트 원자 쓰기 유틸 (1시간)
**신규**: `backend/app/core/checkpoint_io.py` — `atomic_write_json`, `read_json_safe`
**수정**: `toggle_shot_selection` 로컬 `_atomic_write_json` 제거, 공통 유틸 사용

#### 1.4 Step lifecycle 필드 (2시간)
**수정**: `backend/app/core/step_manifest.py` — 모든 step에 `lifecycle` 필드 추가
**이동**: `backend/app/core/steps/analysis_steps_legacy.py` → `legacy/` 디렉토리
**신규 유틸**: `is_active(step_id)`, `get_active_steps()`

#### 1.5 번역 실패 시 warning 전파 (2시간)
**수정**: `backend/app/services/image_service.py::_build_final_scene_prompt`
- 번역 실패 + 한국어 잔존 시 반환값에 warning 포함
- 상위 호출자가 API 응답의 `warnings`로 전파

**총 소요**: 약 10시간 (1.5일).

---

## 각 작업의 검증 체크리스트

### 1.1 하드코딩 downstream 제거
- [ ] `get_all_downstream_recursive("shot_selection")` 결과가 기존 하드코딩 리스트를 포함하는지 (grep으로 비교)
- [ ] 신규 step (`shot_dependency_t2i`, `character_state_variant`) 포함 확인
- [ ] E2E: shot 토글 후 모든 기대 step이 stale 표시

### 1.2 Validator 레지스트리
- [ ] 기존 서브클래스 오버라이드한 step 목록 확인 + Validator로 이동 가능성 판단
- [ ] Unknown rule → `ValueError` 발생 (deliberate typo로 테스트)
- [ ] `planning_doc_analysis`가 기획서 없는 프로젝트에서 skip

### 1.3 원자 쓰기 유틸
- [ ] `toggle_shot_selection` 정상 작동
- [ ] `step_runner.save_checkpoint`도 동일 유틸 사용하도록 리팩토링 (선택)

### 1.4 Lifecycle 필드
- [ ] `is_active("shot_cinematography")` → False
- [ ] 서버 재시작 후 import 오류 없음 (legacy 파일 이동 후)

### 1.5 번역 warning
- [ ] 번역 mock 실패 시 응답에 `translation_failed` warning 포함
- [ ] 기존 시나리오에서는 warning 없음 (정상 번역 시)

---

## 주의 사항 (이전 세션 교훈)

### 커밋 전 필수
- **Codex + Claude 병행 리뷰** (`feedback_dual_code_review.md`)
- 코드리뷰 발견 사항 모두 수정 후 커밋

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

### 테스트 절차
- 서버 재시작 후 smoke test: `backend/.venv/bin/python -c "from app.main import app; print('OK')"`
- Frontend 타입체크: `cd frontend && ./node_modules/.bin/tsc -b`
- E2E 전 스냅샷 저장 (롤백용)
- 단계별 실행, run-all 최소화

---

## 이번 세션 (2026-04-17) 미커밋 변경

다음 세션 시작 시 먼저 확인:

### v0.5.3 수정 (이번 세션 일)
1. Critical 4건:
   - `main.py` startup WARNING
   - `toggle_shot_selection` 트랜잭션 순서
   - `ProjectDetail.tsx` 멤버 핸들러
   - `EpisodeDetail.tsx fetchAllStillImages`
2. Important 8건:
   - Sidebar 버전 자동화
   - `alert()` → `addToast` 6건
   - `scene_consistency` selected_map 방어
   - `detail_steps` applies_to_shots 캐스팅
   - `entity_episode_link` UPSERT 전환
   - `restore_snapshot` 실제 status 복원
   - `pipeline_gate` N+1 제거
   - `image_service` 번역 실패 로그
3. 2차 리뷰 반영 5건:
   - `entity_episode_link` outlook 보존
   - `restore_snapshot` whitelist 확장
   - 멤버 핸들러 throw 제거
   - `toggle_shot_selection` warnings 응답
   - Frontend toggle race 가드 (`togglingShots`, `handleToggleShot`, `isToggling`)

### Git 상태 (세션 종료 시점 예상)
```
On branch shot-more
Modified:
  CHANGELOG.md
  backend/app/api/v1/steps.py
  backend/app/core/pipeline_gate.py
  backend/app/core/steps/detail_steps.py
  backend/app/core/steps/scene_consistency_step.py
  backend/app/main.py
  backend/app/services/image_service.py
  frontend/package.json
  frontend/src/components/layout/Sidebar.tsx
  frontend/src/components/shared/LLMConfigPanel.tsx
  frontend/src/components/shared/PipelineStepsPanel.tsx
  frontend/src/components/shared/SceneVariationCard.tsx
  frontend/src/pages/EpisodeDetail.tsx
  frontend/src/pages/Episodes.tsx
  frontend/src/pages/ProjectDetail.tsx
  frontend/src/pages/PromptManager.tsx
  frontend/vite.config.ts

New:
  frontend/src/vite-env.d.ts
  docs/architecture-refactor/ (이 전체 문서 세트)
```

### 커밋 전략 선택지

**옵션 A**: v0.5.3을 먼저 커밋, 그 다음 Phase 1 시작.
- 장점: 코드 리뷰 수정분이 명확히 분리됨.
- 단점: Phase 1 시작 지연.

**옵션 B**: v0.5.3 + Phase 1을 한 번에 커밋.
- 장점: 빠른 진행.
- 단점: 커밋 범위 커짐.

**권장**: 옵션 A. 이번 세션 변경사항은 이미 리뷰 완료 → 바로 커밋하고, Phase 1은 별도 feature branch.

---

## 분석/설계 문서 지도

| 파일 | 용도 | 읽는 시점 |
|---|---|---|
| `00-analysis.md` | 10개 결함 상세 분석 | 리팩토링 필요성 재확인 시 |
| `01-target-design.md` | 목표 아키텍처 설계 | 구현 중 "어떻게 생겼어야 하지?" 의문 시 |
| `02-before-after.md` | Before/After 구체적 비교 | 특정 컴포넌트 변경 전 참조 |
| `03-roadmap.md` | Phase별 실행 계획 | 작업 순서 / 일정 파악 시 |
| `04-next-session-brief.md` (이 문서) | 다음 세션 첫 작업 | 세션 시작 시 |

---

## 결정 보류 사항

다음 세션에서 확인 필요:

1. **outlook 테이블 분리 여부** — `01-target-design.md` 8.3에 "Phase 4에서 재검토"로 기록. 대규모 마이그레이션이라 따로 평가.

2. **React Query 도입 타이밍** — Phase 4에 배치했지만 Phase 2 중 한 페이지 시범 적용 가능. 학습 비용 대비 이익 판단.

3. **`_resume_sensitive` 자동화 방법** — manifest `supports_resume` 플래그 vs 휴리스틱. Phase 1 착수 시 결정.

4. **Phase 1의 "번역 warning 전파" 작업 (1.5)** — 진실원 이중화 해소(Phase 4)와 일부 겹침. Phase 1에서는 최소 변경만(logger level 조정), Phase 4에서 완전 해결.

5. **shot_extract 재설계 (이월)** — 이전 세션부터 이월된 "한 샷=한 찰나" 원칙 강화 작업. 리팩토링과 독립이라 Phase 1~2 중 별도 세션 가능.

---

## 긴급 시 롤백

리팩토링 중 문제 발생 시:
1. `git checkout main` — main 브랜치로 복귀 (현재 v0.5.2)
2. 또는 `git reset --hard <commit>` — 특정 커밋으로 (신중히)
3. DB 스냅샷 복원 (해당하는 경우)
4. 체크포인트 스냅샷 복원 (UI에서)

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

---

## 관련 메모리 파일 업데이트 필요 (다음 세션에서)

MEMORY.md에 추가될 항목:
```
- [project_architecture_refactor_plan.md](project_architecture_refactor_plan.md) - 아키텍처 리팩토링 4-Phase 계획 (docs/architecture-refactor/ 참조)
```

이 메모리 파일은 다음 세션 첫 단계에서 사용자 확인 후 저장.

---

## Phase 1 완료 시 예상 효과

- **invalidation 신뢰도**: 신규 step 추가 시 자동 반영.
- **applicability 신뢰도**: `if_*` 규칙이 실제로 런타임 검증.
- **체크포인트 원자성**: 모든 체크포인트 쓰기가 원자적.
- **legacy 가시성**: UI에서 deprecated step 표시 가능.
- **번역 실패 UX**: 사용자가 원인 인지 가능.

**소요**: 약 1.5일.
**리스크**: 낮음 (기존 동작 유지 중심).