# 11. UI 아키텍처 — 수상한 잡화점

> **작성일**: 2026-04-17
> **작성자**: 개발팀장
> **상태**: v1 (초판, Phase 0-B 연계 문서)
> **대상**: `Assets/Script/UGUI/` 전수 (Ingame 19 + Lobby 19 + Common/Title/Util/Manager/BackKey 등)
> **관련 문서**: `08_전투시스템_SOT_v1.md`, `09_카드시스템_아키텍처_v1.md`, `10_데이터로딩_구조_v1.md`

---

## 1. 목적 (P18 §결정의 배경)

수상한 잡화점 UI 계층의 **구조·주요 매니저·상호작용 패턴**을 전수 식별하여:
1. 전투·카드·데이터 문서(08·09·10)에 이은 Phase 0-B 완결 (UI는 기획 밸런싱·시뮬레이션의 최종 표시 계층)
2. 코어 프레임워크 Tier 1 `BurningTimes.UI.UGUI`·`BurningTimes.UI.Components`에 흡수할 **범용 패턴 vs 프로젝트 특수 로직** 경계 확정 (C11)
3. UI 기획 연동·UX 검증 작업 시 영향 범위 식별에 필요한 **단일 SOT**

## 2. 전체 계층 구조

```
UGUI/
├── Manager/          UI 전역 매니저 계층 — 씬·팝업·로딩 브릿지
├── BackKey/          Android 뒤로가기 통합 처리
├── Common/           씬 공용 (GameUI, ScenarioUI, ToastUI, ControlUI 등)
├── Util/             SafeArea, UI 확장 컴포넌트
├── Title/            타이틀·로딩·공지·계정 진입 흐름
├── Lobby/            로비 씬 UI (19개 스크립트)
│   ├── LobbyUIManager        ← 로비 최상위 오케스트레이터
│   ├── LobbyTopUI, MoneyCard
│   ├── MainMenu/             영웅·카드·장비·미션·상점 (Base + 5개 탭)
│   ├── Attandance/           출석 보상
│   ├── CatTrade/             상점(고양이 상인) — 재화·장비·인장·메인 미션 통합 (11종)
│   ├── Explore/              탐험 — 지도·스테이지·보상 (7종)
│   ├── SeasonPass/           시즌 패스 (2종)
│   └── ETC/
├── Ingame/           전투·던전 씬 UI (19개 스크립트)
│   ├── IngameUIManager       ← 인게임 최상위 오케스트레이터 (153 LOC)
│   ├── DungeonProcess        ← 스테이지 진행 UI (67 LOC)
│   ├── SelectCardUI          ← 카드 선택 (290 LOC, 최대 UI 단일 모듈)
│   ├── BattleCard, BattleSmallCard, DeckUI, DeckUI_Skills, DeckUI_My4Spec
│   ├── GainCardList, IngameTopUI, SpecificityCard/List
│   ├── MerchantBuyPopup, PCMainStatUI, IngameMainStatCard
│   ├── Result/               DefeatUI, WinUI, StageClearRewards, ResultComon
│   └── ETC/
└── zTestUI/
```

## 3. 최상위 매니저 3종 — 오케스트레이션 책임

### 3-1. `LobbyUIManager` (Lobby/LobbyUIManager.cs, 202 LOC)
- 로비 씬 전체 UI 탭 전환·활성화 제어
- 탭 구성: MainMenu(영웅/카드/장비/미션/상점) · Attandance · CatTrade · Explore · SeasonPass
- 각 탭 자체 열림 상태·재진입 초기화 책임은 하위 UI에 위임하되, **탭 간 배타 활성은 본 매니저가 통제**

### 3-2. `IngameUIManager` (Ingame/IngameUIManager.cs, 153 LOC)
- 인게임(전투) 씬 UI 전역 오케스트레이터
- 주요 책임: `DungeonProcess` 연동, 전투 카드 스폰/회수, 결과 UI(Result/) 트리거
- 08 전투시스템 SOT 문서의 FSM 상태 전환 이벤트를 구독하여 UI 표시 갱신

### 3-3. `Title_Mgr` (Manager/Title_Mgr.cs)
- 타이틀 씬 진입 — 로딩·공지·계정 인증 흐름 제어
- `AddrResourceMgr`·`DataCheckMgr`와 협력 (Addressable 로드·마스터 데이터 체크)

