BurningTimesAi/프로젝트/코어프레임워크/02_수상한잡화점_추출대상_v1.md

# 수상한 잡화점 — BT.Framework 추출 대상 선별

> 🟢 **2026-04-17 완료 실적 아카이브 — Tier 1 16/16 반영 종료**
>
> 본 문서는 수상한 잡화점 소스에서 코어 프레임워크로 추출할 대상을 식별한 **원 가이드**로, Tier 1 기반 Core 4종 + Attribute 3종 + Util 6종 + Event 2종 + Container 3종 + Data 5종 = **총 19 파일·16 모듈 구현 완료** 시점(2026-04-17)에 "완료 실적" 성격으로 전환됨. 각 추출 항목은 아래 본문에서 구현 위치 역참조로 연결됨 (📦 표기). 구현 상세는 [`코어코드/BT.Framework/CHANGELOG.md`](../../코어코드/BT.Framework/CHANGELOG.md) 참조.
>
> 차기 프로젝트에서 Tier 2(Addressable·UGUI·Security)·Tier 3(Network) 추가 추출 시 본 문서 구조(A/B/C/D 등급 분류·변형 포인트·네이밍 규칙)를 재사용 가능 (헌법 제1원칙 목표 2 원칙 A).

> **작성일**: 2026-04-14
> **상위 문서**: `01_아키텍처_개요_v1.md`
> **목적**: 수상한 잡화점 Unity 프로젝트 코드에서 신규 코어로 편입할 범용 패턴 식별·분류
> **원칙**: **코드·구조 참고는 가능, 네이밍은 재작성 필수** (PD님 확정)
> **주의**: 수상한 잡화점 프로젝트에는 이 코어를 적용하지 않음. **추출은 다음 프로젝트에서 사용할 코어용**.

---

## 1. 등급 분류

| 등급 | 의미 | 조치 |
|------|------|------|
| **A. 즉시 추출** | 범용성 높음 + 의존성 최소 | 코어에 바로 재작성 편입 |
| **B. 프레임워크 래핑** | 패턴은 범용, 단순화·제네릭화 필요 | 구조 참고 + 재설계 |
| **C. 선별 추출** | 게임 로직과 범용 로직 혼재 | 범용 메서드만 분리 흡수 |
| **D. 도메인 잔류** | 프로젝트 특수 개념 다수 | 코어 편입 제외, 프로젝트에 남김 |

## 2. 분류표 (13+개 대상 파일)

### A. 즉시 추출 (6개)

| # | 원본 | 줄 수 | 신규 위치 | 변형 포인트 | 구현 상태 |
|---|------|------|----------|------------|---------|
| 1 | `My/MyCoroutine.cs` | 52 | `BurningTimes.Core.Coroutine.CoroutineRunner` | 기존 BurningTimesCore `CoroutineHandler`와 통합, 일시정지·재시작·중복방지 1종 API | ✅ 2026-04-16 — 📦 `Runtime/Core/Coroutine/CoroutineRunner.cs` |
| 2 | `My/CryptoUtil.cs` | 86 | `BurningTimes.Security.CryptoUtil` (Tier 3 합류 시점) | **AES 키 하드코딩 제거 필수**, `ICryptoProvider` 인터페이스 뒷받침, 키 주입 방식 | ⏸ Tier 3 대기 |
| 3 | `Addressable/AddrHandleBase.cs` | 102 | `BurningTimes.Addressable.AddressableHandle<T>` (Tier 2) | 참조 카운팅·Preload/Unload 정책 부가 | ⏸ Tier 2 대기 |
| 4 | `Addressable/AddressableReleaseSelf.cs` | 8 | `BurningTimes.Addressable.AutoReleaseComponent` (Tier 2) | OnDestroy 훅 재작성, 주석처리 코드 제거 | ⏸ Tier 2 대기 |
| 5 | `UGUI/Util/SafeArea.cs` | 17 | `BurningTimes.UI.Components.SafeAreaBorder` | 기존 UIToolkit 버전과 병존, UGUI RectTransform 대응 | ⏸ Tier 2(UI) 대기 |
| 6 | `Manager/ErrorLogHookManager.cs` | 42 | `BurningTimes.Core.Util.Log` 내부 훅 | `Log` 카테고리·필터와 통합, `#if FGB_LIVE` 같은 프로젝트 플래그 제거 | ✅ 2026-04-16 — 📦 `Runtime/Core/Log/` 통합 |

### B. 프레임워크 래핑 (2개)

| # | 원본 | 줄 수 | 신규 위치 | 변형 포인트 | 구현 상태 |
|---|------|------|----------|------------|---------|
| 7 | `Template/MonoBehaviourSingletonTemplate.cs` | 30 | `BurningTimes.Core.Patterns.MonoSingleton<T>` | 4종 싱글톤(Sync/Async/Ready/Inner) 통합 (01문서 4-1 참조). `MonoBehaviourSingletonuScrollViewMgr<T>` 같은 변종 제거 | ✅ 2026-04-16 — 📦 `Runtime/Core/Patterns/MonoSingleton.cs` + `ServiceLocator.cs` |
| 8 | `UGUI/BackKey/BackKeyAdd.cs` | 67 | `BurningTimes.UI.UGUI.BackKeyHandler` | `BackKeyMgr` 싱글톤 의존을 구독 패턴으로 재설계, 스택 기반 백키 처리 | ⏸ Tier 2(UI) 대기 |

