Project SS - 파일 및 컴포넌트 구조 설계

본 문서는 "서사형 덱빌딩 게임 시스템 기획서" 및 **"스토리 바이블"**을 바탕으로, 기존 단일 HTML 파일을 모던 웹 프레임워크(React + Vite + Tailwind CSS + Zustand) 기반으로 마이그레이션 및 고도화하기 위한 디렉토리 및 컴포넌트 구조를 정의합니다.

📂 1. 전체 디렉토리 구조 (Directory Structure)

/src
 ├── assets/             # 이미지, 폰트, 아이콘 등 정적 파일
 ├── components/         # UI 및 도메인 컴포넌트
 │    ├── common/        # 공통 UI 요소 (버튼, 모달, 툴팁 등)
 │    ├── dashboard/     # 상단 상태창 및 파라미터 표시
 │    ├── gameplay/      # 핵심 게임 루프 (카드 스와이프, 자산 관리)
 │    └── council/       # 주간 의회 시스템 (투표, 법안, 파벌)
 ├── constants/          # 게임 내 상수 (파벌 정보, 테마 컬러, 엔딩 조건 등)
 ├── data/               # 초기 데이터 및 시나리오 (CSV/JSON 형식)
 ├── hooks/              # 커스텀 훅 (ex. useSwipe, useVoting)
 ├── store/              # 전역 상태 관리 (Zustand)
 ├── types/              # TypeScript 타입 정의 (Card, Faction, State 등)
 ├── utils/              # 헬퍼 함수 (엔트로피 계산, 전투/결과 연산 등)
 ├── App.tsx             # 루트 컴포넌트 (페이지 라우팅 및 전역 상태 주입)
 └── main.tsx            # 진입점

🧩 2. 상세 컴포넌트 구조 (Components Breakdown)

2.1 공통 UI (`/components/common`)

프리미엄한 관료주의 다크/레트로 UI를 구성하는 기본 요소들입니다.

Button.tsx: 액션 버튼 (결재, 서명 등 텍스처 효과 포함)
Modal.tsx: 미스터리 보드, 법안 확인 등을 위한 공통 팝업
ProgressBar.tsx: 게이지 바 (엔트로피, 내부 저항 등)
AlertToast.tsx: 패시브 효과 연쇄나 비상 사태를 알리는 시스템 메시지 (우측 하단/상단 노출)

2.2 대시보드 (`/components/dashboard`)

플레이어의 현재 상태(국장실 요약)를 보여줍니다.

StatusHeader.tsx: 현재 주차(Week), 일차(Day), 주간 아젠다 노출
ParameterBoard.tsx: 3대 핵심 파라미터 게이지 (내부 저항, 엔트로피, 위험 수용 계수)
ResourcePanel.tsx: 3대 토큰(예산, 인력, 정보) 및 자원 태그(재력, 무력, 감시) 현황
FactionDonut.tsx: 8대 파벌의 의회 지분율 및 우호도를 시각화하는 도넛 차트

2.3 게임플레이 (`/components/gameplay`)

일일 업무(결재 단계)를 처리하는 핵심 루프 컴포넌트입니다.

DeskView.tsx: 국장실 책상 배경 및 전체 레이아웃 래퍼
CardSwiper.tsx: 틴더 스타일의 스와이프 인터페이스 (Tinder-like Swipe)
- 좌/우 스와이프에 따른 예측 결과(예상 토큰/파라미터 증감)를 오버레이로 표시
DilemmaCard.tsx: 개별 딜레마/위기 서류. (제목, 내용, 플레이버 텍스트, 결재/반려 스탬프 이펙트)
AssetManager.tsx: 보유 중인 자산(파이프라인, 성질 변환 등 덱 압축 장치) 관리 모달

2.4 의회 시스템 (`/components/council`)

매주 5일차 종료 후 진행되는 정치 시스템 컴포넌트입니다.

CouncilPhase.tsx: 주간 의회 화면 메인 컨테이너
BillDisplay.tsx: 상정된 법안(이득 규약 vs 표적 규약) 비교 UI
VotingBoard.tsx: 13명의 임원(상임 이사 8명 + 글로벌 지부장 5명)의 예상 투표 현황 및 게이지 바
InterventionPanel.tsx: 국장의 개입 액션 (매수, 장부 조작, 내부 감사) 버튼 및 리스크 안내 패널

2.5 뷰 / 씬 (Views/Scenes)

LoadingScreen.tsx: 초기 데이터 파싱 및 게임 세팅 화면
GameScreen.tsx: 인게임 전체 메인 화면 (대시보드 + 게임플레이 결합)
EndingScreen.tsx: 멀티 엔딩 매트릭스에 따른 최종 결과 출력 (위대한 침묵, 신인류의 탄생 등)

💾 3. 전역 상태 구조 (Global State - Zustand 제안)

관리가 복잡한 게임 데이터를 효율적으로 다루기 위해 상태를 나눕니다.

interface GameState {
  // 시간/페이즈 관리
  week: number;
  day: number;
  phase: 'DAY_WORK' | 'COUNCIL' | 'ENDING';
  
  // 핵심 파라미터
  entropy: number;       // 0~100%
  internalResistance: number; // 0~100%
  riskTolerance: number;      // 0~100%
  
  // 자원
  tokens: { budget: number; personnel: number; info: number; };
  tags: { finance: number; force: number; surveillance: number; };
  
  // 덱 및 내러티브
  narrativeTags: string[];
  ideologyTags: string[];
  deck: Card[];        // 섞인 오염카드 및 이벤트 풀
  assets: Asset[];     // 덱 압축 파이프라인
  
  // 파벌 및 의회 (13명의 임원 정보 포함)
  factions: FactionState[];
  currentBills: Bill[];
}

🚀 4. 추천 기술 스택

Framework: React (컴포넌트 분리를 통한 복잡한 UI 관리)
Build Tool: Vite (빠른 HMR 및 빌드 속도)
Styling: Tailwind CSS (유틸리티 클래스로 빠른 UI 구현) + CSS Animations (스와이프 액션, 팝업 등)
State Management: Zustand (가볍고 직관적인 전역 상태 관리)
Interactions: Framer Motion 또는 react-spring (부드러운 카드 스와이프 액션 및 몰입감 있는 애니메이션)
Type Checking: TypeScript (복잡한 자원 계산과 이벤트 분기에 대한 안정성 보장)

5.5 KiB Raw Blame History

Project SS - 파일 및 컴포넌트 구조 설계

📂 1. 전체 디렉토리 구조 (Directory Structure)

🧩 2. 상세 컴포넌트 구조 (Components Breakdown)

2.1 공통 UI (/components/common)

2.2 대시보드 (/components/dashboard)

2.3 게임플레이 (/components/gameplay)

2.4 의회 시스템 (/components/council)