13 KiB

Raw Blame History

신규 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 신규 제작이 필요한 사유

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

1.3 전략적 판단

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

2. 설계 방향

2.1 기본 원칙

기존 코어의 장점 계승 — 범용성 확보된 영역(UI·데이터 테이블·유틸·에디터 확장)의 구조·패턴을 차용 (코드가 아닌 설계)
누락 모듈 내장 — 네트워크 추상화·세이브/로드·로컬라이제이션을 1차 릴리스부터 포함
프로젝트 오염 0% 유지 — 카드·몬스터·상점 등 수상한 잡화점 특수 개념 절대 혼입 금지
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 법적 안전장치

기존 코어 코드의 구조·아이디어 참고는 허용되나 코드 직접 복사는 금지. 재구현 시 설계 패턴만 차용하고 모든 코드는 신규 작성한다.

→ 열린 이슈 OI-3: 기존 코어 참고 범위에 대한 법무 검토 필요 여부 (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	🟡 개발실 협의 중	개발실장 → PD님 공유
OI-3	기존 코어 참고 범위: 설계 패턴만 vs 일부 코드 패턴도 재구현 가능 여부 — 법무적 안전성 확인 필요	🔴 미결	PD님
OI-4	1차 릴리스 범위: 9개 모듈 vs 6개 모듈부터 단계적	🟡 C9 원칙상 9개 일괄 권장이나 PD님 재확인	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번 문서에서 참조되나 실체 부재 상태 해결. 기존 코어 소유권 전환에 따른 신규 제작 방향 명문화

10. 참고 문서

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

13 KiB Raw Blame History