# 신규 NerdNavisCore 설계안 (v1 — 초안)

> **작성일**: 2026-04-14
> **작성자**: 개발실장
> **문서 상태**: 🟡 **설계 초안 (v1)** — 일부 항목 미확정, PD님 판단 필요 항목 명시
> **참조 문서**: `04_코어_범용성_분석_v1.md` (구 NerdNavisCore 분석 결과)
> **근거 규칙**: 공통 규칙 **P18 (설계 문서화 의무)**, 핵심 규칙 **C11 (개발 관점 원칙)**

---

## 0. 문서 목적

본 문서는 **너드나비스 자체 범용 코어(이하 "신규 NerdNavisCore")** 의 설계 방향과 구현 가이드라인을 명문화한다.

유령 문서(참조만 존재하고 본문 없음) 금지 원칙에 따라, 아직 **미확정 결정사항이 있더라도 최소한의 방향성을 먼저 문서로 고정**하고 이후 개정 이력으로 추적한다.

---

## 1. 결정의 배경

### 1.1 기존 NerdNavisCore 상황
- **위치**: `C:/Project/Core/NerdNavisCore/` (외부 프로젝트)
- **범용성 점수**: 78/100 (04번 분석 결과, C11 합격)
- **구성**: `DG.*` 네임스페이스, 91개 파일, ~14,000 lines
  - UI 프레임워크 / 데이터 테이블 / 유틸리티 / 에디터 확장 / 가챠·부스트 / 전투 인터페이스
- **오염도**: 0% (프로젝트 특수 로직 없음, 깨끗한 상태)

### 1.2 신규 제작이 필요한 사유
1. **소유권 이전**: 기존 `NerdNavisCore`는 **타 회사 소유로 전환**됨 (2026-04-14 PD님 지시 확인)
2. **담당자 퇴사**: 원 제작자 부재로 구조적 개선·유지보수 채널 상실
3. **코드 차용 불가**: 소유권이 이전되었으므로 코드를 그대로 복사하는 것은 불가 — **참고·아카이브 용도로만** 활용
4. **누락 모듈 기회**: 기존 코어에 부재했던 네트워크 추상화·세이브 시스템·로컬라이제이션을 **처음부터 포함**하여 설계 품질 상승

### 1.3 전략적 판단
너드나비스 스튜디오는 복수 프로젝트를 전개할 조직이므로, **범용 코어는 스튜디오의 지속가능한 자산**이다. 본 기회를 통해 코어를 **자체 소유·자체 관리 체계로 확립**한다.

---

## 2. 설계 방향

### 2.1 기본 원칙
1. **기존 코어의 장점 계승** — 범용성 확보된 영역(UI·데이터 테이블·유틸·에디터 확장)의 **구조·패턴**을 차용 (코드가 아닌 설계)
2. **누락 모듈 내장** — 네트워크 추상화·세이브/로드·로컬라이제이션을 **1차 릴리스부터 포함**
3. **프로젝트 오염 0% 유지** — 카드·몬스터·상점 등 수상한 잡화점 특수 개념 **절대 혼입 금지**
4. **C11 3원칙 준수** — 자원 효율성 / 코드 구조 직관성 / 코드 범용성

### 2.2 구성 모듈 (계획)

| # | 모듈 | 상태 | 비고 |
|---|------|------|------|
| 1 | **기본 인터페이스·열거형** | 🟢 1차 포함 | `DG.Core` 대체 — 기본 계약 정의 |
| 2 | **유틸리티 (싱글톤·코루틴·컨테이너)** | 🟢 1차 포함 | 가장 재사용률 높은 영역 |
| 3 | **데이터 테이블 시스템** | 🟢 1차 포함 | CSV/JSON → ScriptableObject 자동 변환 |
| 4 | **UI 프레임워크** | 🟢 1차 포함 | UIElements 기반 |
| 5 | **에디터 확장** | 🟢 1차 포함 | 애셋번들·빌드·계층창 단축키 |
| 6 | **네트워크 추상화 (INetworkService)** | 🟢 1차 포함 (**신규**) | 기존 코어 누락 보완, PlayFab/Firebase 의존 제거 |
| 7 | **세이브/로드 시스템** | 🟢 1차 포함 (**신규**) | JSON/Binary 직렬화 + 암호화 |
| 8 | **로컬라이제이션 매니저** | 🟢 1차 포함 (**신규**) | 다국어 텍스트/애셋 관리 |
| 9 | **데이터 테이블 무결성 검증 도구** | 🟢 1차 포함 (**신규**) | FK 검증·스탯 범위 이상 탐지, CI 연결 가능 |
| 10 | **가챠/부스트 시스템** | 🟡 2차 | 기존 코어는 "가챠/부스트" 용어 하드코딩 → **제네릭 추첨(Draw) 시스템으로 일반화** 필요 |
| 11 | **전투 인터페이스·열거형** | 🟡 2차 | enum 값 일부 특화 → **추상 이벤트/상태머신 기반으로 재설계** |
| 12 | **오디오 매니저** | 🟡 2차 | 게임별 차이 큼 — 공통 API만 |
| 13 | **VFX 래퍼** | 🟢 3차 | 파라미터화된 이펙트 관리 |

