# review-codex-1

## 범위

이 리뷰는 현재 저장소를 아래 자료와 직접 대조한 결과다.

- `docs/architecture/`
- `docs/architecture-refactor-final/`
- `README.md`
- `docs/product-roadmap-discussion.md`

검토 범위는 문서만이 아니라 백엔드 실행 경로, 프런트 UI/상태 관리, 테스트/품질 게이트, 그리고 프로젝트 목적 달성 가능성까지 포함한다.

## 수행 방법

실제 코드와 문서를 교차 확인했고, 아래 검증도 다시 실행했다.

- `backend/.venv/bin/python -m pytest backend/tests -q`
- `cd frontend && npm run build`
- `cd frontend && npm run lint`
- `rg --files frontend | rg '(test|spec)\.'`

또한 핵심 계약 파일을 직접 읽었다.

- `backend/app/core/step_manifest.py`
- `backend/app/core/step_catalog.py`
- `backend/app/core/step_runner.py`
- `backend/app/api/v1/episodes.py`
- `backend/app/api/v1/steps.py`
- `backend/app/main.py`
- `backend/app/core/config.py`
- `backend/app/services/image_service.py`
- `backend/app/services/reference_image_service.py`
- `backend/app/services/scene_image_service.py`
- `frontend/src/pages/EpisodeDetail.tsx`
- `frontend/src/pages/Episodes.tsx`
- `frontend/src/hooks/api/mutations/useAnalyzeEpisode.ts`
- `frontend/src/hooks/useEventSource.ts`

전수 스캔 기준 파일 수는 아래와 같다.

- `backend/app`: 175개
- `frontend/src`: 76개
- `backend/tests`: 76개
- 합계: 327개

세부 ledger는 아래 문서에 따로 남겼다.

- `07-backend-app-file-ledger.md`
- `08-frontend-src-file-ledger.md`
- `09-backend-tests-file-ledger.md`

## 현재 기준선

### 실행 결과

| 명령 | 결과 |
|---|---|
| `backend/.venv/bin/python -m pytest backend/tests -q` | `637 passed, 56 failed, 2 errors, 1 skipped` |
| `cd frontend && npm run build` | 성공, 최종 JS chunk `987.79 kB` 경고 |
| `cd frontend && npm run lint` | `77 errors, 3 warnings` |
| `rg --files frontend | rg '(test|spec)\.'` | 결과 없음 |

### Step 계약 실측

`backend/app/core/step_manifest.py` 실측 결과:

- 총 49 step
- category 분포: analysis 42 / image 5 / auxiliary 2
- applicability 분포: always 38 / on_demand 4 / disabled 4 / if_planning_doc 1 / if_set_design_enabled 1 / if_has_outlooks 1
- 기본 active 경로: 40개
- `SET_DESIGN_ENABLED=true`까지 포함한 조건부 active 경로: 41개

## 최상위 결론

1. 프로젝트 목표 자체는 유효하다. 현재 코드베이스는 여전히 "시나리오 PDF → 분석 파이프라인 → 이미지 생성 → 웹북/산출물" 방향을 실제로 수행하도록 짜여 있다.
2. 문서는 현재 상태의 정본이 아니다. `docs/architecture`와 `docs/architecture-refactor-final`은 유용한 배경 설명과 리팩토링 기록이지만, 현재 저장소의 수치·경로·품질 상태를 그대로 반영하지 않는다.
3. 리팩토링은 실제 진전이 있다. StepRunner 중심 dispatch, checkpoint sync 5-way 분해, React Query 전환, `EpisodeDetail` 축소는 코드에서 확인된다.
4. 그러나 "완료" 서술은 과장돼 있다. 공개 API는 아직 `/analyze`와 `/steps/run-all`이 공존하고, StepCatalog는 생겼지만 런타임 소비자는 여전히 `STEP_MANIFEST` 직접 참조가 남아 있다.
5. 이미지 도메인도 완전 수렴은 아니다. `reference_image_service.py`와 `scene_image_service.py`로 분리됐지만 `image_service.py`가 1,228줄 shim으로 남아 있고, API와 테스트도 여전히 이를 사용한다.
6. 품질 게이트는 green이 아니다. 백엔드 전체 pytest는 red이고, 프런트는 빌드만 통과하며 lint와 테스트 자동화는 부족하다.
7. 지금 막혀 있는 것은 기능 부족보다 운영 신뢰성이다. 문서-코드-테스트 계약 불일치, startup/test coupling, projection/presync 하드코딩, 프런트 품질 부채가 반복 가능성과 회복 가능성을 약화시킨다.

## 문서 세트 요약

| 문서 | 핵심 내용 |
|---|---|
| `01-document-integrity-review.md` | 문서와 코드가 어디서 어긋나는지 |
| `02-backend-architecture-review.md` | 실행 경로, 진실원, projection, startup 구조 |
| `03-backend-code-review.md` | 코드 핫스팟, shim/legacy, 유지보수성 문제 |
| `04-frontend-review.md` | React Query 전환 이후의 실제 강점과 프런트 부채 |
| `05-testing-and-quality-review.md` | 현재 실측 품질 상태와 실패 묶음 |
| `06-delivery-roadmap.md` | 프로젝트 목적 달성을 위한 우선순위 |
| `07-backend-app-file-ledger.md` | `backend/app` 전 파일 ledger |
| `08-frontend-src-file-ledger.md` | `frontend/src` 전 파일 ledger |
| `09-backend-tests-file-ledger.md` | `backend/tests` 전 파일 ledger |
| `10-product-goal-and-ops-review.md` | 제품 목표, HiTL, 운영/출시 관점 gap |

## 한 문장 요약

현재 저장소는 "리팩토링이 실패한 프로젝트"가 아니라 "핵심 구조 개편은 실제로 끝냈지만, 그 위를 받치는 계약 정합성과 품질 게이트가 아직 따라오지 못한 프로젝트"다.