205 lines
13 KiB
Markdown
205 lines
13 KiB
Markdown
# 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 문서 교차 참조.
|