### 2.3 네임스페이스 체계 (결정 필요)

**Option A (PD님 판단 필요)**: 기존 `DG.*` 그대로 사용
- 장점: 과거 패턴 익숙
- 단점: 원 제작자의 이니셜로 추정되어 **소유권 혼선 우려**

**Option B (권장)**: `NerdNavis.*` 로 신규 체계
- 장점: 스튜디오 소유권 명확, 검색·분리 용이
- 단점: 신규 학습 비용 (미미)

```
NerdNavis.Core                 - 기본 인터페이스, 열거형
├─ NerdNavis.Core.Data         - 마스터 테이블, 데이터 파싱
├─ NerdNavis.Core.Tool         - CSV 변환, 에디터 도구
├─ NerdNavis.Core.Validation   - 테이블 무결성 검증 (신규)
NerdNavis.Util                 - 유틸리티
├─ NerdNavis.Util.Container    - 제네릭 컬렉션
NerdNavis.UI                   - UI 프레임워크
NerdNavis.Net                  - 네트워크 추상화 (신규)
NerdNavis.Save                 - 세이브/로드 (신규)
NerdNavis.Localization         - 로컬라이제이션 (신규)
NerdNavis.Manager              - ObserverManager 등
```

**→ 열린 이슈 OI-1**: 네임스페이스 최종 결정 (PD님 판단 대기)

### 2.4 저장 위치 (결정 필요)

**Option A**: 기존 방식 유지 — `C:/Project/Core/NerdNavisCore/` 외부 경로 참조
**Option B (권장)**: **Git 서브모듈 또는 Unity Package (UPM Git URL)** 로 전환 — 버전 관리·배포 표준화

**→ 열린 이슈 OI-2**: 코어 배포 방식 최종 결정 (개발실 내부 협의 후 PD님 공유 예정)

---

## 3. 대안 비교

| 대안 | 장점 | 단점 | 판정 |
|------|------|------|------|
| **A. 완전 신규 제작** (채택) | 소유권 완전 확보, 누락 모듈 1차 포함, 구조 최신화 | 초기 구현 분량 큼 | ✅ **선택** |
| **B. 기존 코어 일부 재작성** | 재사용 최대화 | 소유권 이전된 코드 참조 리스크, 법적 회색지대 | ❌ 기각 |
| **C. 오픈소스 라이브러리 도입 (DOTween·UniTask·Zenject 조합)** | 커뮤니티 검증, 즉시 사용 가능 | 다수 의존성 결합, 라이선스 관리 복잡, 스튜디오 내부 통제 상실 | ❌ 기각 (보조적 채택은 가능 — DOTween 등은 현재도 사용 중) |
| **D. Unity 공식 패키지만 사용 (Addressable·UI Toolkit·Localization 패키지)** | 유지보수 책임 Unity | 고수준 범용 유틸·팩토리·컨테이너 등 공백 | ❌ 단독으론 부족 (보조적 채택) |

### 3.1 C9 원칙 적용 결과
핵심 규칙 C9에 따라 "MVP·공수·일정" 고려하지 않고 **완성도 최우선**. 따라서 A안(완전 신규) 선택이 정당함.

### 3.2 법적 안전장치 (2026-04-15 PD님 결정 반영)
기존 코어의 **설계 패턴을 최대한 차용**하여 더 좋은 설계 방안이 있으면 **참고 자료로 적극 활용**한다. **법무 검토는 불필요** (PD님 2026-04-15 직접 결정). 단, **코드 직접 복사는 지속 금지** — 재구현 시 모든 코드는 신규 작성한다.