### 🆕 2026-04-17 Tier 1 확장 구현 (본 원 가이드 범위 외 추가 추출)

Tier 1 완결을 위해 원 가이드에 없던 모듈 9종을 추가 설계·구현. 수상한잡화점 소스 역추적이 아닌 **차기 프로젝트 범용성을 목적으로 한 신규 설계** (C11 범용성 원칙).

| 범주 | 모듈 | 구현 위치 | 근거 설계 |
|------|------|----------|---------|
| **Attribute** 3종 | `ReadOnlyAttribute`·`ShowIfAttribute`·`ArrayTitleAttribute` | 📦 `Runtime/Core/Attribute/` | 인스펙터 UX 공통 패턴 |
| **Util** 6종 | `EnumToInt`(#12 일반화)·`EnumEx`·`FormatEx`·`MathEx`·`KeyMaker`·`ValidationEx`(#9 일반화) | 📦 `Runtime/Core/Util/` | 박싱 회피 `Unsafe.As<,>`, `:` 구분자 표준, 순수 BCL |
| **Event** 2종 | `EventBus`·`Raw/RawEventBus` | 📦 `Runtime/Core/Event/` | `04_Tier1_3종_상호작용_설계_v1.md` §3 |
| **Container** 3종 | `ObservableList`·`ObservableDictionary`·`ObservableQueue` | 📦 `Runtime/Core/Container/` | 기존 `UniList`·`UniEventList`·`UniObserverList` 3종 통합 대체, 세분화 이벤트 |
| **Data** 5종 | `IDataRow`·`DataTable`·`DataTableSO`·`DataTableLoader`·`DataTableLoadedEvent` | 📦 `Runtime/Core/Data/` | 기존 `MasterTableBase` 재설계, 제네릭 키, RFC 4180 최소 CSV + JsonUtility |

**테스트**: NUnit 기반 총 19+ 파일 (`Tests/Runtime/Core/{Attribute,Util,Event,Container,Data}/*Tests.cs`).

### C. 선별 추출 (4개 — 범용 메서드만 취함)

#### 9. `My/DSUtil.cs` (1,406줄)
프로젝트 강결합(게임 테이블 참조, `ObscuredTypes` 의존, 게임 stage 로직)이 상당함. **범용 메서드만 흡수**.

| 추출 후보 메서드 | 신규 위치 | 비고 |
|----------------|----------|------|
| `CheckNull`, `Get_Clone`, `Format` | `BurningTimes.Core.Util.ValidationEx` / `ObjectEx` / `FormatEx` | |
| `StringToEnum<T>` | `BurningTimes.Core.Util.EnumEx` | 캐시 적용 |
| `LogError` 변종 | `BurningTimes.Core.Util.Log` | 중앙 로거로 통합 |
| **제외** | `GetStageInfo`, `ActorInfo`류, 테이블 조회 | 수상한 잡화점 전용, 프로젝트 잔류 |

#### 10. `UGUI/Manager/uScrollViewMgr.cs` + `uScrollViewArrMgr.cs` (합 116줄)
- **추출**: 무한 스크롤 프레임워크 뼈대 (`Set_ScrollView<T>`, `ScrollTo`)
- **제거**: `CardBase`, `DSUtil` 의존, 프로젝트 특화 `ClickCard`/`Select_Card`
- **신규 위치**: `BurningTimes.UI.UGUI.InfiniteScrollView<T>`
- **변형**: 제네릭 데이터 바인딩 인터페이스(`IScrollItem<T>`)로 재설계

#### 11. `UGUI/Manager/UIAtlasMgr.cs` (29줄)
- **추출**: `Set()`, `Get_Sprite()` 스프라이트 아틀라스 관리
- **제거**: `Get_EquipmentGrade_Sprite()`, `Get_CardGrade_Sprite()` (게임 특수)
- **신규 위치**: `BurningTimes.UI.UGUI.SpriteAtlasRegistry`

#### 12. `My/MyEnumToInt.cs` (51줄)
- **추출**: Enum → Int 캐싱 패턴 (박싱 회피)
- **신규 위치**: `BurningTimes.Core.Util.EnumToInt<T>`
- **변형**: `MyEnum` 구체 의존 제거, 제네릭 타입 파라미터로 일반화

### D. 도메인 잔류 (추출 제외, 프로젝트에 남김)

| 원본 | 사유 |
|------|------|
| `My/MyEnum.cs` (463줄) | 23개 enum 전부 수상한 잡화점 특수 (`eStageNodeType`, `eStat`, `eStatusConditionsType` 등). **C11 오염, 코어 편입 금지** |
| `My/MyValue.cs` (802줄) | 게임 테이블·스테이지 데이터 강결합. 프로젝트 설정값 모음 |
| `My/MyText.cs` | `eStat`/`eElement` 로컬라이제이션 — 게임 특수 |
| `UGUI/Common/GameUI.cs` | `EffectMgr`/`MyValue` 강결합, 게임 이펙트 로직 |
| `UGUI/Common/ControlUI.cs` | `eControlUi` 게임 특수 enum |
| `UGUI/Common/ScenarioUI.cs` (43KB) | 시나리오 이벤트 시스템, 프로젝트 특화 |
| `UGUI/Common/TouchBlockUI.cs` | (재확인 필요 — 범용성 검토 후 추출 여부 재판정) |

## 3. 추출 시 공통 정리 원칙

### 3-1. 네이밍 규칙
- `My*` 접두사 전면 제거 (`MyCoroutine` → `CoroutineRunner`)
- `u*` 소문자 시작 접두사 제거 (`uScrollViewMgr` → `InfiniteScrollView`)
- `Mgr`, `_Mgr` 축약 → 풀 네임 (`Mgr` → `Manager`, 단 통용 시 유지 가능)
- `_` 구분자 제거, PascalCase 준수 (`Set_Coroutine` → `SetCoroutine`)
- `Regist*` 오탈자 → `Register*`
- 기존 `FilGoodBandits` 네임스페이스 모두 → `BurningTimes.*` 로 재작성

### 3-2. 의존성 단절
- 수상한 잡화점 전용 enum/class 참조 전부 제거
- `ObscuredInt` / `ObscuredLong` (ACTk) 참조는 선택 레이어로 재설계 (`INumericProtection`)
- 테이블 조회(`table_*`) 참조 제거, 데이터 추상 인터페이스(`IDataTable`)로 대체

### 3-3. 변형 방향
- **싱글톤 감소**: 필요 최소 외에는 순수 클래스 + DI 패턴 친화로
- **이벤트 기반 통신**: `EventBus` 적극 활용, 강결합 매니저 참조 회피
- **제네릭 우선**: `UIAtlasMgr`처럼 특정 도메인 하드코딩된 메서드는 제네릭 팩토리로 재설계

## 4. 추출 우선순위 (Tier 1 구현 순서 제안)

| 순번 | 추출 대상 | Tier | 이유 |
|------|----------|------|------|
| 1 | MyCoroutine → CoroutineRunner | 1 | 다른 모듈이 의존하는 기반 |
| 2 | MonoBehaviourSingletonTemplate → MonoSingleton | 1 | 전반적으로 쓰임 |
| 3 | DSUtil 일부 → ValidationEx/ObjectEx/FormatEx/EnumEx | 1 | 유틸 기반 |
| 4 | MyEnumToInt → EnumToInt | 1 | 성능 유틸 |
| 5 | SafeArea (UGUI 버전) → SafeAreaBorder | 1 | UGUI 주력 방침 반영 |
| 6 | UIAtlasMgr → SpriteAtlasRegistry | 1 | UGUI 기본 인프라 |
| 7 | ErrorLogHookManager → Log 훅 통합 | 1 | 로깅 인프라 |
| 8 | BackKeyAdd → BackKeyHandler | 1 | UGUI 주력 관련 |
| 9 | uScrollView → InfiniteScrollView | 1 | 복잡도 중간 |
| 10 | AddrHandleBase → AddressableHandle | 2 | Addressable 모듈 |
| 11 | CryptoUtil → CryptoUtil (+ICryptoProvider) | 3 | 서버팀 합류 시점 |

## 5. 추출 후 수상한 잡화점 자체 정리 (별도 과제)

수상한 잡화점 프로젝트는 새 코어를 **적용하지 않지만**, 추출 과정에서 드러난 오염은 기록해 둠.

### 발견된 C11 관점 문제 (수상한 잡화점 내부)
- **네임스페이스 부재**: 대부분 global namespace (SafeArea.cs만 `FilGoodBandits`)
  → 장기 리팩토링 대상 (우선순위 낮음, 기능에는 영향 없음)
- **`My*`, `u*` 접두사 혼재**: 일관성 부족
- **매니저 싱글톤 과다**: `uScrollViewMgr`, `UIAtlasMgr`, `BackKeyMgr`, `EffectMgr`, `ProjectileMgr` 등 → 결합도 높음
- **DSUtil 거대화(1,406줄)**: 유틸과 게임 로직이 혼재 → 장기 분해 대상

이 문제들은 **이번 프로젝트에서 손대지 않음** (개발 중단 리스크). 추출 과정에서만 반영.

## 6. 다음 작업

| # | 작업 | 선행 조건 |
|---|------|----------|
| 1 | PD님과 NAS Git 저장소 위치·접근 방식 협의 | 없음, 즉시 가능 |
| 2 | 패키지 스켈레톤 생성 (`package.json`, `asmdef`, 폴더 틀) | 저장소 위치 확정 |
| 3 | Tier 1 구현 시작 (위 4절 순번 1번부터) | 스켈레톤 완료 |
| 4 | 수상한 잡화점 개발 준비 (Phase 0-B/C) 재개 | Tier 1·2 진행 중 병행 가능 여부는 PD님 판단 |