서사형 덱빌딩 게임 시스템으로 리뉴얼

2026-06-09 22:54:07 +09:00
parent 4d3e55a89b
commit e1310bc872
27 changed files with 2604 additions and 13 deletions
--- a/docs/architecture_design.md
+++ b/docs/architecture_design.md
@@ -0,0 +1,105 @@
+# 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` (복잡한 자원 계산과 이벤트 분기에 대한 안정성 보장)