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

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

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

```text
/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 제안)

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

```typescript
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` (복잡한 자원 계산과 이벤트 분기에 대한 안정성 보장)