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

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

---

## 1. 프로젝트 기본 정보

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

---

## 2. 어셈블리(asmdef) 구성

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

| asmdef | 경로 | 의존 |
|--------|------|------|
| `{ProjectNamespace}.Core` | `Assets/Scripts/{ProjectNamespace}/Core/` | BT.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, BT.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         ← 에디터 도구 (런타임 제외)
```

**BurningTimes 네임스페이스와 분리 원칙**:
- `BurningTimes.*` = 프레임워크 영역 (수정 불가)
- `{ProjectNamespace}.*` = 프로젝트 전용 영역
- 두 영역의 혼합 사용 금지

---

## 5. 매니저/시스템 목록

| 클래스 | 역할 | 라이프사이클 | Framework 의존 |
|--------|------|-------------|---------------|
| `GameManager` | 게임 전체 상태 관리, 씬 전환 총괄 | `MonoSingleton<T>` (Persistent) | ✅ |
| `DataManager` | DataTable 로딩·캐시 관리 | `MonoSingleton<T>` (Persistent) | ✅ |
| `UIManager` | UI View 스택·전환 관리 | `MonoSingleton<T>` (Persistent) | ✅ |
| `AudioManager` | BGM/SFX 재생 | `BurningTimes.Audio` 위임 | ✅ |
| `ServerManager` | 서버 통신 추상화 | `ServiceLocator` | ✅ |
| `SaveManager` | 세이브/로드 | `ServiceLocator` + `BurningTimes.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 | {날짜} | 개발팀장 | 템플릿 초안 |