AGENT SKILL
13-shop-catalog
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-04-12
- Stars
- ★ 0
- Forks
- 0
03 SKILL.md 正文
13-shop-catalog
Status: ACTIVE AppliesTo: v10
Shop Catalog는 상점 상품 소스를 카탈로그 타입으로 분리해서 관리한다.
catalog initialize/refresh operation의 정본은 03-ssot다.
이 문서는 카탈로그 데이터 해석 규칙을 다룬다.
1. Enum
ENUM_META.json
SHOP_CATALOG_TYPE: [NONE, DAILY, CHEST, PURCHASE, GOLD, EVENT]
SHOP_DISCOUNT_TYPE: [NONE, PER10, PER20, PER30, PER50]
SHOP_PRODUCT_TYPE: [NONE, FREE, ADS, CURRENCY, PURCHASE]
2. Table Mapping
- table file:
input/Domains/Game/ShopTable.xlsx - 카탈로그 생성 소스:
SHOP_CATALOG - 카탈로그 클래스 매핑:
DAILY->ShopCatalogDailyCHEST->ShopCatalogChestPURCHASE->ShopCatalogPurchaseGOLD->ShopCatalogGoldEVENT->ShopCatalogEvent
- 카탈로그 상품 테이블 매핑:
DAILY->SHOP_ITEM_DAILYCHEST->SHOP_ITEM_CHESTPURCHASE->SHOP_ITEM_PURCHASEGOLD->SHOP_ITEM_GOLDEVENT->SHOP_ITEM_EVENTCHESTprogression source ->SHOP_CATALOG_CHEST
카탈로그 초기화 라이프사이클:
ShopCatalogBase는 생성자에서 product를 만들지 않는다.Initialize()가 1회 실행되며,onInitialize()로 1회 setup 후RefreshProducts()를 호출한다.CreateRuntimeCatalogs(storage)는TB_SHOP_CATALOG.GetAll()을 읽어 storage-backed runtime catalog를 생성한다.CreateRuntimeCatalogs(storage)는 catalog 인스턴스만 만들고,ShopManager.Initialize()경로에서 registry 등록 후 각 catalogInitialize()를 호출한다.Create(...)는 standalone catalog 생성을 위해 반환 전에Initialize()를 호출해 product 인덱스를 확정한다.ShopCatalogBase.onRefresh()기본 구현은CHEST/PURCHASE/GOLD의 테이블 전체 row를 상품으로 생성하고, 해당 catalog bucket의 remain state를 적용한다.ShopCatalogDaily.onRefresh()는 DAILY snapshot 복원 또는 재생성을 처리한다.ShopCatalogEvent.onRefresh()는SHOP_ITEM_EVENT.start_time/end_time서버 UTC 구간 안의 row만 상품으로 생성한다.- 각 catalog 생성자는 자기 전용
ShopCatalog*StorageData를 받는다. - row ->
ShopProductBase변환은ShopProductFactory(15)에서 처리한다.
3. Refresh Rule
- 일반 카탈로그의 구매 제한 자동 refresh는
autoRefreshUtcMs(다음 refresh 시각) +auto_refresh_days기준으로 처리한다. - 일반 카탈로그는
auto_refresh_days <= 0이면 자동 refresh를 사용하지 않는다. - 일반 카탈로그 refresh 완료 시 다음 refresh 시각은
serverNow + auto_refresh_days로 갱신한다. EVENT는auto_refresh_days대신 가장 가까운 미래start_time/end_time경계 시각을 다음 refresh 시각으로 사용한다.- ADS/FREE 상품 리필은 catalog 저장 버킷의
adsRefreshUtcMs기준으로 별도 처리한다. - 카탈로그 초기화/refresh 시
adsRefreshUtcMs가 없거나 만료면 ADS/FREE 제한 상품을remainCount=max_count로 리필한다. - ADS/FREE 구매 성공 시
adsRefreshUtcMs = serverNow + 1day를 기록한다. SHOP_ITEM_DAILY카탈로그 refresh 시에는 저장된 DAILY snapshot을 새 snapshot으로 교체한다.- refresh 조건 탐색은
ShopManager.evaluateCatalogRefreshState(...)한 곳에서 처리한다. - 카탈로그별 refresh 남은 시간은 catalog runtime 프로퍼티로 조회한다. 공통 값은
RemainAutoRefreshTimeMs, DAILY 전용 값은RemainAdsRefreshTimeMs,ManualRefreshRemainTimeMs,ManualRefreshRemainCount를 사용한다.
4. Unlock Rule
SHOP_CATALOG.unlock_msg_id가 비어있으면 잠금 없이 사용한다.SHOP_CATALOG.unlock_msg_id가IsNullOrWhiteSpace면 unlock 조건 없음으로 간주하며IsLocked=false다.unlock_msg_id가 있으면IsLocked=true로 시작한다.ShopManager는GameMessageManager를 구독하고unlock_op_type/unlock_value조건을 평가해 해금한다.- 해금 조건 평가는 누적 stat(
GameMessageManager.GetStat(unlock_msg_id))으로 수행한다. - 조건 만족 시
IsLocked=false로 전환된다. - 잠긴 카탈로그의 상품은
CanBuy/BuyAsync에서 차단된다.
5. SHOP_ITEM_DAILY Snapshot Rule
SHOP_ITEM_DAILY는 초기화/refresh 시 최종 snapshot을 생성한다.currency_type=FREE/ADSrow는 고정 상품으로 항상 포함한다.currency_type!=FREE/ADSrow에서5개를 선택 생성한다.- 이 규칙은
auto_refresh_days값과 무관하며DAILY의 고유 생성 규칙이다. select_rate < 0row는 무조건 포함한다.select_rate > 0row만 합산해 가중치 선택한다.select_rate == 0row는 선택 후보에서 제외한다.- 동일
shop_item_id는 중복 선택하지 않는다. - 선택된 비고정 5개 중 무작위 3개를 할인 상품으로 선정한다.
- 할인 선정된 row는
discount_rate10_per/20Per/30Per/50Per합산 가중치로SHOP_DISCOUNT_TYPE(PER10/PER20/PER30/PER50)를 결정한다. - 할인 가중치 합이 0 이하면
SHOP_DISCOUNT_TYPE.NONE을 사용한다. - 각 snapshot row는
amount_min/amount_max범위에서 runtimeamount를 1회 선택한다. - 생성 결과는 storage의
dailyCatalogProducts(shopId, discountType, remainCount, amount)로 저장한다. dailyCatalogProducts는 DAILY snapshot 전체를 저장한다.FREE/ADS도 동일 리스트에 포함한다.- 저장된 DAILY snapshot이 있으면 그 상태를 복원한다. legacy save처럼
FREE/ADS가 빠져 있으면 fixed row를 보강해 정규화한다. - 저장된 DAILY snapshot의 만료 여부는
ShopManager의 시간 기반 refresh 판정에서 결정한다. SHOP_ITEM_DAILY.unit_price는 단가다.ShopProductDaily.PriceWithoutDiscount는unit_price * snapshot.amount이며, 할인은 그 결과에 적용한다.- daily runtime
amount는 reward 반복 횟수이면서 가격 배수에도 반영된다. - daily manual refresh는 광고 시청 성공으로만 가능하며, rolling 24시간 기준 최대 5회다.
- daily manual refresh의 상태 판단, 광고 호출, 성공 시
manualRefreshUtcMs/manualRefreshRemainCount/autoRefreshUtcMs갱신은ShopCatalogDaily가 직접 처리한다. manualRefreshRemainCount는 남은 횟수이며, 초기값과 만료 후 reset 값은 5다.
6. Event Catalog Rule
catalog=EVENT상품 소스는SHOP_ITEM_EVENT다.ShopCatalogEvent.onRefresh()는 서버 UTC 현재 시각이start_time <= now < end_time인 row만 생성한다.- 다음 refresh 시각은 가장 가까운 미래
start_time/end_time경계 시각이다. EVENT는 DAILY처럼 별도 동적 상품 payload를 저장하지 않는다.
7. Purchase Catalog Rule
catalog=PURCHASE상품은internal_product_id를 통해PurchaseManager로 구매한다.- 시즌 종료 임박 차단(
season_id) 검사는 ShopManager에서 수행한다.
8. Chest Catalog Rule
catalog=CHEST상품 소스는SHOP_ITEM_CHEST다.- chest progression source는
SHOP_CATALOG_CHEST다. - chest 구매 reward는
SHOP_ITEM_CHEST.reward_group_id가 아니라 현재 chest level row의reward_ads/reward_paid01/reward_paid10에서 결정한다. - chest exp는 현재 chest level row의
ads_exp/gain_exp01/gain_exp10을 사용한다. SHOP_ITEM_CHEST.amount는 reward 반복 지급 횟수이며 가격에는 곱하지 않는다.- 최대 레벨은
SHOP_CATALOG_CHEST의 최대Level값이며, 최대 레벨에서는CurrentExp=0이고 추가 exp를 획득하지 않는다.
9. Implementation Location (3-path mirror)
- UPM (정본):
framework-cs/upm/com.devian.foundation/Samples~/MobilePackage/Runtime/Shop/Catalog/ - Packages (sync):
framework-cs/apps/UnityExample/Packages/com.devian.foundation/Samples~/MobilePackage/Runtime/Shop/Catalog/ - Assets/Samples (import):
framework-cs/apps/UnityExample/Assets/Samples/Devian Foundation/0.1.0/MobilePackage/Runtime/Shop/Catalog/
파일 구성:
ShopCatalogBase.cs— abstract base, runtime helpersShopCatalogFactory.cs— catalog instance 생성 factoryShopCatalogEmpty.cs— empty placeholder (internal)ShopCatalogDaily.cs—FREE/ADS + 비고정 5개snapshot 생성/할인/저장 복원ShopCatalogEvent.cs— 시간 구간 필터링ShopCatalogChest.cs— CHEST 카탈로그ShopCatalogPurchase.cs— PURCHASE 카탈로그ShopCatalogGold.cs— GOLD 카탈로그