Code Review and Cleanup Plan

개요

프로젝트 전체 코드를 리뷰하여 다음 문제를 해결:

한 파일에 너무 많은 코드가 있는 경우 (250줄 규칙 위반)
같은 기능의 코드가 중복되어 있는 경우
사용하지 않는 예전 버전의 불필요한 코드

🔍 발견된 문제점

1. 파일 크기 문제 (250줄 규칙 위반)

TypeScript 파일 (250줄 이상)

파일	라인 수	상태	조치 필요
`src/services/research.service.refactored.ts`	593줄	❌ 미사용	삭제 권장
`src/services/seed.service.refactored.ts`	539줄	❌ 미사용	삭제 권장
`src/lib/kv.ts`	502줄	✅ 사용 중	분리 필요
`src/lib/d1.ts`	441줄	✅ 사용 중	분리 필요
`src/lib/queue/domain-queue-handlers.ts`	437줄	✅ 사용 중	분리 필요
`src/lib/queue/queue-handlers.ts`	412줄	✅ 사용 중	분리 필요
`src/lib/queue.ts`	405줄	✅ 사용 중	분리 필요
`src/lib/liveness.ts`	399줄	✅ 사용 중	분리 필요
`src/services/seed.service.ts`	398줄	✅ 사용 중	분리 필요
`src/services/research.service.ts`	390줄	✅ 사용 중	분리 필요
`src/schemas/seed.ts`	381줄	✅ 사용 중	분리 필요
`src/lib/path.ts`	381줄	✅ 사용 중	분리 필요
`src/services/storage.service.ts`	340줄	✅ 사용 중	분리 필요
`src/services/metadata.service.ts`	320줄	✅ 사용 중	분리 필요
`src/lib/checkpoint.ts`	306줄	✅ 사용 중	분리 필요
`src/infra/cloudflare/github/githubStorageAdapter.ts`	295줄	✅ 사용 중	분리 필요
`src/routes/seeds.ts`	293줄	✅ 사용 중	분리 필요

Shell 스크립트 (250줄 이상)

파일	라인 수	상태	조치 필요
`.github/scripts/lib/cloudflare-resources.sh`	531줄	✅ 사용 중	분리 필요
`.github/scripts/steps/deploy.sh`	308줄	✅ 사용 중	분리 필요
`.github/scripts/lib/wrangler-config.sh`	303줄	✅ 사용 중	분리 필요

2. 중복 코드 문제

2.1 Service 파일 중복

문제: .refactored.ts 파일들이 존재하지만 실제로는 사용되지 않음

파일	라인 수	실제 사용 여부	조치
`src/services/research.service.refactored.ts`	593줄	❌ 미사용	삭제
`src/services/seed.service.refactored.ts`	539줄	❌ 미사용	삭제
`src/services/research.service.ts`	390줄	✅ 사용 중	유지
`src/services/seed.service.ts`	398줄	✅ 사용 중	유지

증거:

src/services/index.ts에서 .refactored.ts 파일을 import하지 않음
실제 사용되는 파일은 .service.ts (refactored 없음)

조치: .refactored.ts 파일 삭제

2.2 Re-export 파일 중복

문제: lib/kv.ts, lib/d1.ts, lib/queue.ts, lib/liveness.ts, lib/path.ts가 하위 디렉토리의 index.ts를 re-export하는 구조

현재 구조:

src/lib/
├── kv.ts (502줄) ← re-export 파일
├── kv/
│   └── index.ts (실제 구현)
├── d1.ts (441줄) ← re-export 파일
├── d1/
│   └── index.ts (실제 구현)
├── queue.ts (405줄) ← re-export 파일
├── queue/
│   └── index.ts (실제 구현)
├── liveness.ts (399줄) ← re-export 파일
├── liveness/
│   └── index.ts (실제 구현)
├── path.ts (381줄) ← re-export 파일
└── path/
    └── index.ts (실제 구현)

문제점:

Re-export 파일이 300-500줄에 달함 (단순 re-export가 아님)
실제 구현이 하위 디렉토리에 있음
중복된 export 구조

조치: Re-export 파일을 제거하고 하위 디렉토리의 index.ts를 직접 사용하도록 변경

2.3 Compatibility Layer

파일: src/lib/d1/task-state-compat.ts (38줄)

상태: ✅ 사용 중 (src/lib/d1/index.ts에서 export)

조치: 유지 (하위 호환성을 위해 필요)

3. 사용하지 않는 코드

3.1 Refactored 파일들

src/services/research.service.refactored.ts (593줄) - 삭제 권장
src/services/seed.service.refactored.ts (539줄) - 삭제 권장

3.2 테스트 파일

참고: 테스트 파일은 유지 (.test.ts 파일들)

🎯 개선 계획

Phase 1: 즉시 삭제 (Low Risk)

1.1 미사용 Refactored 파일 삭제

대상:

src/services/research.service.refactored.ts (593줄)
src/services/seed.service.refactored.ts (539줄)

