Seven-Shards-ORIGIN — 전투 리팩터링 스냅샷

1. 주요 변경사항

• PlayerStats, EnemyBase, 주요 Enemy, 중간보스, 최종보스가 partial 파일군으로 분할됐다. 이전보다 파일 탐색성과 변경 범위 파악은 확실히 좋아졌다.
• FinalBossEnemy2D는 패턴 직접 호출에서 BossState 생성·실행 흐름으로 이동했다. 보스 행동을 상태 단위로 다루려는 방향은 타당하다.
• PlayerStats는 사망, 부활, 피해, 표현, 라이프사이클로 나뉘었다. NGO 기반 서버 권한 코드가 흩어진 만큼 회귀 테스트 중요도가 올라갔다.
• NotoSansKR-Regular SDF.asset가 대량 변경됐다. 폰트 에셋은 diff 리뷰가 사실상 불가능하므로 생성 조건과 검증 기준이 필요하다.

2. 코드 품질 리뷰

이번 변경의 핵심 성과는 “거대한 단일 파일을 읽을 수 있는 단위로 나눈 것”이다. 특히 FinalBossEnemy2D의 이전 backlog는 실질적으로 개선됐다. 다만 partial class는 구조 개선의 시작이지 완성은 아니다. 같은 클래스의 private/protected 상태를 여러 파일이 공유하면 책임 경계가 컴파일 단위로는 여전히 하나다. 즉 파일 수는 줄었지만 결합도까지 낮아졌는지는 별도 확인이 필요하다.

public partial class PlayerStats : NetworkBehaviour, IDamageable
public partial class FinalBossEnemy2D : EnemyBase

이 패턴 자체는 Unity 컴포넌트 리팩터링에서 현실적인 선택이다. 단, 네트워크 상태, 사망 플로우, 시각 효과, 입력 요청이 한 컴포넌트 내부 partial로만 나뉘면 테스트 가능한 순수 로직이 생기지 않는다. 다음 단계에서는 “파일명별 분리”가 아니라 “상태 전이 책임” 기준으로 검증해야 한다. 예를 들어 보스 패턴은 BossState로 이동했으므로 취소, 사망, stagger, phase 전환 중 어떤 상태가 후처리 gap을 갖는지 테스트 케이스로 고정하는 것이 좋다.

또 하나의 위험은 주석 제거다. 긴 주석이 항상 좋은 것은 아니지만, PlayerStats의 부활 정책처럼 게임 규칙과 네트워크 권한 모델을 설명하던 주석은 코드 밖 문서로 이동해야 한다. 설명이 사라지고 구현만 남으면 신규 인원이 멀티 사망 플로우를 안전하게 수정하기 어렵다.

3. 진행도 평가

이전 대비 전진은 분명하다. 전투 핵심 클래스의 물리적 분할과 보스 상태머신화는 앞으로 기능을 더 얹기 위한 기반 작업으로 가치가 있다. 특히 최종보스 단일 클래스 집중 문제를 이번 커밋에서 직접 다룬 점은 긍정적이다.

다만 완성도 평가는 크게 올리기 어렵다. 커밋이 1개에 90개 파일, 1만 줄 이상 삽입 규모라 회귀 위험이 높고, 문서·테스트·체크리스트 갱신이 동반되지 않았다. 현재는 플레이 가능 빌드로 가는 중반 이후 단계로 보이나, 멀티 사망·부활·보스전 검증 없이는 안정 단계라고 보기 어렵다.

4. 다음 권장사항

• PlayerStats 사망·부활 플로우를 1인, 2인, 전멸, 공유 목숨 0 케이스로 재현 테스트한다.
• EnemyBase와 파생 Enemy partial 파일들이 공유 필드에 얼마나 의존하는지 점검한다.
• FinalBossEnemy2D의 phase2, last stand, floor collapse 상태 전이를 플레이 테스트로 고정한다.
• 대량 변경된 SDF 폰트 에셋의 생성 설정, 포함 문자, 대상 로케일을 문서화한다.
• 전투 리팩터링 결과를 기술 문서의 모듈 맵으로 남겨 다음 변경 기준을 만든다.

5. 문서화 상태

design은 4점이다. 게임 컨셉과 시스템 방향은 코드에서 일부 추론되지만, 현재 스냅샷에는 전투 리팩터링 의사결정이나 보스전 경험 목표를 설명하는 문서 갱신이 보이지 않는다.

technical은 3점이다. NGO 서버 권한, 부활 정책, 보스 상태머신 구조처럼 반드시 문서화해야 할 내용이 코드 주석과 구현에 기대고 있다. 이번처럼 partial 분할이 큰 경우에는 파일 구조표만 있어도 유지보수 비용이 크게 줄어든다.

spec은 3점이다. 보스 패턴 수치와 폰트 에셋 변경은 사양 성격이 강한데, 리뷰 가능한 수치표나 QA 체크리스트가 함께 보이지 않는다. 플레이테스트 체크리스트 위치 문제도 여전히 남아 있다.

6. Backlog

• 플레이테스트 체크리스트의 후속 위치가 아직 확인되지 않는다. 다음 리포트까지 QA 기준 문서로 복원해야 한다.
• TrapFieldWest.unity의 Mesh fileID 셔플 문제는 이번 커밋에서 해결 근거가 없다.
• Resources 기반 UI·로케일 로딩과 Addressable 전환 계획은 계속 남아 있다.
• UI Bootstrap/Driver/RootRefs 규약은 여전히 문서화된 아키텍처 계약으로 보이지 않는다.
• 로케일 fallback, 누락 키 리포트, 언어 변경 시 기존 TMP 텍스트 갱신 문제는 미해결이다.
• zh-Hans, zh-Hant, ja 폰트 대리 문제는 KR SDF 에셋 대량 변경만으로 해결됐다고 판단할 수 없다.

7. 이전 Backlog 해결

• FinalBossEnemy2D 신규 구현이 단일 클래스에 과도하게 집중은 해결로 본다. 기존 FinalBossEnemy2D.cs의 패턴, 설정, 표현, 상태머신, Authoring 책임이 별도 partial 파일로 분리됐고, 본체는 상태 생성·실행 흐름 중심으로 축소됐다.