hushroom/.cli/tasks/0015-fsd-settle-phase2-cleanup-and-public-api.md

.gemini/current.md

TASK_META (수정 금지)

• TASK_TITLE: FSD 정착 2차 — 잔재 import 제거/중복 정리 + widgets public API 고정 + 분리작업 준비
• TASK_SLUG: fsd-settle-phase2-cleanup-and-public-api

작업 목표

1차 FSD 이관 이후 남아있는 “잔재(import/중복/브릿지)”를 정리하고, 페이지(app/*)가 widgets의 public API만 import 하도록 고정해 향후 기능/스타필드/UI 분리 작업을 안전하게 진행할 수 있는 상태로 만든다.

중요: 동작/디자인 변경 없이 리팩토링(정리/분리)만 수행한다.

---

0) 작업 순서(반드시 이 순서로)

1. 잔재 import 탐지 → 2) 잔재 제거/이관 → 3) 중복 소거(단일 소스) →
2. widgets public API(index.ts) 구축 → 5) 페이지 import를 widgets로 통일 →
3. 브릿지 파일 제거 → 7) 빌드 확인

---

1) 잔재(import) 탐지 및 제거(필수)

탐지(필수)

레포에서 아래 경로를 직접 참조하는 import가 남아있는지 모두 확인하고 제거한다:

• components/*
• lib/*
• types/* (가능하면)
• features/*/ui/* 를 page가 직접 import 하는 케이스(페이지는 widgets만)

탐지는 CLI에서 ripgrep을 사용하거나(권장), 코드 검색으로 동일하게 수행한다.

정리 규칙(필수)

• components/*를 직접 import하는 코드가 있다면:
  • 해당 컴포넌트의 “정식 위치”(shared/ui, features//ui, widgets//ui)로 import를 바꾼다.
• lib/* import가 남아있다면:
  • shared/lib/** 또는 shared/config/** 또는 entities/**/model/features/**/model로 교체한다.
• types/* import가 남아있다면:
  • 가능 범위에서 shared/types/** 또는 도메인 model로 이동/교체한다.
  • 단, 타입 대수술은 금지(경로 정리 중심).

---

2) 중복 구현 정리(필수)

대상(필수)

특히 아래 성격의 파일은 중복이 생기기 쉬우므로 “단일 소스”로 통일한다:

• LobbyBackground 계열
• FlightBackground 계열
• Star/Glint/Constellation 컴포넌트
• Starfield Canvas/Loop 관련 유틸

규칙(필수)

• 동일 기능이 두 위치에 존재하면, 하나를 “정식 소스”로 결정하고 나머지는 제거한다.
• 정식 소스 위치 우선순위:
  1. widgets/** (페이지에 꽂는 단위)
  2. features/** (기능 단위)
  3. shared/** (완전 범용)
• 제거가 리스크면 임시 re-export 브릿지를 1회만 허용하되, 이번 작업에서 최종적으로는 브릿지를 제거하는 방향을 우선한다.

---

3) Widgets Public API 고정(핵심)

목표(필수)

페이지(app/*)는 앞으로 아래만 import 한다:

• widgets/** 의 index.ts (public API)

수행(필수)

• 각 widget 폴더에 index.ts를 만들고 public export를 한 곳으로 모은다. 예:
  • src/widgets/lobby-background/index.ts
  • src/widgets/flight-background/index.ts
  • src/widgets/flight-hud/index.ts
  • src/widgets/lobby-routes/index.ts
• page에서 widgets/**/ui/* 또는 features/**/ui/* 를 직접 import하는 코드를 전부 제거하고, widgets/**의 index.ts에서만 가져오게 수정한다.

금지(필수)

• page에서 features/entities/shared를 직접 import하지 말 것(예외: 정말 공용 상수 1~2개 정도만, 가능하면 위젯이 먹도록 감춘다).
• widget 내부에서만 features/entities/shared를 조합한다.

---

4) 페이지(app/*) 정리(필수)

목표(필수)

• src/app/page.tsx 및 src/app/flight/page.tsx는 “조합자” 역할만 한다:
  • 위젯 렌더링 + 라우팅/레이아웃
• 별자리/스타필드/글린트/타이머 코어 로직은 페이지에서 제거되어야 한다(이미 분리되어 있다면 유지).

수행(필수)

• app/page.tsx는 LobbyBackground(widget)와 라우트/CTA만 남긴다.
• app/flight/page.tsx는 FlightBackground + FlightHUD(widget)만 남긴다.

---

5) 브릿지 파일 제거(필수)

목표

• 1차 이관에서 남겨둔 임시 re-export/브릿지 파일이 있다면 제거한다.
• components/ 또는 lib/ 폴더가 남아있다면:
  • 비어있게 만들고 제거하거나,
  • 최소한 “더 이상 import되지 않음” 상태로 만든다(최종적으로 삭제 권장).

---

6) 빌드/런타임 확인(필수)

• 타입 체크/빌드가 깨지지 않아야 한다.
• Home 로비 배경(별자리+glint) 정상 표시
• Flight 배경 스타필드 정상 표시
• 주요 라우트 이동(/, /boarding, /flight, /debrief, /log, /settings) 깨짐 없음

---

Non-scope

• 기능 추가/변경 금지
• UI/애니메이션/스타필드 튜닝 금지(이번 작업은 구조 고정만)
• 라우트/디자인 변경 금지
• 스타일 값 조정 금지

---

적용 범위(예상)

• src/app/page.tsx
• src/app/flight/page.tsx
• src/widgets/** (index.ts 생성/수정)
• src/features/** (중복 제거/정식 소스 확정)
• src/shared/** (유틸/설정 경로 정리)
• 잔재 폴더(components, lib, types) 정리/삭제

---

완료 조건(AC)

• components/*, lib/*, types/* 직접 import가 레포에서 0이거나(최소화), 남아있다면 정당한 사유가 주석으로 명시됨
• 페이지(app/*)는 widgets public API만 import한다(직접 features/ui 참조 없음)
• 각 widget은 index.ts(public API)를 가진다
• 중복 구현이 제거되어 단일 소스가 확정되었다
• 빌드/타입 에러 없이 동작이 유지된다

---

완료 후 출력(최소)

• 변경/생성/삭제된 파일 경로 목록
• AC 체크(OK/NO)