조치:

파일 삭제
Git에서 제거

예상 효과: 1,132줄 제거

Phase 2: Re-export 파일 정리 (Medium Risk)

2.1 Re-export 파일 분석 및 정리

대상:

src/lib/kv.ts (502줄)
src/lib/d1.ts (441줄)
src/lib/queue.ts (405줄)
src/lib/liveness.ts (399줄)
src/lib/path.ts (381줄)

조치:

각 파일의 내용 분석
실제 구현이 하위 디렉토리에 있는지 확인
Re-export만 하는 경우: 파일 삭제, import 경로 변경
추가 로직이 있는 경우: 하위 디렉토리로 이동

예상 효과: 2,128줄 정리

Phase 3: 대형 파일 분리 (High Risk, 단계적 진행)

3.1 Service 파일 분리

대상:

src/services/research.service.ts (390줄)
src/services/seed.service.ts (398줄)

조치:

이미 research/, seed/ 하위 디렉토리에 handler 파일들이 있음
추가 분리 검토 필요

3.2 Library 파일 분리

대상:

src/lib/queue/domain-queue-handlers.ts (437줄)
src/lib/queue/queue-handlers.ts (412줄)
src/schemas/seed.ts (381줄)
src/services/storage.service.ts (340줄)
src/services/metadata.service.ts (320줄)
src/lib/checkpoint.ts (306줄)
src/infra/cloudflare/github/githubStorageAdapter.ts (295줄)
src/routes/seeds.ts (293줄)

조치: 각 파일을 기능별로 분리 (250줄 이하로)

3.3 Shell 스크립트 분리

대상:

.github/scripts/lib/cloudflare-resources.sh (531줄)
.github/scripts/steps/deploy.sh (308줄)
.github/scripts/lib/wrangler-config.sh (303줄)

조치: 함수별로 분리하여 모듈화

📊 우선순위별 작업 계획

🔴 Critical (즉시 실행)

미사용 Refactored 파일 삭제
- 난이도: 낮음
- 위험도: 낮음
- 예상 시간: 10분
- 효과: 1,132줄 제거

🟡 High (단기간 내 실행)

Re-export 파일 정리
- 난이도: 중간
- 위험도: 중간
- 예상 시간: 2-3시간
- 효과: 2,128줄 정리
- 주의: Import 경로 변경 필요

🟢 Medium (중기 계획)

대형 파일 분리 (TypeScript)
- 난이도: 높음
- 위험도: 높음
- 예상 시간: 1-2일
- 효과: 코드 가독성 향상
- 주의: 단계적 진행, 테스트 필수
대형 파일 분리 (Shell Script)
- 난이도: 중간
- 위험도: 중간
- 예상 시간: 4-6시간
- 효과: 스크립트 유지보수성 향상

🔍 상세 분석

Re-export 파일 상세 분석 필요

각 re-export 파일의 내용을 확인하여:

단순 re-export인지
추가 로직이 있는지
하위 디렉토리와의 관계

분석 대상:

src/lib/kv.ts vs src/lib/kv/index.ts
src/lib/d1.ts vs src/lib/d1/index.ts
src/lib/queue.ts vs src/lib/queue/index.ts
src/lib/liveness.ts vs src/lib/liveness/index.ts
src/lib/path.ts vs src/lib/path/index.ts

✅ 검증 계획

삭제 전 검증

Refactored 파일 삭제 전:
- Git에서 검색하여 참조 확인
- Import 문 검색
- 테스트 파일에서 사용 여부 확인
Re-export 파일 정리 전:
- 모든 import 경로 확인
- 실제 사용 여부 확인
- 하위 디렉토리와의 관계 확인

변경 후 검증

빌드 테스트:
- TypeScript 컴파일 확인
- Linter 오류 확인
기능 테스트:
- 단위 테스트 실행
- 통합 테스트 실행
CI/CD 테스트:
- GitHub Actions 실행
- 배포 테스트

📝 작업 체크리스트

Phase 1: 즉시 삭제

src/services/research.service.refactored.ts 삭제
src/services/seed.service.refactored.ts 삭제
Git commit 및 push

Phase 2: Re-export 파일 정리

Phase 3: 대형 파일 분리

각 파일의 기능 분석
분리 계획 수립
단계적 분리 실행
테스트 실행

🎯 예상 효과

코드 라인 수 감소

Phase	제거/정리 라인 수	비고
Phase 1	~1,132줄	미사용 파일 삭제
Phase 2	~2,128줄	Re-export 파일 정리
Phase 3	~3,000+줄	대형 파일 분리 (추정)
총계	~6,260줄

코드 품질 향상

✅ 파일 크기 규칙 준수 (250줄 이하)
✅ 중복 코드 제거
✅ 명확한 모듈 구조
✅ 유지보수성 향상

기획 완료 일시: 2026-01-28
우선순위: Critical → High → Medium
예상 총 작업 시간: 2-3일