kyoung5/ProjectSS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Kyoung5seo
2026-06-09 22:54:07 +09:00
parent 4d3e55a89b
commit e1310bc872
27 changed files with 2604 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/Project SS DB.xlsx
View File

Binary file not shown.

32
docs/Project SS PRD.md
View File

@@ -1,32 +0,0 @@
## 1. 프로젝트 개요
- 프로젝트명: Project SS (가제: 비밀 결사단)
- 장르: 로그라이트 권력 시뮬레이션 / 엔진 빌딩 / 정치 스릴러
- 플랫폼: 모바일 웹앱 및 하이브리드 앱 (세로 모드 전용)
- 핵심 가치 (Core Value):
1. 원하는 자원과 태그를 수집하기 위한 [능동적 딜레마 스와이프]
2. 모은 자원을 폭발시켜 미스터리를 해결하고 자산을 얻는 [엔진 빌딩]
3. 사상적 우호도에 기반하여, 필요할 때만 권력을 개입시키는 [선택적 정치 공작]
## 2. 주요 기능 요구사항 (Functional Requirements)
### 2.1. 데이터 관리 (Live DB)
- Google Sheets Sync: 사건(결재 카드), 파벌, 자산, 미스터리 등 게임 내 모든 수치와 텍스트를 구글 시트에서 Fetch하여 로드하는 구조 필수.
- 상태 관리 (State Management): 세션 내 플레이어의 4대 속성, 획득한 태그, 파벌별 우호도 수치를 실시간으로 추적 및 업데이트해야 함.
### 2.2. [메인 화면] 결재 시스템 (A vs B Swipe)
- 기능: 메인 화면 중앙의 카드를 좌/우로 드래그하여 투입할 부서(대응 방식)를 선택.
- 오버레이 피드백: 드래그 중 화면 좌우측 및 상단에 예상되는 획득 자원과 태그 아이콘을 시각적으로 미리 표시(Preview).
### 2.3. [미스터리 모달] 미스터리 보드 시스템 (Mystery Dossier)
- 조건부 팝업: 조건(엔트로피 달성, 특정 태그 N개 누적 등) 만족 시 보드(별도 UI 모달)에 새로운 미스터리 항목 동적 생성.
- 상태 이상(디버프) 처리: 미결재 상태의 미스터리가 보드에 존재할 경우, 매 턴(스와이프)마다 지정된 디버프 수치(예: 신임도 -2) 자동 차감 로직 구현.
- 해결 및 보상 처리: 플레이어가 요구되는 '빌드업 태그'와 재화를 지불하고 '해결' 버튼 클릭 시, 디버프 제거 및 지정된 '자산(Asset)'을 인벤토리에 추가.
### 2.4. [주간 의회 모달] 정치 및 우호도 시스템 (Affinity & Parliament)
- 스펙트럼 로직: 플레이어의 '성향 태그'가 변경될 때마다 8개 파벌의 우호도 상태(5단계)를 자동 재계산 및 업데이트.
- 액션 개입 (Intervention): 주간 의회 페이즈 진입 시, 특정 조건(우호도)을 만족하는 파벌을 대상으로 '정치 자본'을 지불하여 액션(이면 계약, 블랙리스트)을 트리거하는 버튼 활성화.
- 카운터 입법: 적대 파벌은 플레이어가 가장 많이 보유한 '빌드업 태그'를 파악하여, 해당 기능을 정지시키는 카운터 법안을 상정하는 타겟팅 로직 필요.
## 3. UI/UX 및 비기능 요구사항
- 뷰포트 최적화: 좁은 모바일 화면에서 카드 스와이프 영역(메인)과 스탯/로그 영역을 침범하지 않도록 dvh 기반의 레이아웃 설계.
- 조작 피드백: 미스터리 해결, 정치 액션 실행, 게임 오버 발생 시 강력한 햅틱 진동 및 사운드 효과 필수.

88
docs/Project SS 기획서.md
View File

