# 카드 전투 통합 (TODO 항목 B) — 설계

> 작성: 2026-06-08 / 상태: 승인됨 / 근거: TODO.md 항목 B + 코드 직접 분석.
> 선행 작업: 항목 C(미커밋 노이즈 정리) 완료 — 작업 트리 클린.

## 문제

현재 `SlayDeckController.codeblock`의 `PlayCard`는 에너지만 차감하고 `Toast(log)`만 띄운다.
실제 전투 상태(적 HP/방어, 플레이어 HP/Block, 적 의도, 승패)가 없어 STS식 덱빌딩 루프가
닫히지 않는다. 필드 액션 몬스터(`Monster.codeblock` — HP·피격·리스폰)는 카드 시스템과 분리돼 있다.

## 범위

**포함**: 단일 적 카드 전투 루프(데미지·방어·적 의도·턴 진행·승패), 카드 수치화, DeckHud UI 노출.
**제외(금지)**: 로그라이크 메타(E), 신규 카드 대량 추가, 전체 데이터 외부화(D — 본 작업은 인라인 수치화까지).

## 단일 소스 원칙

모든 변경은 `tools/gen-slaydeck.mjs`에서 생성한다. `SlayDeckController.codeblock` /
`ui/DefaultGroup.ui` / `Global/common.gamelogic`을 직접 손으로 편집하지 않는다.
변경 = 생성기 수정 → `node tools/gen-slaydeck.mjs` 재실행.

## 수치는 임시 placeholder

> 플레이어 수치는 향후 **캐릭터 특성별**, 몬스터 수치는 **몬스터별**로 다르게 설정 예정.
> 본 작업의 값(플레이어 80 / 적 45 / 의도 10·6·방8)은 루프 검증용 임시값이며,
> D(데이터 외부화) 단계에서 캐릭터/몬스터별 데이터로 분리한다.

## 설계

### 1) 전투 상태 (codeblock 속성 추가)
- 플레이어: `PlayerHp`, `PlayerMaxHp`(임시 80), `PlayerBlock`
- 적: `EnemyHp`, `EnemyMaxHp`(임시 45), `EnemyBlock`, `EnemyIntentIndex`
- `CombatOver`(승패 후 입력 잠금)
- 적은 codeblock 내부 상태로 보유(필드 `Monster.codeblock`과 분리).

### 2) 카드 데이터 수치화 (desc 파싱 폐기)
| id | 이름 | cost | kind | 효과 |
|----|------|------|------|------|
| Strike | 타격 | 1 | Attack | damage 6 |
| Defend | 방어 | 1 | Skill | block 5 |
| Bash | 강타 | 2 | Attack | damage 10 |

`desc`는 표시용으로만 유지. 효과는 `damage`/`block` 숫자 필드로 처리.
시작 덱: Strike×5, Defend×4, Bash×1 (10장).

### 3) 적 의도 — 결정적 사이클 (사용자 선택: A안)
- 의도 사이클(3스텝 회전): `[공격 10] → [공격 6] → [방어 8]`
- 매 플레이어 턴 시작 시 **다음 의도를 미리 표시**.
- 결정적이라 F(밸런스 시뮬레이터)에서 동일 규칙 재현 가능.

### 4) 전투 규칙 (STS 관례)
- 데미지는 **방어도 먼저 차감** 후 잔여만 HP에 적용.
- 플레이어 Block은 **플레이어 턴 시작 시 0 리셋**, 적 Block은 **적 턴 시작 시 리셋**.
- `PlayCard(slot)`: `kind=="Attack"` → 적 HP 감소(적 Block 우선 차감);
  `kind=="Skill"` → 플레이어 Block 증가.
- `EndPlayerTurn` → 적 턴: 적 Block 리셋 → 현재 의도 실행(공격이면 플레이어에 피해,
  방어면 적 Block↑) → 의도 인덱스 전진 → 패배 체크 → 다음 플레이어 턴(Block/에너지 리셋·드로우)
  → 다음 의도 표시.
- 승패: 적 HP≤0 → 승리 / 플레이어 HP≤0 → 패배. 승패 시 `CombatOver=true`로 입력 잠금 +
  결과 텍스트 표시 + **보상 훅 자리(E용 주석)**.

### 5) UI — DeckHud 엔티티 추가 (생성기 생성)
- 상단 적 패널: 적 이름 · `HP 45/45` · `방어 0` · `의도: 공격 10`
- 좌측 플레이어 패널: `HP 80/80` · `방어 0`
- 승패 결과 텍스트(중앙, 평소 숨김 → 승패 시 표시).

## 검증 (메이커 Play)
- 타격 카드 → 적 HP 감소(적 Block 있으면 먼저 차감).
- 방어 카드 → 플레이어 Block 증가.
- 턴 종료 → 적이 표시된 의도대로 공격(플레이어 Block이 피해 흡수) 또는 방어.
- 적 HP 0 → 승리 / 플레이어 HP 0 → 패배, 입력 잠금.
- `node tools/gen-slaydeck.mjs` 2회 실행 결과 동일(결정적).
- `git status` — 의도한 생성물만 변경.