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

자산(엔진) 시스템 v1 + 오염 카드 압박 강화

Browse Source 
자산 시스템 (docs/작업지시서/자산시스템_작업지시서.md 반영, 이전 세션 작업분 커밋):
- 발라트로형 조커 레이어 엔진 빌딩 도입. assets.json 8종(트리거→효과→성장 스키마) +
  engine/assetEngine.js(이벤트 버스, 연쇄 깊이 상한 10)로 기존 수동 클릭형 자산 4종 전면 대체
- AssetInfoPopup 추가 — 자산 슬롯 클릭 시 트리거/효과/스택/충전 상태 표시, 발동 로그 피드 노출

오염 카드 압박 강화 (그레이박스 위기감 피드백 반영):
- engine/pollution.js 신설 — 오염 주입 규칙(타입 매핑·등급 추첨·물량)을 단일 모듈로 분리해
  사전 예고(SwipeCard) · 실제 주입(GameScreen) · 사후 알림이 같은 계산을 공유하도록 함
- 위험 파라미터를 올리는 결재는 정례회의를 기다리지 않고 그 자리에서 덱에 오염 카드를 주입
- UI 3종: 스와이프 시 오염 유입 사전 경고, 결재 후 유입 토스트, 상단 덱 오염 상시 게이지
- currentCardIndex를 매 결재마다 덱 길이로 정규화(주입/소각으로 덱 길이가 바뀌므로 필요)

기타:
- docs/architecture_design.md를 실제 구현(plain JS/CSS, useState, engine/ 순수 함수 경계)
  기준으로 전면 재작성 — 기존 문서는 채택되지 않은 초기 제안(Tailwind/Zustand/TS)이었음
- playtest.bat 추가 — 더블클릭으로 dev 서버 실행 (ASCII 전용, chcp로 인한 배치 파싱 오류 회피)
- CLAUDE.md 상태 갱신 및 실기 플레이 결과 기록

실기 플레이로 정상 동작 확인. 자산 획득 경로(극비 카드 스와이프)는 플레이 중 한 번도 발생하지
않아 원인 미조사 상태로 남김 — CLAUDE.md에 후속 확인 항목으로 기록.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
kyoung5seo
2026-07-23 22:59:30 +09:00
parent 31558edcb2
commit db1051c08c
14 changed files with 1397 additions and 279 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
docs/작업지시서/내러티브태그_시스템_작업지시서.md Normal file
View File