@@ -1,88 +0,0 @@
## 코어 루프 (Core Game Loop)
게임은 다음 4개의 톱니바퀴가 반복되며 굴러가는 구조를 가집니다.
1. 사건 대응 (스와이프): 매 턴 사건 카드가 등장하며, 유저는 [어느 부서를 투입할지(A vs B)] 선택합니다. 이를 통해 재화와 태그를 획득합니다.
2. 빌드업 (미스터리 보드): 획득한 태그와 재화가 쌓이면 **[미스터리]**가 해금됩니다. 방치 시 페널티를 받으며, 재화를 소모해 해결하면 시너지를 내는 **[자산(엔진)]**을 획득합니다.
3. 정치적 반작용 (우호도 스펙트럼): 유저의 선택(성향)에 따라 파벌들이 자동적으로 우호/적대 상태로 재편성됩니다.
4. 난관 돌파 (주간 의회): 주말이 되면 적대 파벌이 유저의 엔진을 부수는 **[카운터 법안]**을 냅니다. 유저는 권력을 개입(이면 계약 등)시켜 이를 방어하고 다시 일상 업무로 돌아갑니다.
## 2. 속성 정의 (Attributes Definition)
이 게임의 모든 행동과 목표, 패배 조건은 다음 속성들에 의해 결정됩니다.
### 2.1. 4대 핵심 재화 (자원)
- 🧬 변칙 데이터 (Anomaly Data): 연구/포획 시 획득. [미스터리 해결]에 소모되는 필수 성장 재화.
- 👑 정치 자본 (Political Clout): 은폐/통제 시 획득. [의회 액션]에 소모되는 필수 통제 재화.
- ⏱️ 엔트로피 (Entropy): 종말 척도 (0~100%).
- 효과: 일정 구간마다 시민 패닉 단계 상승 (게임 내 억까 이벤트 등장 확률 증가).
- 패배 조건: 100% 도달 시 즉시 [세계 멸망 엔딩 (Game Over)].
- 🛡️ 신임도 (Trust): 대중과 기구의 지지율. (플레이어의 HP)
- 패배 조건: 0에 도달 시 즉시 [국장 숙청 엔딩 (Game Over)].
### 3.2. 2대 태그 시스템 (결재 시 이중 획득)
- 🏷️ 빌드업 태그 (군사, 과학, 정보, 오컬트, 자본): 미스터리 해금 조건이자, 보유한 자산(엔진)의 시너지 발동 조건이 되는 실질적 재료.
- 🧭 성향 태그 (지배, 순응, 은폐, 혼돈): 파벌의 우호도를 결정짓고, 최종 엔딩의 분기를 나누는 사상적 나침반.
### 3.3. 파벌 우호도 5단계 (성향 태그에 의해 자동 변경)
1. 👑 핵심 동맹: 태그 공명. 유저의 주력 빌드업 속도 가속화.
2. 🤝 우호: 주간 의회 시, 유저에게 유리한 버프 법안 자동 상정.
3. ⚖️ 중립: 아무 효과 없음. (이면 계약 액션의 타겟)
4. ⚔️ 적대: 주간 의회 시, 유저의 주력 태그를 박살 내는 카운터 법안 자동 상정.
5. 🔥 파국: 성향이 극악이거나 블랙리스트 지정 시 도달. 법안 대신 극단적 '사보타주 테러(강제 페널티)' 이벤트 발생.
## 4. UI 화면 중심 시스템 정의
이 게임의 시스템은 크게 3개의 UI 화면을 중심으로 나뉘며, 각 화면에서 할 수 있는 행동이 곧 게임의 규칙입니다.
### 4.1. [메인 집무실 화면] : 결재 및 태그 수집 시스템
유저가 가장 많은 시간을 보내는 기본 화면입니다.
- UI 구조: 중앙에 틴더 형태의 스와이프 카드. 좌/우측에 대응 부서 아이콘 노출.
- 시스템 규칙:
- 카드는 '사건'을 의미하며, 좌우 스와이프는 '투입할 부서'를 의미합니다.
- 드래그 방향에 따라 명확히 어떤 자원(데이터, 자본, 신임도 등)과 태그(빌드업, 성향)를 획득/상실할지 미리 보여줍니다. (예산 제약 없음)
- 결재 완료 즉시 상단의 4대 재화 수치와 누적 태그 현황판이 업데이트됩니다.
### 3.2. [미스터리 결재판 화면] : 퀘스트 및 엔진 빌딩 시스템
유저가 직접 진척도를 관리하고 보상을 수령하는 서브 모달 창입니다.
- UI 구조: 현재 해금된 미스터리 목록 리스트. 각 항목에 [해결 비용], [방치 페널티], [보상 자산] 명시.
- 시스템 규칙:
- 해금: 특정 빌드업 태그가 N개 모이거나, 엔트로피가 N%를 넘으면 새로운 미스터리가 리스트에 추가됩니다.
- 디버프: 리스트에 미스터리가 남아있는 동안, 메인 화면에서 결재를 1회 할 때마다 지속 페널티(예: 엔트로피 자동 +1)가 부과됩니다.
- 해결: 유저가 요구되는 '빌드업 태그'와 '변칙 데이터'를 소모해 버튼을 누르면 미스터리가 지워지며, 인벤토리에 **[자산(패시브 엔진)]**이 추가됩니다.
- 승리 조건: 세계관급 재앙인 **[종결 미스터리 3종]**을 이 화면에서 모두 해결하면, 누적된 성향에 따른 **[진엔딩]**이 출력되며 승리합니다.
### 3.3. [주간 의회 화면] : 파벌 정치 및 난관 돌파 시스템
일정 턴(예: 7턴) 경과 시 강제로 진입하는 이벤트 화면입니다.
- UI 구조:
- 상단: 현재 상정된 법안의 내용과 상정 주체(적대 파벌).
- 중단: 8개 파벌의 현재 우호도 스펙트럼 현황.
- 하단: 유저가 개입할 수 있는 2개의 '액션 버튼(이면 계약, 블랙리스트)'.
- 시스템 규칙:
- 난관 발생: 적대 파벌은 유저 인벤토리에 가장 많은 '빌드업 태그'를 무력화하는 카운터 법안을 상정합니다.
- 능동적 방어 (액션): 유저는 상정된 법안을 막기 위해 아래의 선택을 할 수 있습니다.
1. 액션 포기: 법안이 통과되어 자산이 정지되는 페널티를 그대로 수용합니다.
2. [이면 계약] 실행: 정치 자본을 지불하고 우호도 [중립] 파벌을 선택합니다. 해당 파벌이 거부권을 행사해 법안이 즉시 무효화됩니다.
3. [블랙리스트] 실행: 정치 자본 지불 없이 [적대] 파벌을 탄압합니다. 해당 파벌은 [🔥파국] 상태가 되어 테러를 준비하지만, 유저는 다음 주 동안 이 파벌의 안건을 부결시킬 때마다 대량의 신임도와 정치 자본을 보상으로 수확할 수 있습니다.
## 4. UI 텍스트 레이아웃 구조 (가이드라인)
AI 및 개발 단계를 위한 최소화된 텍스트 기반 레이아웃 구조입니다.
### [Header: 대시보드 영역]
- [🛡️ 신임도: 80%] [⏱️ 엔트로피: 45%]
- [🧬 변칙 데이터: 150] [👑 정치 자본: 30]
- 우측 상단 햄버거 메뉴: [인벤토리(자산) 및 성향 로그 보기] 버튼
### [Body: 스와이프 결재 영역 (메인)]
- (좌측 표시기): ⚔️ 작전부 투입 (군사 태그 / 신임도+ / 변칙 데이터-)
- [카드 UI]: <사건 타이틀> 및 <사건 설명 텍스트>
- (우측 표시기): 🔬 R&D부 투입 (과학 태그 / 변칙 데이터+ / 신임도-)
### [Footer: 네비게이션 영역]
- [ 📁 미스터리 결재판 (🚨 1) ] 버튼 (알림 배지 표시)
- [ 🏛️ 이번 주 의회 동향 ] 버튼
### [Modal: 주간 의회 팝업]
- [상정된 법안]: <과학 기술 통제법> (효과: 과학 자산 모두 무효화)
- [파벌 현황표]: (철의 수호당: 우호) / (순수 인간당: 적대) ...
- [개입 액션 패널]:
- [ 🤝 이면 계약 (비용: 👑 50) ] -> 터치 시 중립 파벌 목록 드롭다운
- [ 🎯 블랙리스트 지정 (무료) ] -> 터치 시 적대 파벌 목록 드롭다운
- [ ⏩ 개입 없이 법안 통과 (방관) ]

