NerdNavis_AiDev
/
BurningTimesAi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
BurningTimesAi/프로젝트/수상한잡화점/개발/12_메타시스템_v1.md

13 KiB
Raw Blame History

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 문서 교차 참조.