**→ 열린 이슈 OI-3**: ✅ **확정 (2026-04-15 PD님 결정)** — 법무 검토 불요, 설계 패턴 최대 차용 및 참고 자료 활용

---

## 4. 구현 가이드라인 (C11 3원칙 기반)

### 4.1 자원 효율성
- **GC 최소화**: 범용 유틸·컨테이너는 내부 풀링(Object Pool) 내장
- **Lazy 초기화**: 사용되지 않는 모듈은 로드하지 않음 (Assembly 분리)
- **Addressable 통합**: 리소스 로딩은 기본적으로 Addressable 기반으로 설계
- **메모리 상한**: 테이블 로딩 시 전수 메모리 상주 대신 지연 로드 패턴 제공

### 4.2 코드 구조의 직관성
- **네임스페이스 필수**: 모든 공개 타입은 `NerdNavis.*` 네임스페이스 소속
- **인터페이스 우선**: 구현체가 아닌 인터페이스(`INetworkService`, `ISaveStore` 등)로 노출
- **명명 컨벤션**:
  - 인터페이스: `I` 접두사 (`INetworkService`)
  - 추상 클래스: `Abstract` 접두사 또는 `Base` 접미사
  - 이벤트: `On` 접두사 (`OnLoaded`)
  - 정적 유틸: `*Util` / `*Helper`
- **폴더 = 네임스페이스 1:1 매핑**

### 4.3 코드 범용성
- **프로젝트 특수 개념 금지**: `Card`, `Monster`, `Shop`, `DeckBuilding` 등 용어 **코어 전체에서 0건** 유지
- **제네릭·추상 우선**: 구체 타입 의존 최소화
- **플랫폼 독립**: `#if UNITY_*` 분기는 플랫폼 어댑터 계층에만 한정
- **설정 주입**: 기본값 하드코딩 대신 `ScriptableObject` 기반 설정 주입

### 4.4 금지 사항 (04번 문서에서 계승)
- ❌ 프로젝트 용어 포함 파일 (`Card*`, `Monster*`, `Shop*`)
- ❌ `FilGoodBandits` 네임스페이스를 코어에서 참조
- ❌ 코어 enum에 프로젝트 특수값(`eCardType` 등) 추가
- ❌ 특정 서버(PlayFab) / 특정 분석(Firebase) 직접 의존 — 반드시 추상화 계층 경유

---

## 5. 검증 방법

### 5.1 품질 보증 방법
| 방법 | 목적 | 주기 |
|------|------|------|
| **오염도 자동 검사** | 코어 내부에 프로젝트 용어(Card, Monster 등) 포함 여부 grep 스캔 | CI 매 커밋 |
| **샘플 게임 복수 구현** | 덱빌딩 외 최소 1종(예: 퍼즐 샘플)으로 범용성 실증 | 릴리스 전 |
| **단위 테스트** | 각 모듈(유틸·세이브·네트워크) 테스트 커버리지 목표 ≥70% | CI 매 커밋 |
| **정적 분석** | Roslyn Analyzer로 네임스페이스·명명 컨벤션 강제 | CI 매 커밋 |
| **범용성 자가 점검 (Q&A)** | 04번 문서의 Q1·Q2·Q3 질의 재적용 → 점수 산정 | 메이저 버전 릴리스마다 |

### 5.2 인수 기준 (1차 릴리스)
- [ ] 오염도 0% (프로젝트 용어 grep 0건)
- [ ] 샘플 프로젝트에서 신규 코어로 **최소한의 덱빌딩 프로토타입** 재구현 성공
- [ ] 9개 1차 모듈 단위 테스트 통과
- [ ] 네임스페이스·명명 컨벤션 정적 분석 경고 0건
- [ ] 문서화: 각 모듈 README + 시작 가이드

### 5.3 기존 코어와의 범용성 비교 목표
- **목표 점수**: ≥85/100 (기존 78점 + 누락 모듈 3종 보완분)
- 측정: 04번 문서와 동일 방식 재산정

---

## 6. 시뮬레이터 이원화 해소와의 연관

본 코어 신규 제작은 `07_시뮬레이터_이원화_해소_착수계획_v1.md` 와 **독립적으로 진행**한다.

