# UVC 라이브러리 가이드

UVC(Unity View Components)는 프로젝트 전반에서 사용되는 공통 유틸리티, UI 컴포넌트, 데이터 처리 라이브러리입니다.

---

## 모듈 구조

```
UVC/
├── Core/           # DI, Injector 시스템
├── Data/           # 데이터 매핑, HTTP/MQTT 통신
├── DB/             # SQLite 데이터베이스
├── Edit/           # 3D 오브젝트 편집 (Gizmo, Selection)
├── Event/          # UniTask 기반 이벤트 핸들러
├── Extention/      # C# 확장 메서드
├── GLTF/           # GLTF 내보내기
├── Json/           # JSON 유틸리티
├── Linq/           # GameObject LINQ 확장
├── Locale/         # 다국어 지원
├── Log/            # 로깅 시스템
├── Network/        # HTTP 요청, Debounce
├── Object3d/       # 3D 인터랙션
├── Pool/           # 오브젝트 풀링
├── Tests/          # 단위 테스트
├── Threading/      # 메인 스레드 디스패처
├── UI/             # uGUI 기반 UI 컴포넌트
├── UIToolkit/      # UI Toolkit 기반 컴포넌트 ⭐
└── Util/           # 기타 유틸리티
```

---

## 핵심 모듈

### 1. Core - 의존성 주입 (DI)

```csharp
// 필드/프로퍼티에 [Inject] 어트리뷰트로 자동 주입
public class PlayerController : MonoBehaviour
{
    [Inject] private ILogService _logger;
    [Inject(Optional = true)] private IDebugService _debugService; // 선택적
}

// 서비스 등록
Injector.Register<ILogService, ConsoleLogger>(ServiceLifetime.App);
```

**주입 시점:**
- MonoBehaviour: `InjectorSceneContext.PerformSceneInjection()`
- 순수 C#: 인스턴스 생성 직후
- 수동: `Injector.Inject(target)`

### 2. Data - 데이터 매핑 시스템

JSON 데이터를 `DataObject`/`DataArray`로 변환하는 매핑 시스템입니다.

```csharp
// DataMask로 타입 정의
var mask = DataMask.Parse(@"{ ""name"": """", ""age"": 0 }");
mask.ObjectIdKey = "name";

// DataMapper로 변환
var mapper = new DataMapper(mask);
DataObject result = mapper.Map(sourceJson);

// 풀링 지원
var obj = DataObjectPool.Get();
obj.ReturnToPool(); // 사용 후 반환
```

**주요 클래스:**
- `DataMapper`: JSON → DataObject 변환
- `DataMask`: 타입 정의 마스크
- `DataObject/DataArray`: 통합 데이터 컨테이너
- `DataObjectPool/DataArrayPool`: 메모리 풀링

### 3. Pool - 오브젝트 풀링

```csharp
// GameObjectPool 사용
var pool = new GameObjectPool<Bullet>(bulletPrefab, container);

// 풀에서 가져오기
Bullet bullet = pool.GetItem("bullet_1");

// 풀에 반환
pool.ReturnItem("bullet_1");

// 통계 확인
Debug.Log(pool.GetStats()); // 최대 사용량, 현재 사용량, 풀 미스 횟수
```

### 4. UI - uGUI 컴포넌트

#### Modal 시스템
```csharp
// 모달 열기
var content = new ModalContent("Prefabs/UI/ConfirmModal")
{
    Title = "확인",
    Message = "정말 삭제하시겠습니까?"
};
bool confirmed = await Modal.Open<bool>(content);

// 모달 닫기
await Modal.Close();
```

#### Tab 시스템
```csharp
// TabView 초기화
tabView.InitializeTabs(tabs, configs, OnTabSelected, togglable: false);

// 탭 전환
await tabView.UpdateActiveTab(tabIndex, prevIndex, tabData);
```

### 5. UIToolkit - UI Toolkit 컴포넌트 ⭐

**권장**: 새 UI는 이 모듈의 컴포넌트를 사용하세요.

#### 리스트 컴포넌트
| 클래스 | 용도 |
|--------|------|
| `UTKTreeList` | 트리 구조 리스트 |
| `UTKAccordionList` | 접이식 리스트 |
| `UTKComponentList` | 컴포넌트 리스트 |
| `UTKImageList` | 이미지 리스트 |