@@ -0,0 +1,138 @@
# 내러티브 태그 시스템 작업 지시서
> **범위:** (A) 연대기 ↔ 내러티브 태그 개념 분리 + (B) 내러티브 태그 스니펫 시스템 도입.
>
> **작업 환경:** Claude Code 세션에서 각 파일을 열어 해당 섹션을 대조 후 반영. 아래 문구는 리포 실제 텍스트와 100% 일치하지 않을 수 있으므로 의미 기준으로 수정할 것.
>
> **주의:** `narrative_tags.json` 콘텐츠(스니펫 등)는 자유롭게 초안·반영 가능. 단 `update_csv_tags.js` 등 **보호된 스크립트** 수정이 필요해지면 임의 실행 금지 — 근거 설명 → diff 확인 → 승인 절차를 따를 것.
---
# PART A. 연대기 ↔ 내러티브 태그 분리
## A-0. 개념 정의 (기준선)
| 구분 | 내러티브 태그 (Narrative Tag) | 연대기 (Chronicle) |
|---|---|---|
| 본질 | **결과** — 세계가 어떻게 되었는가 | **원인** — 내가 무엇을 어떻게 결재했는가 |
| 성격 | 명사 · 세계의 상흔 | 동사 · 국장의 결정 로그 |
| 구성 | 키워드 + 스니펫 + 엔딩 조건 + 페이즈 축 | 등장한 결재 카드 + 플레이어 선택(좌/우/위) 이력 (시간순) |
| 진입점 | 좌상단 `[📖 4/8]` 카운터 → '세계의 상흔' 팝업 | 별도 로그 버튼 + 엔딩 화면 '이번 회차 결정 요약' |
**한 줄 기억표:** 태그는 스토리의 '무엇', 연대기는 '어떻게'.
**스니펫은 태그 쪽에 귀속된다** (태그의 살). 연대기와는 무관.
## A-1. 시스템 기획서 — `Project SS 서사형 덱빌딩 게임 시스템 기획서.md`
1. 내러티브 태그 항목에서 연대기 서술을 **제거**. 태그 항목엔 스토리 전달(스니펫) + 엔딩 조건 + 페이즈 축만 남김.
2. 시스템 목록에 **독립 항목** 신설:
> **연대기 (Chronicle):** 국장이 결재한 카드와 그에 대한 선택(좌/우/위)을 시간순으로 기록한 결정 장부. 내러티브 태그가 '세계의 결과'라면, 연대기는 '국장의 원인 이력'이다.
## A-2. 스토리 바이블 — `Project SS 스토리 바이블 v3.0.md`
2장 "연대기의 편찬(The Chronicle)" 테마를 '결정 장부' 관점으로 재서술:
> 국장의 모든 결재는 되돌릴 수 없는 기록으로 남는다. 세계의 상흔(내러티브 태그)이 '무엇이 벌어졌는가'를 말한다면, 연대기는 '누가 그렇게 결정했는가'를 말한다. 플레이어는 회차가 끝난 뒤 이 장부를 되짚으며, 멸망이 사고가 아니라 자신의 서명들이 쌓인 결과였음을 마주한다.
## A-3. 텍스트 와이어프레임 — `ProjectSS 텍스트 와이어프레임.md`
1. **3.1 팝업 2종 분리:**
- '세계의 상흔' 팝업: `[📖 4/8]` 터치. 본문 = 태그 키워드 + 스니펫 시간순.
- '연대기' 팝업(신규): 별도 로그 버튼. 본문 = 결재 카드 + 선택 이력 시간순.
```
[일상] 오염된 장부 승인
└ 좌(예산+): 유가족 위로금은 예비비 충당
```
2. **3.2 엔딩 화면:** '이번 회차 연대기(결정 요약)' 블록 추가.
## A-4~A-7. 나머지 문서 (한두 줄 수정)
- **비전 문서 4-C:** 연대기 = 결재 카드·선택의 시간순 결정 장부. 세계 상태는 태그가 담당(분리).
- **PRD 5장:** 연대기(결재 결정 이력) / 내러티브 태그(엔딩·세계 상태) 각주 분리.
- **유저플로우 4.4:** 연대기와 태그 목록을 **분리 저장**으로 명시.
- **개발순서 Phase 4:** 연대기 기능과 태그 뷰('세계의 상흔')를 별도 UI로 분리 구현 명시.
---
# PART B. 내러티브 태그 스니펫 시스템
> 태그 키워드만으로는 서사 체감이 약함. 각 태그에 1~2문장 결과 보고서 스니펫을 붙여 살을 부여한다. 그레이박스 원칙 안에서 순수 텍스트로 검증 가능.
## B-1. 스타일 가이드 (확정)
**톤 3원칙**
1. **거리 유지** — 감정 형용사·판단·괴수 외형 묘사 금지. 오직 기록·숫자·행정 용어.
2. **숫자 하나** — 스니펫마다 구체 숫자 정확히 1개(예: 14명, 47건, 15%). 냉혹한 비용편익의 앵커.
3. **인정 유예** — 스니펫은 위로·의미 부여를 하지 않는다. 인정(감동)은 엔딩/연대기 회고의 몫으로 미룬다.
**포맷 골격**
`사실 진술 → 행정적 뒤틀림 → [처리 상태]로 종결`
- **마침 도장(각인층):** 모든 스니펫은 결재 상태어로 끝난다(처리됨 / 승인됨 / 종결됨 / 이관됨 / 반려됨 / 미반영됨 등). 이 게임만의 문장 지문.
**유형 2종 — 비율 약 7:3**
- **시스템형(70%):** 시스템의 부조리가 주인공.
- **사람형(30%):** 익명의 개인이 데이터 이상치로만 존재('숨겨진 헌신'). 엔딩/변주 콜백용.
> **설계 근거(참고 문서에서 이식):** 감동 공식(거리+숨겨진 헌신+인정+의미의 역류) — 거리는 문체로 확보, 헌신은 사람형 스니펫에 매설, 인정은 엔딩에서 역류. 로그라이크 루프가 이 역류를 회차마다 반복시킨다.
## B-2. 스키마 변경 (승인 필요 항목)
각 태그 객체에 두 필드 추가:
```json
{
"id": "quarantine_breach",
"keyword": "격리 붕괴",
"snippet": "격리동 전력 계통에 원인 불명의 수동 복구 기록 1건. 해당 시간대 출입 승인자 없음. 요원 K-771, 실종자 명단으로 이관됨.",
"snippet_type": "human",
"phase": 2
}
```
- `snippet` (string): 태그 스니펫 본문.
- `snippet_type` ("system" | "human"): 콜백 로직용. 엔딩/연대기 회고에서 해당 회차의 human 태그를 골라 "그때 K-771이…" 식 콜백 훅으로 사용.
> `narrative_tags.json` 직접 수정은 가능. 단 이 파일이 `update_csv_tags.js`로 **생성/가공**되는 구조라면 스크립트에 신규 컬럼 반영이 필요하므로, 그 경우 diff 확인 → 승인 후 진행.
## B-3. 샘플 배치 8종 (검토용 기준선)
**시스템형 (5)**
| 태그 | 스니펫 |
|---|---|
| `[실종]` | 7구역 정수장 근무자 14명 미귀가. 근태 시스템상 전원 '정상 퇴근'으로 **처리됨**. |
| `[가스 폭발]` | 언론 브리핑상 '노후 배관 폭발'로 발표. 유가족 위로금 항목은 예비비로 충당, 회계 **승인됨**. |
| `[매수]` | 3분기 감사 중 국장 명의 차명 계좌 3건 인지. 담당 조사관 해외 연수 발령으로 조사 **중단됨**. |
| `[차원 균열]` | 12구역 상공 '접힘 현상', 위성 미검출. 목격 진술 47건 전원 상이. 관측 장비 오류로 **종결됨**. |
| `[마녀사냥]` | '이웃이 변이체' 신고 폭증. 실제 변이 확인 0건, 자경단 폭행 사망 3건. 통계 비공개 **결정됨**. |
**사람형 (3) — 숨겨진 헌신**
| 태그 | 스니펫 |
|---|---|
| `[격리 붕괴]` | 격리동 전력 계통에 원인 불명의 수동 복구 기록 1건. 해당 시간대 출입 승인자 없음. 요원 K-771, 실종자 명단으로 **이관됨**. |
| `[결손 보전]` | 은폐 자금 결손분 340만, 익명 입금으로 충당. 입금자 추적 '불필요' 판정. 계정 **종결됨**. |
| `[초과 근무]` | 작전부 잔업 신청 반려 건수 218건. 반려된 요원 전원 무급으로 현장 잔류 확인. 근태 기록 **미반영됨**. |
## B-4. 확정 대기 (스타일 가이드 완성 전 결정 필요)
- [ ] **사람형 헌신 농도:** ⑥~⑧을 더 은근하게 vs 더 드러나게.
- [ ] **마침 도장 어휘:** 자유 어휘 허용 vs 고정 리스트로 관리(처리됨/승인됨/종결됨/이관됨/반려됨/미반영됨…).
이 둘이 정해지면 스타일 가이드 확정 → 나머지 태그를 다음 배치들로 진행.
---
# 통합 체크리스트
**Part A (개념 분리)**
- [ ] 시스템 기획서: 연대기 독립 항목 승격, 태그 항목 정리
- [ ] 스토리 바이블: "연대기의 편찬" 결정 장부 관점 재서술
- [ ] 와이어프레임: 팝업 2종 분리 + 엔딩 결정 요약 블록
- [ ] 비전/PRD/유저플로우/개발순서: 정의 분리 및 분리 저장/분리 구현 반영
**Part B (스니펫)**
- [ ] 스타일 가이드 확정(B-4 두 항목 결정)
- [ ] `narrative_tags.json` 스키마에 `snippet`, `snippet_type` 추가
- [ ] (해당 시) `update_csv_tags.js` 신규 컬럼 반영 — diff 승인 후
- [ ] 샘플 8종 반영 → 검토 → 나머지 태그 배치 확장
- [ ] 스토리 바이블 톤 앤 매너에 스니펫 3원칙·포맷 규칙 문서화(선택)