단, 양자가 만나는 접점:
- **시뮬레이터 Headless 추출 시** — 프로젝트 코드에서 신규 코어 의존이 없는 부분만 먼저 추출 가능 (기존 코어는 이미 PlayFab·Unity UI 의존 없음, 신규 코어도 동일 원칙 유지)
- **데이터 테이블 시스템** — 신규 코어의 테이블 로딩이 Python 시뮬과 동일 JSON을 공유하도록 **직렬화 포맷 호환성** 유지

→ 시뮬 이원화 해소 작업에서 **테이블 로딩 인터페이스를 신규 코어의 원형으로 활용**할 수 있음.

---

## 7. 열린 이슈 (PD님 판단 필요)

| ID | 이슈 | 상태 | 결정 권자 |
|----|------|------|----------|
| **OI-1** | 네임스페이스: `DG.*` 유지 vs `NerdNavis.*` 전환 | 🔴 미결 | PD님 |
| **OI-2** | 코어 배포 방식: 외부 경로 참조 vs Git 서브모듈 vs UPM | 🟡 **헌법 제1원칙 3대 목표 기반 재평가 중** (PD님 2026-04-15 지시) | 개발실장 → PD님 안건 재제안 |
| **OI-3** | 기존 코어 참고 범위: 설계 패턴만 vs 일부 코드 패턴도 재구현 가능 여부 — 법무적 안전성 확인 필요 | ✅ **확정 (2026-04-15 PD님)** — 법무 검토 불요, 설계 패턴 최대 차용 및 참고 자료 활용 | PD님 |
| **OI-4** | 1차 릴리스 범위: 9개 모듈 vs 6개 모듈부터 단계적 | ✅ **확정 (2026-04-15 PD님)** — A안 **9개 모듈 일괄 1차 릴리스** | PD님 |
| **OI-5** | 현행 `수상한잡화점` 프로젝트에 신규 코어 적용 시점 — 본 프로젝트는 기존 코어 참조 상태 유지 vs 신규 코어로 마이그레이션 | 🔴 미결 | PD님 |

---

## 8. 작업 착수 계획 (상위 수준)

> **상세 공수·담당은 OI 결정 후 하위 계획으로 분리 작성 예정**

| 단계 | 내용 | 선결 조건 |
|------|------|----------|
| **0. 이슈 해소** | OI-1 ~ OI-5 PD님 결정 수령 | — |
| **1. 레포 초기화** | 신규 Git 레포 생성, 네임스페이스 골격, asmdef 구성 | OI-1, OI-2 |
| **2. 1차 모듈 구현** | Core / Util / Data / UI / Editor + Net / Save / Localization / Validation | 단계 1 완료 |
| **3. 샘플 프로젝트 검증** | 최소 덱빌딩 프로토타입 재구현 | 단계 2 완료 |
| **4. 수상한 잡화점 마이그레이션 판단** | OI-5 결정에 따라 진행 여부 결정 | 단계 3 완료 |

---

## 9. 변경 이력

| 일자 | 작성·수정자 | 버전 | 사유 |
|------|-----------|------|------|
| 2026-04-14 | 개발실장 | v1 (초안) | 유령 문서 해소(P18) — 05번 문서에서 참조되나 실체 부재 상태 해결. 기존 코어 소유권 전환에 따른 신규 제작 방향 명문화 |
| 2026-04-15 | 총괄PM | v1.1 | PD님 직접 결정 반영: OI-3 법무 검토 불요·설계 패턴 최대 차용 확정 / OI-4 A안(9개 모듈 일괄) 확정 / OI-2는 헌법 제1원칙 3대 목표 기반 안건 재도출로 이관 (§3.2·§7 갱신) |

---

## 10. 참고 문서

- `04_코어_범용성_분석_v1.md` — 기존 NerdNavisCore 구조·범용성 분석 (아카이브 용도)
- `05_서버연동_현황_v1.md` — 네트워크 추상화 필요성의 근거 (Critical 3건 포함)
- `02_개발자관점_점검_v1.md` — C11 점검 항목 전반
- `03_Unity프로젝트_구조_v1.md` — 프로젝트 코드와 코어의 경계
- 공통 규칙 C11 (개발 관점 원칙), P18 (설계 문서화 의무)