#### 모달 컴포넌트
| 클래스 | 용도 |
|--------|------|
| `UTKColorPicker` | 색상 선택기 |
| `UTKColorPickerHSV` | HSV 색상 선택기 |
| `UTKDatePicker` | 날짜 선택기 |
| `UTKModalBlocker` | 모달 배경 차단 |

#### Property 시스템
```csharp
// PropertyWindow에서 다양한 속성 타입 지원
UTKStringPropertyItem   // 문자열
UTKIntPropertyItem      // 정수
UTKFloatPropertyItem    // 실수
UTKBoolPropertyItem     // 불리언
UTKVector2/3PropertyItem // 벡터
UTKColorPropertyItem    // 색상
UTKDatePropertyItem     // 날짜
UTKEnumPropertyItem     // 열거형
UTKDropdownPropertyItem // 드롭다운
UTKRadioPropertyItem    // 라디오 버튼
```

### 6. Network - HTTP/디바운스

```csharp
// 디바운스 요청 (실시간 검색 등)
var requester = new DebounceRequester();

void OnSearchTextChanged(string text)
{
    requester.Request<SearchResult>(
        300,  // 300ms 디바운스
        "/api/search",
        "get",
        $"{{\"query\": \"{text}\"}}",
        null,
        useAuth: true,
        result => DisplayResults(result)
    );
}

// 리소스 해제 필수
requester.Dispose();
```

### 7. Extention - 확장 메서드

| 파일 | 확장 대상 |
|------|-----------|
| `DictionaryEx` | Dictionary |
| `ImageEx` | Image |
| `LayoutGroupEx` | LayoutGroup |
| `NumberEx` | 숫자 타입 |
| `OrderedDictionary` | 순서 유지 딕셔너리 |
| `RectTransformEx` | RectTransform |
| `StringEx` | string |
| `TransformEx` | Transform |
| `TMP_InputFieldEx` | TMP_InputField |

### 8. Linq - GameObject 확장

```csharp
// 자식 순회
foreach (var child in gameObject.Children()) { }

// 조건부 검색
var buttons = gameObject.Descendants<Button>().Where(b => b.interactable);

// 부모 검색
var canvas = gameObject.Ancestors<Canvas>().FirstOrDefault();
```

---

## 사용 지침

### 새 UI 개발 시
1. **UIToolkit 모듈 사용** (`UVC/UIToolkit/`)
2. UXML/USS로 구조/스타일 분리
3. `UTK*` 접두사 클래스 활용

### 데이터 처리 시
1. `DataMapper` + `DataMask`로 JSON 매핑
2. `DataObjectPool`/`DataArrayPool`로 메모리 최적화
3. 사용 후 `ReturnToPool()` 호출

### 서비스 개발 시
1. 인터페이스 정의 (`IMyService`)
2. `InjectorAppContext` 또는 `InjectorSceneContext`에서 수동 등록
3. `[Inject]`로 주입 받기

> **참고**: `[Register]` 어트리뷰트는 향후 자동 스캔용으로 정의되어 있으나, 현재는 수동 등록이 필요합니다.

### 네트워크 요청 시
1. 연속 요청은 `DebounceRequester` 사용
2. `CancellationToken` 전달
3. 리소스 해제 (`Dispose()`) 필수

---

## 네이밍 규칙

| 접두사 | 의미 |
|--------|------|
| `UTK*` | UI Toolkit 컴포넌트 |
| `Data*` | 데이터 처리 클래스 |
| `I*` | 인터페이스 |
| `*Pool` | 풀링 클래스 |
| `*Ex` | 확장 메서드 클래스 |

---

## 테스트

```
UVC/Tests/
├── Editor/
│   └── Data/
│       ├── DataArrayTests.cs
│       ├── DataMapperTests.cs
│       ├── DataObjectTests.cs
│       ├── HttpDataFetcherTests.cs
│       └── MqttDataReceiverTests.cs
└── MockHttpRequester.cs
└── MockMQTTService.cs
```

에디터 테스트 실행: `Window > General > Test Runner`