hushroom/.cli/tasks/0014-fsd-refactor-phase1-no-behavior-change.md

.gemini/current.md

TASK_META (수정 금지)

• TASK_TITLE: FSD 1차 구조로 리팩토링(동작 동일) — lobby/flight 시각 컴포넌트 및 로직 분리
• TASK_SLUG: fsd-refactor-phase1-no-behavior-change

작업 목표

현재 @src/app/page.tsx(Home/Lobby)와 @src/app/flight/page.tsx에 섞여있는 UI/스타필드/글린트/타이머 관련 코드를 FSD 구조로 분리하여 읽기 쉽게 만든다.

• 핵심: 동작/디자인/출력 결과는 변경하지 않는다.
• 변경은 “파일 분리 + import 정리 + 타입 분리” 중심으로 한다.

리팩토링 원칙(필수)

• 기능 추가 금지 / UI 변경 금지 / 애니메이션 변경 금지
• 기존 동작과 시각 결과를 유지(가능하면 스냅샷/수동 확인)
• 변수명/함수명은 의미가 더 명확해지면 최소한으로 개선 가능(대규모 리네이밍 금지)
• CSS 유틸리티/글로벌 스타일은 이동하더라도 동일하게 동작해야 함

목표 FSD 디렉토리(제안, Next App Router 호환)

아래 구조로 생성/이동하라:

• src/shared/

  • ui/ : 재사용 UI(버튼/칩/베일 등)
  • lib/ : 유틸(랜덤 시드, clamp, prefersReducedMotion, resize observer 등)
  • config/ : 상수/튜닝 값(별 개수 범위, speed 티어 등)

• src/features/

  • lobby-starfield/
    • ui/ : ConstellationScene, Star, GlintCross 등(로비 배경 전용)
    • model/ : 별자리 좌표/별 티어 데이터(오리온/마차부/북두칠성)
  • flight-starfield/
    • ui/ : FlightStarfieldCanvas (배경 캔버스 레이어)
    • model/ : Star 객체 타입, spawn/recycle, speed tiers, vp 설정 등
    • lib/ : 투영/렌더 루프 헬퍼(순수 함수)

• src/widgets/ (페이지에 꽂는 단위)

  • lobby-background/ : 로비 배경 위젯(장면 전체)
  • flight-background/ : flight 배경 위젯
  • flight-hud/ : flight 타이머/미션/버튼 UI 위젯(있다면)

• src/pages/ 는 App Router라 사용하지 말 것(생성 금지)

구체 작업 범위

A) Home/Lobby 분리(필수)

• src/app/page.tsx에서 로비 배경(별자리+glint) 관련 JSX/CSS 의존을 분리:
  • 새로운 위젯/피처 컴포넌트로 이동
  • page.tsx는 “레이아웃 + CTA + 배경 위젯 호출”만 남긴다
• 별자리 좌표/티어/스타 크기/opacity 등의 상수는 shared/config 또는 features/lobby-starfield/model로 이동

B) Flight 분리(필수)

• src/app/flight/page.tsx에서 스타필드 캔버스 로직을 분리:
  • rAF 루프, star state, spawn/recycle, speed tiers 등은 features/flight-starfield로 이동
  • page.tsx는 “HUD(UI) + 배경 위젯 호출”만 남긴다
• prefers-reduced-motion 처리도 shared/lib로 이동(중복 제거)

C) import 정리(필수)

• 절대경로/alias 사용 규칙이 있으면 그것에 맞추고, 없으면 통일(한 방식만)
• barrel export(index.ts)는 필요 최소로만(과도한 index 남발 금지)

D) 타입/상수 정리(권장)

• star 타입, 티어 타입, 좌표 타입 분리
• “튜닝 값”을 한 파일에 모아 관리 가능하게(예: shared/config/starfield.ts)
• 단, 값 자체는 바꾸지 말 것(동작 유지)

Non-scope

• 디자인 변경, 애니메이션 변경, 별 개수/속도 변경 금지
• 라우팅 변경 금지
• 신규 기능 추가 금지

적용 파일(예상)

• @src/app/page.tsx
• @src/app/flight/page.tsx
• 신규 생성:
  • src/features/lobby-starfield/**
  • src/features/flight-starfield/**
  • src/widgets/**
  • src/shared/lib/**, src/shared/config/**

완료 조건(AC)

• page.tsx / flight/page.tsx의 코드가 “페이지 조합” 수준으로 짧아졌다(핵심 로직 제거)
• 로비 별자리+glint는 features/widgets로 분리되었고 동작 동일
• flight 스타필드 캔버스는 features/widgets로 분리되었고 동작 동일
• 빌드/타입 에러 없이 동작한다
• 기능/디자인 변경 없이 리팩토링만 수행했다

완료 후 출력(최소)

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