156
docs/Project SS 서사형 덱빌딩 게임 시스템 기획서.md Normal file
View File

@@ -0,0 +1,156 @@
- 개요
- 서사형 덱빌딩 게임
- 출시: 모바일&스팀
- 코어 루프
- 시스템 요약: 로그라이크 루프
1. **시작:** 무작위 사건(내러티브)과 무작위 지부장이 배치된 채 국장 취임.
2. **결재 (덱 빌딩):** 스와이프를 통해 토큰을 관리하며, 덱에 [오염 카드]를 밀어 넣거나 [자산 카드]를 챙김.
3. **위기 (드로우):** 내가 넣은 오염 카드가 튀어나와 목을 조를 때, 어떻게든 [자원 태그] 엔진과 남은 토큰으로 방어.
4. **엔딩 (결과):** 덱의 상태, 파벌 우호도, 붕괴 게이지의 조합에 따라 수십 가지의 파생 엔딩 중 하나를 수집하고 다음 회차로 루프.
- 시스템 (플레이어 행동 중심 시스템 정리)
- 게임 목표: 모든 엔딩 보기
- 기본 붕괴 엔딩
- 사임 (내부 붕괴): [내부 저항] 5단계 도달 시. (수많은 딜레마에서 조직원들을 갈아 넣고 장악력을 잃은 결과)
- 세계 멸망 (외부 붕괴): [엔트로피] 5단계 도달 시. (내러티브 태그 방치 및 오염 카드에서 세상의 타락을 방관한 결과)
- 정치적 탄핵 (윗선 붕괴): 주간 의회 단계에서 적대적 파벌 임원이 2/3(9명 이상)를 넘어 탄핵안이 상정되었으나, 방어 자원(정치적 개입)이 없어 가결될 시.
- 변주된 붕괴 엔딩
- 기본 붕괴 엔딩 + 특정 자원 태그
- 기본 붕괴 엔딩 + 특정 토큰
- 극단적 파라미터 엔딩
- 특정 파라미터를 극단적으로 비정상적인 상태로 만들었을 때 즉시 발동하는 강제 종료 엔딩 (조기 엔딩)
- 내러티브 연쇄 엔딩
- 특정 내러티브 엔딩을 순서대로 수집
- 의회 정치 엔딩 (의회의 수장이 원하는 바를 이룸)
- 탄핵 + 의회의 수장이 보유한 성향에 맞는 조건 달성
- 자원
- 토큰: 소모성 자원
- 예산 토큰
- 인력 토큰
- 정보 토큰
- 자원 태그: 누적 자원, 영구적인 1코스트 할인 효과
- 재력/자본 태그: 건물 아이콘
- 무력/조직 태그: 방패 아이콘
- 감시/언론 태그: 눈동자 아이콘
- 핵심 속성 파라미터 (명확한 수치화)
- [내부 저항 (Internal Resistance)]: (0~100%) 국장에 대한 조직 내부의 반발력.
- 1단계: ~20%
- 2단계: ~40%
- 3단계: ~60%
- 4단계: ~80%
- 5단계: ~100%
- [엔트로피 (Entropy)]: (0~100%) 세계가 미쳐가는 종말 카운트다운.
- 1단계: ~20%
- 2단계: ~40%
- 3단계: ~60%
- 4단계: ~80%
- 5단계: ~100%
- [위험 수용 계수 (Risk Tolerance)]: (0~100%) 위원회가 국장의 행보를 보고 느끼는 위기감의 척도. (높을수록 위원회가 보수적/강압적으로 변함)
- 1단계: ~20%
- 2단계: ~40%
- 3단계: ~60%
- 4단계: ~80%
- 5단계: ~100%
- [내러티브 태그]: 결재로 얻는 세계의 훼손 상태 (스택형).
- [성향 태그]: 결재로 얻는 국장의 통치 사상 (스택형).
- [임원 우호도]: 13명의 위원이 국장에게 가지는 개별 호감도 (-100 ~ +100).
- 결재 단계: 스와이프 결정
- 딜레마 선택
- 일상 딜레마: 어떤 토큰과 어떤 오염 카드를 선택할 것인가?
- 좌: 토큰 획득 + 덱오염
- 우: 토큰 획득 + 덱오염
- 위기 딜레마: 덱오염의 대가로 토큰을 얻을 것인가? 토큰을 쓰고 위기를 넘길것인가?
- 좌: 토큰 획득 + 덱오염
- 우: 토큰 소모
- 작전: 무료 획득이지만 덱오염을 감수할 것인가? 토큰을 쓰고 더 많은 자원 태그를 얻을 것인가?
- 좌: 자원 태그 획득 + 덱오염
- 우: 토큰 소모 + 더 많은 자원 태그 획득
- 극비 프로젝트: 토큰을 소모해 어떤 보상 (자원 태그 or 자산)을 받을 것인가?
- 좌: 토큰 소모 + '자원 태그 획득 or 자산 획득'
- 우: 토큰 소모 + '자원 태그 획득 or 자산 획득'
- 위로: 버리기
- 위기 강타(오염 카드 - 신화, 조직저항, 이사회의 압박)
- 좌: 토큰 차감 or 자원 태그 차감
- 우: 위험 단계 (엔트로피, 내부 저항, 위험 수용 계수) 상승
- 뉴스 이벤트
- 좌: 보유 '자산' 중 1개 제거
- 우: 위험 단계 (엔트로피, 내부 저항, 위험 수용 계수) 상승
- 공통 획득
- 내러티브 태그: 스토리 전달 + 자원 태그 스택
- 연대기 시스템 (Chronicle)
- 누적된 내러티브 태그를 터치하면, 플레이어가 지금까지 세상을 어떻게 망치고 구해왔는지 연대기 형태의 히스토리/텍스트로 확인 가능. (플레이어의 목적의식과 내러티브 몰입도 강화)
- 성향 태그: 파벌과의 우호도 변화
- 덱 오염 (토큰을 마이너스)
- 엔트로피 1~5단계: 신화 카드 추가
- 적색 보고서: 뉴스 이벤트
- 내부 저항 1~5단계: 조직 저항 카드 추가
- 위험 수용 계수 1~5단계: 이사회의 압박 카드 추가
- 덱압축: 오염카드 제거
- 자산
- 성질 변환 (Transformation): 독을 약으로 바꾸기
- 오염카드를 영구 변환
- 시한부 격리 (Quarantine): 하이 리스크 하이 리턴 압축
- 여러장의 카드를 격리하지만 조건에 따라 덱으로 복귀
- 물리적 영구 소각 (Purge): 정통 덱 압축
- 조건 없이 깔끔하게 덱의 불순물을 제거하는 가장 기본적이고 강력한 수단
- 결재권 강제 행사 (Mulligan / Skip): 회피 기동
- 덱에서 카드가 사라지지는 않지만, 뽑혔을 때 뼈아픈 페널티를 무효화하는 패시브 방어막
- 자산 슬롯 (무제한 인벤토리)
- 파이프라인 연쇄 반응
- 연쇄 노드를 구축하면 오염카드 자동처리
- 입력
- 변환
- 출력
- 주간 의회 단계: 의회의 압박
- '그림자 위원회' 임원 구성 (총 13명):
- 상임 이사회 (8명): 고정된 이념을 가짐. 국장의 '성향 태그'에 직접적으로 우호도가 변함.
- 글로벌 지부장 (5명): 수많은 현장 책임자 중 5명만 선발되어 합류(게임을 시작할때마다 변경). 이념보다 실리(자원 태그, 자산, 특정 내러티브 태그)에 따라 우호도가 변동함.
- 법안 상정 및 투표
- 법안 상정
- 동맹: 이득 규약 법안 상정 (자원 태그 플러스)
- 파국: 표적 규약 법안 상정 (자원 태그 마이너스)
- 예상 표결
- 동맹: 이득 규약에 투표 - 국장의 개입 불가
- 우호: 이득 규약에 투표
- 중립: 알 수 없음
- 적대: 표적 규약에 투표
- 파국: 표적 규약에 투표 - 국장의 개입 불가
- 국장의 개입
- 매수 액션:
- 소모 비용: [예산 토큰] 대량 소모 (또는 재력 자원 태그 스택 희생)
- ​개입 효과: '중립' 또는 '적대' 성향의 임원 1~2명을 이번 투표에 한하여 '동맹(찬성)'으로 강제 전환합니다.
- ​치명적 리스크: 돈으로 입을 막은 대가로 이사회 내부에 국장의 부패 스캔들이 돌기 시작하며 [위험 수용 계수]가 즉시 1단계(20%) 상승합니다.
- 장부 조작 액션:
- 소모 비용: [정보 토큰] 대량 소모 (또는 감시 자원 태그 스택 희생)
- ​개입 효과: 발의된 법안의 핵심 근거 서류를 위조하여 법안 상정 자체를 무효화하고 다음 주 의회로 이월(Delay)시킵니다. 시간을 벌 수 있는 유일한 수단입니다.
- ​치명적 리스크: 은폐해야 할 외부의 미스터리 관련 기밀 정보를 정치판에 흘린 대가로 [엔트로피]가 즉시 1단계(20%) 상승합니다.
- 내부 감사 액션:
- 소모 비용: [인력 토큰] 대량 소모 (또는 무력 자원 태그 스택 희생)
- ​개입 효과: 가장 강력한 '적대/파국' 임원의 비리를 무력으로 털어, 해당 임원과 그 측근들을 이번 의회에서 '기권(투표권 박탈)' 처리합니다. 탄핵 정족수를 무너뜨릴 때 유용합니다.
- ​치명적 리스크: 요원들을 사적인 정치 싸움에 갈아 넣은 결과로 현장의 불만이 폭발하여 [내부 저항]이 즉시 1단계(20%) 상승합니다.
- 투표 결과 및 법안 통과: 국장의 개입이 반영된 투표 결과 출력 및 법안 통과
- 탄핵 투표
- 예상 표결:
- 동맹: 탄핵 반대 - 국장의 개입 불가
- 우호: 탄핵 반대
- 중립: 알 수 없음
- 적대: 탄핵 찬성
- 파국: 탄핵 찬성 - 국장의 개입 불가
- 국장의 개입: 매수 액션, 장부 조작 액션, 내부 감사 액션
- 투표 결과 및 탄핵 심판: 국장의 개입이 반영된 투표 결과 출력 및 탄핵 결과 적용
- 토큰 경제 (내러티브 태그 누적치에 따라 페이즈 전환)
- 페이즈1: 기본 루프 (어떤 독을 마실 것인가)
- 토큰과 오염 카드 선택
- 주요 등장 딜레마: 일상 딜레마 + 위기 딜레마
- 페이즈2: 기회 루프 (드디어 턴이 왔다)
- 토큰 소비와 스택 보상 선택(오염 카드 해결 + 자산, 자원 태그 빌드업)
- 주요 등장 딜레마: 작전 + 극비 프로젝트 + 오염 카드
- 페이즈3: 압박 루프 (쌓아둔 모래성 무너뜨리기)
- 엔트로피, 내부 저항, 위험 수용 계수는 거의 게임오버 한계에 도달
- 오염 카드, 뉴스 속보, 표적 규약이 극에 달하는 시기로 토큰이 항상 부족
- 주요 등장 딜레마: 작전 + 극비 프로젝트 + 오염 카드
- 스토리 기반 페이징
- **작동 방식:** 플레이어가 획득한 [내러티브 태그]의 총개수에 따라 파트가 넘어갑니다.
- 태그 0~3개: 페이즈1 (사태 파악 및 은폐의 시작)
- 태그 4~7개: 페이즈2 (프로젝트 가동 및 이사회의 개입 본격화)
- 태그 8개 이상: 페이즈3 (통제 불능의 사태 및 종말의 카운트다운)

105
docs/architecture_design.md Normal file
View File

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