# TheRoad Scene Lab — 아키텍처 리팩토링 프로젝트

> 작성: 2026-04-17
> 상태: **분석 및 설계 완료 — Phase 1 실행 대기**

---

## 개요

이 폴더는 TheRoad Scene Lab 코드베이스의 **아키텍처 리팩토링 계획**을 담고 있다. 10개월간 기능 중심으로 성장하면서 누적된 구조적 결함을 식별하고, 단계적 개선 경로를 설계한 결과물이다.

## 문서 구성

| 문서 | 내용 | 분량 |
|---|---|---|
| [`00-analysis.md`](00-analysis.md) | **결함 심층 분석** — 10개 아키텍처 결함의 현상/증거/원인/연쇄영향 상세 | 길음 |
| [`01-target-design.md`](01-target-design.md) | **목표 설계** — 원칙, 레이어, 진실원 계약, 컴포넌트 책임 | 길음 |
| [`02-before-after.md`](02-before-after.md) | **Before/After 비교** — 각 컴포넌트의 현재 vs 목표 구체적 대비 | 길음 |
| [`03-roadmap.md`](03-roadmap.md) | **Phase별 실행 로드맵** — 4 Phase, 총 ~2개월 | 중간 |
| [`04-next-session-brief.md`](04-next-session-brief.md) | **다음 세션 착수 Brief** — Phase 1 첫 작업 준비 | 짧음 |

**읽는 순서**:
- 처음 읽는 사람: `04` → `00` → `01` → `02` → `03`
- 구현 시작: `04` → `03`
- 상세 확인 필요 시: `02`, `01`, `00`

---

## 핵심 결론 (TL;DR)

### 진단
- **근본 문제**: "체크포인트 파일 중심 설계로 시작해 DB를 중간에 섞은 후 진실원 계약을 정의하지 않음"
- **10개 결함** 식별, 그 중 4개 Critical, 4개 High
- 가장 시급: (1) 하드코딩 downstream 리스트, (2) 진실원 이중화, (3) `_sync_checkpoints_to_db` 722줄 거대 함수, (4) ImageService 5,281줄 거대 클래스

### 처방
- **Phase 1** (1~2일, 낮은 위험): 빠른 승리 — 이미 존재하는 인프라 활용하도록 수정
- **Phase 2** (1주): Service 레이어 분리 — `_sync` 해체 → `CheckpointSyncService`
- **Phase 3** (2주): ImageService 3분할, detail_steps DTO 전환
- **Phase 4** (2~4주): Frontend React Query, 진실원 계층화, 문서화

### 원칙
1. **DB Primary, 체크포인트 Backup** (진실원 계층화)
2. **명시적 계약** (데이터별 진실원 문서화)
3. **단방향 의존성** (API → Service → Core → Steps → Model)
4. **Step은 Pure Transformation** (DTO in/out)
5. **중앙 레지스트리** (Manifest, SettingsRegistry, ApplicabilityValidators)
6. **선언적 > 명령적** (manifest 기반 invalidation)
7. **테스트 가능성 우선**

---

## 메트릭 목표

| 지표 | 현재 | 최종 | 효과 |
|---|---|---|---|
| `image_service.py` | 5,281줄 | 0 (삭제, 3 Service로 분할) | 테스트 가능성 확보 |
| `api/v1/steps.py` | 1,518줄 | 500줄 | API 역할 명확화 |
| `_sync_checkpoints_to_db` | 722줄 한 함수 | 60줄 wrapper + Service 메서드 7개 | 테스트/재사용 |
| 하드코딩 downstream 리스트 | 3곳 | 0 | 신규 step 자동 반영 |
| `EpisodeDetail.tsx` useState | 51개 | 15개 | 유지보수성 향상 |
| 단위 테스트 가능 Service 메서드 | <10% | 90% | 회귀 방지 |
| DELETE→INSERT sync 지점 | 5곳 | 0 | CLAUDE.md 규칙 준수 |

---

## 다음 세션 시작 시

1. [`04-next-session-brief.md`](04-next-session-brief.md) 먼저 읽기
2. v0.5.3 변경사항 커밋 결정 (옵션 A 권장)
3. feature branch 생성: `git checkout -b refactor/phase-1-quick-wins`
4. E2E 스냅샷 저장
5. Phase 1 작업 순서대로 실행 (1.1 → 1.5)
6. 각 작업 후 Codex + Claude 리뷰 → 커밋

---

## 참조

- 분석 방법: 3개 에이전트 병렬 조사 (데이터 진실원 / 제어 & 의존성 / 책임 분포)
- 대상 브랜치: `shot-more` (v0.5.3)
- 관련 이전 세션: `~/.claude/projects/.../memory/project_session_20260417.md`
- 프로젝트 규칙: `/CLAUDE.md`
- 기존 아키텍처 문서: `docs/architecture/*.md`