BurningTimesAi/프로젝트/신규 프로젝트/개발/01_아키텍처_설계.md

{프로젝트명} — 아키텍처 설계

버전: v1 작성일: {날짜} 담당: 개발팀장 적용 범위: {프로젝트명} Unity 클라이언트

---

1. 프로젝트 기본 정보

항목	값	비고
Unity 버전	6000.0.x 이상 (Unity 6 LTS)	하위 버전 사용 시 팀장 확인 필수
타겟 플랫폼	Android(주), iOS, Windows(Editor)	{장르}에 따라 조정
Scripting Backend	IL2CPP	Android/iOS 공통
API 호환성	.NET Standard 2.1
NerdNavis.Framework 버전	com.nerdnavis.framework v0.x.y	관리/Unity_셋업_가이드.md 참조
렌더 파이프라인	URP (기본) / Built-in (선택)	착수 시 확정

---

2. 어셈블리(asmdef) 구성

⚠️ Assembly-CSharp 단일 어셈블리 금지 (수상한잡화점 교훈: asmdef 미적용으로 컴파일 시간 증가·의존성 관리 불가 문제 발생)

asmdef	경로	의존
{ProjectNamespace}.Core	Assets/Scripts/{ProjectNamespace}/Core/	NerdNavis.Framework.Runtime
{ProjectNamespace}.UI	Assets/Scripts/{ProjectNamespace}/UI/	.Core
{ProjectNamespace}.Data	Assets/Scripts/{ProjectNamespace}/Data/	.Core
{ProjectNamespace}.Server	Assets/Scripts/{ProjectNamespace}/Server/	.Core
{ProjectNamespace}.Editor	Assets/Scripts/{ProjectNamespace}/Editor/	.Core, NerdNavis.Framework.Editor (Editor only)
ThirdParty/	Assets/ThirdParty/	서드파티별 격리

규칙:

• 각 asmdef는 자신의 역할 외 다른 도메인 코드를 포함하지 않는다
• 순환 참조 금지 (Core ← UI ← Data ← Server 단방향)
• 에디터 전용 코드는 반드시 .Editor asmdef로 분리

---

3. Assets 폴더 구조

Assets/
├── Scripts/
│   └── {ProjectNamespace}/
│       ├── Core/               ← 게임 매니저, 부트스트랩, 공통 모델
│       ├── UI/                 ← UI View, Panel, HUD
│       ├── Data/               ← DataTable 서브클래스, DataLoader
│       ├── Server/             ← 서버 통신 레이어 (INetworkService 구현)
│       └── Editor/             ← 에디터 전용 도구
├── Addressable/
│   ├── Ingame/                 ← 인게임 리소스 그룹
│   ├── UI/                     ← UI 리소스 그룹
│   └── Audio/                  ← 오디오 그룹
├── Scenes/
│   ├── 00_Bootstrap.unity
│   └── ...
├── Prefabs/
├── Art/
│   ├── Sprites/
│   ├── Effects/
│   └── Characters/
├── Audio/
│   ├── BGM/
│   └── SFX/
├── ThirdParty/                 ← 서드파티 패키지 격리
└── Editor/                     ← 프로젝트 에디터 도구 (asmdef 없는 구역)

주의: Resources/ 폴더는 최소 사용. 동적 로딩은 Addressables로 대체한다.

---

4. 네임스페이스 체계

⚠️ 전역 네임스페이스(global) 사용 금지 (수상한잡화점 교훈: 클래스명 충돌 위험, 장기 리팩토링 부담)

{ProjectNamespace}                    ← 루트 (공용 인터페이스, 공용 enum)
│
├── {ProjectNamespace}.Core           ← 게임 매니저, 부트스트랩, 공통 도메인
├── {ProjectNamespace}.UI             ← UI View, Panel
├── {ProjectNamespace}.Data           ← DataTable 구현체, DataLoader
├── {ProjectNamespace}.Server         ← 서버 통신, Request/Response 래퍼
└── {ProjectNamespace}.Editor         ← 에디터 도구 (런타임 제외)

NerdNavis 네임스페이스와 분리 원칙:

• NerdNavis.* = 프레임워크 영역 (수정 불가)
• {ProjectNamespace}.* = 프로젝트 전용 영역
• 두 영역의 혼합 사용 금지

---

5. 매니저/시스템 목록

클래스	역할	라이프사이클	Framework 의존
GameManager	게임 전체 상태 관리, 씬 전환 총괄	MonoSingleton<T> (Persistent)	✅
DataManager	DataTable 로딩·캐시 관리	MonoSingleton<T> (Persistent)	✅
UIManager	UI View 스택·전환 관리	MonoSingleton<T> (Persistent)	✅
AudioManager	BGM/SFX 재생	NerdNavis.Audio 위임	✅
ServerManager	서버 통신 추상화	ServiceLocator	✅
SaveManager	세이브/로드	ServiceLocator + NerdNavis.Save	✅
{Game}Manager	핵심 게임 로직 매니저 ({장르} 특화)	MonoSingleton<T> or ServiceLocator	상황별

라이프사이클 선택 기준:

• MonoSingleton<T>: Update/OnDestroy 훅이 필요하거나 씬 생명주기와 동기화가 필요한 서비스
• ServiceLocator: 순수 C# 서비스, 인터페이스 바인딩·테스트 대체가 필요한 서비스

---

6. 씬 구성

씬명	역할	로드 방식
00_Bootstrap	앱 진입점, 초기화(Manager 셋업, DataTable 로딩)	Single (시작점)
01_Title	타이틀·로그인 화면	Single
02_Main	메인 로비	Single
03_Ingame	인게임(핵심 게임 루프)	Single or Additive
9x_Tool_*	개발용 도구 씬 (배포 빌드 씬 리스트 제외 필수)	Single

규칙:

• 배포 빌드에서 9x_Tool_* 씬은 Build Settings 씬 목록에서 반드시 제외
• 씬 전환은 GameManager를 통해서만 수행 (직접 SceneManager.LoadScene 금지)

---

7. 서드파티 의존성

패키지	버전	용도	라이선스
com.unity.addressables	2.x	리소스 번들 관리	Unity
com.unity.nuget.newtonsoft-json	3.x	JSON 직렬화	MIT
com.unity.render-pipelines.universal	17.x	URP 렌더링	Unity
com.unity.textmeshpro	(번들)	UI 텍스트	Unity
(AntiCheatToolkit)	최신	메모리 변조 방어	구매
{추가 서드파티}	{버전}	{용도}	{라이선스}

서드파티 추가 규칙:

• 신규 서드파티 추가 시 공유/ 채널에 라이선스·용도·대안 검토 결과를 기록 (P15)
• ThirdParty/ 폴더에 격리하여 프로젝트 코드와 물리적으로 분리

---

8. 열린 결정 항목

항목	선택지	현재 상태
렌더 파이프라인	URP / Built-in	미결
백엔드 서비스	PlayFab / GameSparks / 자체 서버	미결
DI 추가 도구	ServiceLocator(Framework 내장) / VContainer	미결
비동기 패턴	async/await + CoroutineRunner / UniTask	미결

---

변경 이력

버전	일자	작성자	내용
v1	{날짜}	개발팀장	템플릿 초안