# 12. 메타시스템 — 수상한 잡화점

> **작성일**: 2026-04-17
> **작성자**: 개발팀장
> **상태**: v1 (초판, Phase 0-B 연계 문서)
> **대상**: 세이브/로드 · 진행도 · 상점 · 성장(장비·각성·인장) · 시즌패스 · 탐험 · 출석
> **관련 문서**: `05_서버연동_현황_v1.md`, `09_카드시스템_아키텍처_v1.md`, `10_데이터로딩_구조_v1.md`, `11_UI아키텍처_v1.md`

---

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

수상한 잡화점의 **비전투(메타) 시스템** 전체 계층을 식별하여:
1. 전투(08) · 카드(09) · 데이터(10) · UI(11)에 이은 Phase 0-B 최종 완결
2. 서버 역할 문서(05·PD 지시 #30·#31)와의 **메타 시스템 측 대응표** 제공
3. 차기 프로젝트 프레임워크 `NerdNavis.Save`·`NerdNavis.Economy` Tier 2 설계에 필요한 **실증 패턴** 공급
4. 기획 밸런싱·유저 경험 변경 시 **영향 범위 식별 SOT**

## 2. 메타시스템 전체 맵

```
메타시스템 = "전투 외 유저 진행·성장·경제 시스템"

┌─────────────────────────────────────────────────────────────┐
│  클라이언트 로컬 상태 (Assets/Script/Info/)                   │
│  ├── ActorInfo        — 캐릭터·영웅 상태                      │
│  ├── InGameInfo       — 인게임 진행 상태                       │
│  ├── InappInfo        — 인앱 결제 영수증·트랜잭션              │
│  ├── OptionInfo       — 유저 옵션(사운드·언어·그래픽)          │
│  ├── TitleInfo        — 타이틀·공지                            │
│  ├── ADInfo           — 광고 상태                              │
│  ├── SoundInfo, WebViewInfo, UtilInfo, Popup, NetWait        │
│  └── (*.Info 단일 데이터 클래스 + 매니저 스타일)                │
└─────────────────────────────────────────────────────────────┘
                  ↕ (마스터 테이블 조회, 10 문서)
┌─────────────────────────────────────────────────────────────┐
│  서버 연동 (Assets/Script/Server/)                            │
│  ├── ServerClass.cs   — 서버 응답/요청 DTO                    │
│  ├── ServerInfo.cs    — 서버 상태·세션 관리                   │
│  └── (PlayFab 전제, 05 문서 및 서버 지시서 v1.1/v1.2 참조)    │
└─────────────────────────────────────────────────────────────┘
                  ↕ (UI 표시, 11 문서)
┌─────────────────────────────────────────────────────────────┐
│  UI 계층 (Assets/Script/UGUI/Lobby/)                          │
│  └── 본 문서 §4 각 시스템별 UI 매핑                            │
└─────────────────────────────────────────────────────────────┘
```

## 3. 세이브/로드 구조

### 3-1. 현 구조 (PlayFab 중심)
- **원본**: PlayFab(`UserData`/`TitleData`/`PlayerStatistics`) — 서버 지시서 v1.1 §4·§5 기준
- **로컬 캐시**: `Info/*.Info` 각 클래스 내부에 필드 보존 + 필요 시 `PlayerPrefs` 부분 저장(옵션·로컬 전용)
- **인코딩**: JSON(PlayFab 기본 직렬화) + `My/CryptoUtil.cs` 적용분은 일부 (세이브 전반 체계화 안 됨)

### 3-2. 약점·리스크
1. **SOT 분리 모호** — `*.Info` 클래스가 "런타임 상태 + 저장 대상" 이중 역할
2. **세이브 스키마 버전 관리 부재** — 필드 추가/제거 시 마이그레이션 전략 없음
3. **로컬/서버 동기화 타이밍이 호출부에 산재** — 조회 시마다 서버 호출 or 캐시 사용 판단 분산

### 3-3. Tier 2 `NerdNavis.Save` 설계 반영 포인트
- `ISaveProvider` 인터페이스 (PlayerPrefs / JSON / 암호화 / 클라우드)
- 버전 마이그레이션 훅(`IMigration`) 신설
- 세이브 대상 POCO와 런타임 상태 클래스 분리 (DTO 패턴)

## 4. 진행도 · 성장 · 경제 시스템 (영역별)

### 4-1. 영웅·카드·장비·각성·인장 (성장)

| 시스템 | 클라 코드 위치 | UI 클러스터 | 마스터 테이블 |
|--------|--------------|-----------|-------------|
| 영웅 (Hero) | `Info/ActorInfo.cs` + 스킬·스펙 서브 | `Lobby/MainMenu/1_Hero/` | Hero, Skill, HeroSkill |
| 카드 (Card) | 09 문서 런타임 모듈 + `Info/` | `Lobby/MainMenu/2_Card/` | Card, CardEffect |
| 장비 (Equipment) | `Info/`·CatTrade 관련 | `Lobby/MainMenu/3_Equipment/`·`Lobby/CatTrade/CatTradeUI_Equipment.cs` | Equipment, EquipmentOption |
| 미션 (Mission) | `Info/`·`CatTradeUI_MainMission` | `Lobby/MainMenu/4_Mission/`·`Lobby/CatTrade/CatTradeUI_MainMission.cs` | Mission, MissionReward |
| 인장 (Seal) | CatTrade Seal 서브 | `Lobby/CatTrade/CatTradeUI_Seal.cs`·`GetSealUI.cs`·`SealRoulleteCard.cs`·`SealSlotScroller.cs` | Seal, SealOption |

### 4-2. 상점 (CatTrade — 고양이 상인)
- **구조**: 단일 상인이 5개 카테고리(재화·장비·인장·메인 미션 + 공통 Goods) 통합 제공
- **UI 클러스터**: `Lobby/CatTrade/` 11개 스크립트 (로비 최대 클러스터, 11 문서 §6-2 참조)
- **특수 로직**:
  - 인장 룰렛(`SealRoulleteCard`·`SealSlotScroller`): 슬롯머신 연출 — 확률 기반 획득
  - 장비 구매 팝업(`CatTradeEquipmentBuyPopup`) + 기존 보유 장비 비교(`EquipmentTradeInvenCard`)

### 4-3. 탐험 (Explore — 스테이지 선택)
- **구조**: 맵 → 스테이지 노드 선택 → 전투 진입 or 이벤트
- **UI 클러스터**: `Lobby/Explore/` 7개 스크립트 (11 문서 §6-3)
- **저장 대상**:
  - 현재 탐험 지도 ID·해제된 노드
  - 각 노드 클리어 여부·최고 스코어(3성 조건 달성)
  - 탐험 보상 수령 이력
- **P17 연계**: 스테이지별 ★ 조건 배치는 마스터 테이블(기획팀 `Stage`·`StarCondition`)에서 읽어 `ExploreUI_StageSelect`에 표시

### 4-4. 시즌 패스
- **UI**: `Lobby/SeasonPass/SeasonPassUI.cs`·`SeasonPassCard.cs`
- **저장 대상**: 현재 시즌 ID·시즌 진행도 경험치·무료/유료 트랙별 수령 레벨
- **서버 동기화 필요**: 시즌 교체·유료 트랙 결제 영수증 (PlayFab)

### 4-5. 출석
- **UI**: `Lobby/Attandance/AttandanceUI.cs`·`AttandanceCard.cs`
- **저장 대상**: 현재 월/회차·연속 출석일·수령 이력
- **서버 시간 의존**: 날짜 조작 방지 위해 서버 시간 기준 (서버 지시서 §3 참고)

## 5. 재화·경제 시스템

### 5-1. 재화 종류
- 수상한 잡화점은 **복수 재화 체계** (골드·다이아·이벤트 화폐·카드 조각 등)
- 현 구조: `Info/*.Info` 내 변수 + 마스터 테이블 `Goods`·`Currency` 참조 추정
- 표시 UI: `Lobby/LobbyTopUI.cs` + `Lobby/MoneyCard.cs` + 인게임 `IngameTopUI.cs`

### 5-2. 획득 경로
- 전투 클리어(`Ingame/Result/StageClearRewards`)
- 탐험 보상(`Lobby/Explore/ExploreRewardPopup`)
- 상점 구매(`Lobby/CatTrade/MerchantBuyPopup` 포함)
- 인앱 결제(`Info/InappInfo.cs` + PlayFab 영수증 검증)
- 광고 시청(`Info/ADInfo.cs`)
- 출석·시즌 패스 보상

### 5-3. 차기 프로젝트 흡수 (`NerdNavis.Economy`)
- `Goods` 범용 재화 모델 (타입·수량·최대치·오버플로 정책) — 01 설계안 §6-0 기정립
- 인벤토리·획득 이벤트 훅(`EventBus` 연동)
- **본 프로젝트 특수 로직(재화 종류·상점 UX)은 흡수 불가** — 프레임워크는 "재화 모델 컨테이너"만 제공

## 6. 서버 연동 상태 (05 문서 연계)

### 6-1. 현 서버 범위 (PlayFab)
- 세션/인증 → `ServerInfo.cs`
- 유저 데이터 로드/저장 → `ServerClass.cs` DTO 매핑
- 스테이지 결과 기록 → `Save_StageResult` API (서버 지시서 §6 샘플)
- 인앱 영수증 검증 → PlayFab 영수증 검증

### 6-2. 서버 역할 경계 (서버 지시서 §5·§6)
- **클라 100% 책임**: 어뷰징 판정 (`is_abuse_flag`만 서버 전송, 경계값 보관·검증 안 함)
- **서버 100% 책임**: 시간 기반 판정(출석·시즌 만료) · 영수증 검증 · 로그 집계
- **양쪽 책임**: 세이브 동기화 (클라 전송 + 서버 검증 최소 필터)

## 7. 메타시스템 의존성 그래프 (핵심 흐름)

```
로그인 → Title_Mgr
    ↓ (서버 인증 → PlayFab)
ServerInfo.Login → *.Info 다중 로드
    ↓ (마스터 테이블 로드, 10 문서)
DataCheckMgr·AddrResourceMgr
    ↓
LobbyUIManager.Initialize
    ├→ LobbyTopUI (재화 표시)
    ├→ MainMenu (영웅·카드·장비·미션 탭)
    ├→ CatTrade (상점 진입)
    ├→ Explore (탐험 진입)
    │    ↓ (스테이지 선택)
    │    IngameUIManager → 08 전투 FSM
    │    ↓ (전투 종료)
    │    StageClearRewards → *.Info 갱신 → ServerClass 전송
    │    ↓
    │    LobbyUIManager 복귀
    ├→ SeasonPass / Attandance (보상 수령)
    └→ Option/WebView 등
```

## 8. 기획 연동 포인트 (밸런싱·UX 변경 영향 범위)

| 기획 변경 범주 | 영향 메타 모듈 |
|---------------|--------------|
| 재화 밸런스 (획득량·환율) | `Info/*.Info` 재화 필드 + `LobbyTopUI`·`MoneyCard`·`IngameTopUI` + 상점 UI 전체 |
| 성장 곡선 (장비 레벨·인장 등급) | `MainMenu_Equipment`·`CatTrade Seal 계열` + 마스터 테이블 `Equipment`·`Seal` |
| 시즌 패스 트랙 구성 | `SeasonPassUI`·`SeasonPassCard` + 서버 시즌 ID 갱신 |
| 출석 보상 트랙 | `AttandanceUI`·`AttandanceCard` + 서버 시간 의존 |
| 탐험 맵 구조 (노드·분기) | `ExploreUI_Map`·`ExploreStageCard` + 마스터 `ExploreMap`·`Stage` |
| 상점 가격·확률 (룰렛 등) | `CatTrade*` 전체 + 마스터 `Shop`·`Seal` |

## 9. 프레임워크 흡수 계획 (Tier 2 설계 반영)

| 프레임워크 모듈 | 수상한 잡화점 출처 | 흡수 수준 |
|--------------|------------------|---------|
| `NerdNavis.Save.ISaveProvider` | 현 `*.Info` + PlayFab 호출 패턴 | 🟡 신규 인터페이스 (기존 구조는 참고만) |
| `NerdNavis.Save.IMigration` | 없음 (부재 자체가 교훈) | 🔴 신규 설계 |
| `NerdNavis.Economy.Goods` | `MoneyCard`·재화 Info 필드 | 🟢 구조 계승, 네이밍만 변경 |
| `NerdNavis.Economy.Inventory` | 장비·인장·카드 목록 패턴 | 🟡 범용 컨테이너 추출 |
| `NerdNavis.Network.IReceiptVerifier` | `Info/InappInfo.cs` + PlayFab 영수증 | 🟡 Tier 3 편입 (서버팀 합류 시점) |

## 10. 현 프로젝트에서의 차기 개선 안건 (차기 프로젝트 참고 자료)

> 헌법 제1원칙 목표 2 원칙 B: 수상한 잡화점 인사이트를 차기 프로젝트 참고 자료로.

1. `*.Info` 단일 클래스에 "런타임 상태 + 직렬화 대상 + 서버 통신 DTO"를 모두 담는 구조는 차기 프로젝트에서 **반드시 분리** (DTO + 상태 + 리포지토리 3계층)
2. 세이브 버전 관리 부재 → 차기 프로젝트 `IMigration` 훅 필수
3. 서버/클라 동기화 타이밍이 호출부에 분산 → 차기 프로젝트는 **중앙 동기화 매니저** 도입
4. 재화 종류가 하드코딩(필드 단위) → 차기 프로젝트는 `Goods` 범용 모델 + 타입 enum 기반 Dictionary 저장

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

1. 각 Info/Server/UGUI 파일 경로는 실제 Unity 프로젝트에서 실존 확인 완료 (작성 시 `ls` + `find` 실측)
2. `find` 기반으로 `PlayFab`·`SaveData`·`UserData` 키워드를 검색한 결과는 `ServerClass.cs`·`ServerInfo.cs`·`Info/` 6개 파일로 집중됨 — 본 문서 §2 구조와 일치
3. 마스터 테이블 이름은 10 문서(데이터 로딩) 및 서버 지시서 §6 샘플을 교차 참조하여 추정 (기획팀 테이블 정의 재확인 필요 표시)

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

- **기각안 A: 각 Info 클래스의 필드별 세이브 대상 분류표 작성** — 토큰 비용 + 프레임워크 흡수 대비 정보량 과다. 구조 수준 분류로 대체. 필요 시 Phase 0-C에서 세부 감사
- **기각안 B: 서버 API 전수 매핑** — 서버 지시서 v1.1/v1.2가 별도 SOT로 존재. 본 문서는 클라 메타 구조에 집중
- **기각안 C: 메타시스템 보안 취약점 감사** — `05_서버연동_현황_v1.md` Critical 3건이 이미 추적 중(#2 보류). 본 문서는 중복 분석 안 함

## 부록 A. 변경 이력
- **v1 (2026-04-17)**: 초판. 개발팀장 Phase 0-B 최종 완결 작업(B-5)으로 작성. Unity 프로젝트 `Assets/Script/` 전수 `ls` + 키워드 `find` 실측 기반. 서버 지시서 v1.1/v1.2·05 문서·09·10·11 문서 교차 참조.