## 4. 공통 UI 컴포넌트 (Common + Util)

| 컴포넌트 | 위치 | 범용성 | 프레임워크 흡수 대상 |
|---------|------|--------|--------------------|
| `GameUI` | Common/GameUI.cs | ★ 매우 높음 (UIView 추상화 출발점) | ✅ `BurningTimes.UI.UGUI.UIView` |
| `ScenarioUI` | Common/ScenarioUI.cs | △ 프로젝트 특수 (시나리오 시스템) | ❌ 프로젝트 유지 |
| `ToastUI` | Common/ToastUI.cs | ★ 매우 높음 | ✅ `BurningTimes.UI.Components` |
| `TouchBlockUI` | Common/TouchBlockUI.cs | ★ 매우 높음 | ✅ `BurningTimes.UI.Components` |
| `ControlUI`/`ControlUILock` | Common/ | ○ UI 입력 잠금 패턴 | ✅ `BurningTimes.UI.Components` |
| `MainStatCardBase` | Common/MainStatCardBase.cs | △ 프로젝트 카드 베이스 | ❌ 프로젝트 유지 |
| `ItemSimpleCard` | Common/ItemSimpleCard.cs | △ 프로젝트 아이템 카드 | ❌ 프로젝트 유지 |
| `SafeArea` | Util/ (추정) | ★ 매우 높음 | ✅ `BurningTimes.UI.Components.SafeArea` |
| `UIAtlasMgr` | UGUI/Manager/uScrollViewMgr 계열 | ★ 높음 | ✅ `BurningTimes.UI.UGUI.AtlasManager` |
| 무한 스크롤 (`uScrollViewMgr`·`uScrollViewArrMgr`) | UGUI/Manager/ | ★ 높음 | ✅ `BurningTimes.UI.UGUI.VirtualScroll` |

> 범용성 표기: ★=1순위 흡수 · ○=2순위 · △=프로젝트 특수 · ❌=범용 불가

## 5. 핵심 UI 모듈 — 카드 중심 설계

### 5-1. BattleCard / BattleSmallCard (Ingame)
- 전투 중 실제 표시되는 카드 UI. 09 카드시스템 아키텍처의 런타임 표시 계층
- 지속 인스턴스 풀링 대상 (프레임 당 다수 스폰/회수)

### 5-2. SelectCardUI (Ingame, 290 LOC — 최대 단일 UI 모듈)
- 카드 선택(획득 후보 3장 중 1장 선택) UI
- 제약 조건(C7 재미): 선택 시간·UX 피드백·희귀도 연출이 집약됨
- **프레임워크 흡수 비대상** — 프로젝트 특수 선택 규칙 (배제 조건·카드 풀 계산 등)

### 5-3. DeckUI 계열 (DeckUI, DeckUI_Skills, DeckUI_My4Spec)
- 데크·스킬·4스펙(고유 특성) 표시 UI
- 슬롯 기반 그리드 배치 패턴 → VirtualScroll·GridPool 흡수 후보

### 5-4. DungeonProcess (Ingame, 67 LOC)
- 스테이지 진행 UI — 맵 패턴·배틀·이벤트·보스 표시
- 맵 패턴 규칙(P17·기획팀 스테이지 설계)의 UI 표현 계층

## 6. 로비 기능별 UI 클러스터

### 6-1. MainMenu — 영웅·카드·장비·미션·상점 (5탭)
- `Base/`: 공통 베이스
- `1_Hero`·`2_Card`·`3_Equipment`·`4_Mission`: 각 탭 세부 (숫자 접두어 = 표시 순서)
- `MainMenu_Shop.cs`: 상점 탭(본 스크립트는 `5_Shop` 폴더가 아닌 루트에 존재 — 폴더 미정립)

### 6-2. CatTrade — 상점(고양이 상인) 통합 (11개 스크립트, 로비 내 최대 클러스터)
- 재화 거래(`CatTradeUI_Goods`)
- 장비 거래(`CatTradeUI_Equipment` + `CatTradeEquipmentBuyPopup` + `EquipmentTradeInvenCard`)
- 메인 미션(`CatTradeUI_MainMission`)
- 인장(`CatTradeUI_Seal` + `GetSealUI` + `SealRoulleteCard` + `SealSlotScroller`)
- 재화 카드(`CatTradeGoodsCard`)