128
docs/작업지시서/자산시스템_작업지시서.md Normal file
View File

@@ -0,0 +1,128 @@
# 자산(엔진) 시스템 작업지시서 — 그레이박스 v1
> **목적**: 발라트로형 엔진 빌딩 검증. 자산 8종을 데이터로 구현하고, 자산 정보 UI 블로커를 해결하여 실제 플레이 테스트가 가능한 상태를 만든다.
> **원칙**: Greybox First. 수치는 전부 가안이며 튜닝 대상. 비주얼 연출 금지(텍스트/기본 도형만).
> **주의**: `update_csv_tags.js`, `update_csv.js` 등 파이프라인 스크립트는 수정 금지. 본 작업은 신규 데이터 파일 + 신규 로직 모듈로만 구성한다.
---
## Part A. 자산 데이터 스키마
신규 파일 `src/data/assets.json` 생성. 자산 1장의 문법은 **트리거 → 효과 → (선택) 성장**.
```json
{
"id": "asset_purge_001",
"name": "문서 파쇄실",
"grade": "C", // C | B | A | S
"archetype": "purge", // purge | convert | quarantine | skip
"trigger": {
"type": "every_n_approvals", // 트리거 enum (아래 표)
"params": { "n": 5 }
},
"effect": {
"type": "purge_lowest", // 효과 enum (아래 표)
"params": { "count": 1 }
},
"growth": null, // A급 이상만 사용. { "stackOn": "...", "per": 3, "bonus": {...} }
"risk": null, // 부작용. { "param": "risk_tolerance", "amount": 5, "when": "council_end" }
"faction_link": "scavengers", // 우호도 연동 파벌 (nullable)
"description": "결재 5건마다 덱에서 최하 등급 오염 카드 1장을 영구 소각한다.",
"flavor": "파쇄 용량: 일일 1건. 증설 요청은 3회 반려됨."
}
```
### 트리거 enum (v1 범위)
| type | 의미 | params |
|---|---|---|
| `on_pollution_draw` | 오염 카드 드로우 시 | `category`(신화/저항/공황/압박, nullable), `minGrade`(nullable) |
| `on_swipe_left` | 좌 스와이프 시 | — |
| `on_token_spend` | 토큰 소모 시 | `tokenType`(nullable) |
| `every_n_approvals` | 결재 N건마다 | `n` |
| `on_council_end` | 의회 종료 시 | — |
| `on_purge` | 오염 카드 소각 시 (연쇄용) | — |
| `on_convert` | 오염 카드 변환 시 (연쇄용) | — |
| `on_quarantine_fail` | 격리 실패 복귀 시 (연쇄용) | — |
| `manual_charge` | 충전식 수동/자동 방패 | `chargeEvery` |
### 효과 enum (v1 범위)
| type | 의미 | params |
|---|---|---|
| `purge_lowest` | 최하 등급 오염 소각 | `count` |
| `convert_to_token` | 오염 → 토큰 환전 | `tokenType`, `amount` |
| `quarantine` | 오염 격리 (조건 실패 시 강화 복귀) | `failCondition` |
| `negate_penalty` | 페널티 1회 무효 | `category`(nullable) |
| `gain_token` | 토큰 생성 | `tokenType`, `amount` |
| `gain_tag` | 자원 태그 생성 | `tagType`, `amount` |
| `convert_multiplier` | 변환 산출 배수 (상시) | `multiplier` |
| `quarantine_fail_to_purge` | 격리 실패 → 영구 소각으로 치환 (규칙 왜곡) | `bonusTag`(nullable) |
> 구현 노트: 트리거는 게임 이벤트 버스에 리스너로 등록. `on_purge`/`on_convert`/`on_quarantine_fail`은 다른 자산의 효과가 발생시키는 이벤트를 구독하므로, **효과 실행부가 반드시 이벤트를 발행**해야 연쇄가 성립한다. 무한 루프 방지를 위해 결재 1건당 연쇄 깊이 상한 10회.
---
## Part B. 자산 8종 데이터 (확정 배치 1차)
### ① 소각 특화 (faction: scavengers)
1. **문서 파쇄실** — C급
- 트리거: `every_n_approvals(5)` / 효과: `purge_lowest(1)`
2. **소각 처리 대장** — A급
- 트리거: `on_purge` / 성장: 스택 +1, 스택 3마다 `purge_lowest(1)` 추가 발동
### ② 변환 경제 (faction: nexus_traders)
3. **폐기물 재활용 규정** — C급
- 트리거: `on_pollution_draw(category: 신화)` / 효과: `gain_token(예산, 2)` (페널티는 정상 적용 후)
4. **부산물 매각 계약** — B급
- 효과: `convert_multiplier(2)` 상시 / 리스크: 의회 종료 시마다 위험 수용 계수 +5%
### ③ 격리 도박 (faction: occult_collectors)
5. **임시 격리 컨테이너** — C급
- 트리거: `on_swipe_left`(발동 선택 가능) / 효과: `quarantine(failCondition: 다음 의회까지 대중 공황 1단계 상승)`
6. **심연 보관 조례** — S급
- 트리거: `on_quarantine_fail` / 효과: `quarantine_fail_to_purge(bonusTag: 감시 +1)`
### ④ 무효 회피 (faction: field_agents_union — 우호도 **하락** 연동)
7. **결재 반려 도장** — C급
- 트리거: `manual_charge(chargeEvery: 10)` / 효과: `negate_penalty(전체)`
8. **책임 소재 불명 처리** — B급
- 트리거: 조직 저항 계열 `negate_penalty` 발동 시 / 효과: 인력 토큰 소모 없이 통과 / 리스크: 내부 저항 +3%
> 수치(5건, 토큰 2, 스택 3, 5%, 3% 등)는 전부 가안. 플레이 테스트 후 일괄 튜닝.
---
## Part C. UX 블로커 해결 (최우선 선행 작업)
**현재 문제**: 자산 클릭 시 아무 정보도 표시되지 않음 → 덱압축 시스템 평가 자체가 불가능.
1. 하단 자산 슬롯의 `Icon_Asset` 탭/클릭 시 정보 팝업 표시:
- 이름, 등급, 아키타입 아이콘
- **트리거 조건 → 효과** 를 한 문장으로 (description 필드 그대로)
- 성장형이면 현재 스택 수치 표시
2. **자산 발동 시 가시 피드백 (텍스트 로그로 충분)**: 화면 한쪽에 "『문서 파쇄실』 발동 — [하급 신화] 소각됨" 식의 1줄 로그. 발라트로의 조커 점멸에 해당하는 최소 구현. 연쇄 발동 시 순서대로 줄줄이 출력되어야 "엔진이 돌아간다"는 감각이 생긴다.
3. 그레이박스 기준이므로 애니메이션 불필요. 텍스트 로그 + 팝업만.
---
## Part D. 플레이 테스트 체크리스트
구현 완료 후 아래를 검증한다.
- [ ] **역전 엔진 성립**: 3번(재활용 규정) + 1번(파쇄실) 조합 시, 오염이 늘수록 자원이 돌고 덱이 정화되는 체감이 있는가?
- [ ] **연쇄 가시성**: 2번(소각 처리 대장) 보유 시 소각→스택→추가 소각 연쇄가 로그로 읽히는가?
- [ ] **S급 킹핀**: 6번(심연 보관 조례) 획득 전후로 격리 자산의 가치 평가가 뒤집히는가? (획득 전: 격리 기피 / 획득 후: 격리 남발)
- [ ] **무효 빌드의 풍자 체감**: 7+8번 조합으로 "덱은 더럽지만 아무 일도 안 일어나는" 상태가 만들어지는가?
- [ ] **오버파워 확인**: 페이즈 3에서 엔진이 오염 주입 속도를 이기는 순간이 오는가? (이겨야 정상 — 발라트로 모델)
- [ ] 연쇄 깊이 상한(10회)에 걸리는 케이스가 있는가?
## 범위 외 (다음 배치)
- 의회 압박 강화(안건 예고제, 표차 가시화) — 별도 작업지시서로 분리 예정
- 하이브리드 아키타입 자산 및 A/S급 보강 (2차 배치)
- 자산 획득 경로(극비 프로젝트 보상 테이블) 튜닝