### 6-3. Explore — 탐험 (7개 스크립트)
- 맵(`ExploreUI_Map`·`ExploreMapName`·`ExploreUI_Map_Cloud`(안개)): 맵 노드·구름 연출
- 스테이지(`ExploreUI_StageSelect`·`ExploreStageCard`): 노드 선택·카드 표시
- 보상(`ExploreRewardPopup`)

### 6-4. SeasonPass · Attandance
- 시즌 패스(`SeasonPassUI`·`SeasonPassCard`): 트랙·레벨·보상 표시
- 출석(`AttandanceUI`·`AttandanceCard`): 일일 보상 슬롯

## 7. BackKey 통합 처리

- `BackKey/` 디렉토리: Android `Escape` 키 통합 처리
- 열린 UI 스택 관리 → 가장 위 UI부터 순차 닫기
- **프레임워크 흡수 후보**: `BurningTimes.UI.UGUI.BackKeyDispatcher` (안드로이드 필수 패턴)

## 8. 프레임워크 Tier 1 흡수 계획 (범용성 ★ 우선)

차기 프로젝트 활용을 위한 **범용 UI 프레임워크** 구성 요소:

| 모듈 | 네임스페이스 | 수상한 잡화점 출처 |
|------|------------|------------------|
| UIView 추상 베이스 | `BurningTimes.UI.UGUI.UIView` | `Common/GameUI` |
| SafeArea | `BurningTimes.UI.Components.SafeArea` | `UGUI/Util/SafeArea` |
| Toast | `BurningTimes.UI.Components.Toast` | `Common/ToastUI` |
| 입력 차단 | `BurningTimes.UI.Components.InputBlocker` | `Common/TouchBlockUI`·`ControlUI` |
| 아틀라스 매니저 | `BurningTimes.UI.UGUI.AtlasManager` | `UGUI/Manager/UIAtlasMgr` |
| 무한 스크롤 | `BurningTimes.UI.UGUI.VirtualScroll` | `UGUI/Manager/uScrollView*Mgr` |
| BackKey 디스패처 | `BurningTimes.UI.UGUI.BackKeyDispatcher` | `BackKey/` |

## 9. 기획 연동 포인트 (UX 검증 시 영향 범위)

| 기획 변경 범주 | 영향 UI 모듈 |
|---------------|------------|
| 카드 조건·배타(P17) | `SelectCardUI`, `SpecificityCard/List` |
| 스테이지 맵 패턴 | `DungeonProcess`, `ExploreUI_Map`·`ExploreUI_StageSelect` |
| 보상 수치 | `ExploreRewardPopup`, `StageClearRewards`, `Result/WinUI` |
| 상점 재화 밸런스 | `CatTradeUI_*`, `MerchantBuyPopup`, `MoneyCard` |
| 시즌 패스 보상 트랙 | `SeasonPassUI`, `SeasonPassCard` |
| 출석 보상 | `AttandanceUI`, `AttandanceCard` |

## 10. 검증 방법 (P18 §검증)

1. 각 행의 파일 경로는 `Assets/Script/UGUI/{클러스터}/{파일명}.cs`에서 실존 확인 가능 (본 문서 작성 시 `ls`로 전수 확인 완료)
2. LOC 표기는 `wc -l` 결과 기준
3. 범용성 분류(★/○/△/❌)는 의존성 스캔(Unity 타입·게임 특수 enum 참조 여부)로 재검증 가능

## 11. 기각안 (P24 §기각안)

- **기각안 A: UIToolkit 병행 매핑 문서화** — 기획 방향이 UGUI 단일이므로 UIToolkit 매핑은 차기 프로젝트 R&D로 이관 (본 문서는 UGUI 전수 한정)
- **기각안 B: 각 스크립트 public API 메서드 전수 목록화** — 토큰 비용 과다 + 기획·검증 영향도 분류 목적에 불필요. 구조 수준 분류로 대체

## 부록 A. 변경 이력
- **v1 (2026-04-17)**: 초판. 개발팀장 Phase 0-B 완결 작업(B-4)으로 작성. Assets 전수 `ls` + 주요 파일 LOC 실측 기반.