16 Shop Catalog Chest

입력: input/Domains/Game/ENUM_META.json

SHOP_PRODUCT_CHEST_TYPE: [NONE, ADS, ONE, TEN]

• 요청 문구의 TES 표기는 오타로 보고 TEN만 사용한다.

SHOP_ITEM_CHEST

입력: input/Domains/Game/ShopTable.xlsx

• 유지:
  • shop_item_id
  • name_id
  • currency_type
  • price
  • amount
  • max_count
• 추가:
  • productChestType (SHOP_PRODUCT_CHEST_TYPE)
• 삭제:
  • reward_group_id
• 규칙:
  • ADS product는 currency_type=ADS, price=0 유지
  • ONE/TEN은 유료 또는 재화 결제 chest 상품이다.
  • amount는 reward 반복 지급 횟수다. 예를 들어 amount=10이면 선택된 reward group을 10회 적용한 것과 동일한 보상을 준다.
  • amount는 exp 획득량에는 곱하지 않는다. exp는 SHOP_CATALOG_CHEST의 Ads_exp/Gain_exp01/Gain_exp10만 사용한다.

SHOP_CATALOG_CHEST

입력: input/Domains/Game/ShopTable.xlsx

권장 row shape:

• Level (int, pk, 1-base)
• Ads_exp (int)
• Gain_exp01 (int)
• Gain_exp10 (int)
• Max_exp (int)
• Reward_ads (string, reward_group_id)
• Reward_paid01 (string, reward_group_id)
• Reward_paid10 (string, reward_group_id)

Hard rules:

• chest progression row 조회 키는 현재 Level이다.
• TB_SHOP_CATALOG_CHEST.Get(level)로 현재 레벨 row를 읽을 수 있어야 한다.
• current row가 없으면 chest progression 설정 오류로 본다.
• max level은 SHOP_CATALOG_CHEST table에 존재하는 최대 Level 값이다.

3. Runtime Contract

ShopCatalogChest public contract:

public int Level { get; }
public int CurrentExp { get; }
public int Max_exp { get; }
public void LevelUp();

Rules:

• Level 기본값은 1
• CurrentExp 기본값은 0
• Max_exp는 현재 SHOP_CATALOG_CHEST.Level row의 max_exp를 계산해서 노출한다. 별도 저장하지 않는다.
• CurrentExp는 누적 lifetime exp가 아니라 현재 레벨 구간 exp다.
• LevelUp()는 level을 증가시키고 overflow exp를 다음 레벨로 이월한다.
• 권장 구현은 while (CurrentExp >= Max_exp && nextRow exists)로 overflow exp를 보존하는 것이다.
• 다음 level row가 없으면 최고 레벨로 clamp해야 한다.
• 최고 레벨에서는 경험치를 획득하지 않는다.
• 최고 레벨에서는 CurrentExp=0으로 고정한다.
• 최고 레벨에서는 Max_exp=0으로 노출하는 것을 권장한다. 진행 필요 exp가 더 이상 없음을 런타임 값에서 명확히 표현할 수 있다.

4. Purchase Flow Rules

Chest purchase reward source는 SHOP_ITEM_CHEST row가 아니라 현재 chest level row다.

구매 성공 흐름:

1. ShopCatalogChest instance를 얻는다.
2. 현재 Level의 SHOP_CATALOG_CHEST row를 조회한다.
3. SHOP_PRODUCT_CHEST_TYPE으로 reward / exp를 결정한다.
4. 광고 시청 또는 재화 차감을 수행한다.
5. 결정된 reward group을 적용한다.
6. 선택된 reward group을 SHOP_ITEM_CHEST.amount 횟수만큼 적용한다.
7. 결정된 exp를 chest catalog에 적립한다.
8. 현재 row의 Max_exp를 넘기면 자동 레벨업 한다.
9. remainCount, adsRefreshUtcMs, save state를 반영한다.

매핑:

• ADS -> reward=Reward_ads, exp=Ads_exp
• ONE -> reward=Reward_paid01, exp=Gain_exp01
• TEN -> reward=Reward_paid10, exp=Gain_exp10

Hard rules:

• reward row 선택은 exp 적립/레벨업 이전에 해야 한다. 같은 구매가 중간에 다음 레벨 reward로 바뀌면 안 된다.
• reward 지급 multiplier는 항상 SHOP_ITEM_CHEST.amount를 사용한다.
• reward multiplier는 현재처럼 reward group apply 반복 또는 동등한 multiplier API로 처리한다.
• auto level-up threshold는 현재 level row의 Max_exp다.
• 최고 레벨에서는 exp를 적립하지 않는다.
• 최고 레벨에서는 구매 후에도 CurrentExp=0을 유지한다.
• chest purchase success는 save 전에 level/currentExp를 storage에 반영해야 한다.
• 기존 ADS refill semantics(adsRefreshUtcMs)와 limited purchase remain semantics(productRemainCounts)는 유지한다.

5. Product Model Impact

현재 generic reward product model은 chest progression에 맞지 않는다.

구현은 최소한 아래 둘 중 하나를 처리해야 한다.

• 권장: ShopProductChest : ShopProductBase 추가, SHOP_PRODUCT_CHEST_TYPE Chest_type, int Amount 보유
• 차선: chest도 기존 reward product를 유지하되, CHEST catalog에 한해 빈 reward_group_id를 허용하고 runtime에서 reward를 동적으로 조회

권장 이유:

• 현재 validation은 non-empty Reward_group_id를 강제한다.
• 현재 buy path는 product.Reward_group_id를 직접 적용한다.
• chest reward source는 이제 static product row가 아니라 catalog state다.

6. Storage / SaveData

ShopCatalogChestStorageData 소유 상태:

• adsRefreshUtcMs
• productRemainCounts
• level
• currentExp

Rules:

• ShopStorage.schemaVersion는 증가해야 한다. (11 -> 12 예상)
• 구세이브에 chest progression 필드가 없으면 level=1, currentExp=0으로 복원한다.
• Max_exp는 table 기반 계산값이므로 serialize하지 않는다.
• JSON codec은 catalogs.CHEST.level, catalogs.CHEST.currentExp를 저장/복원해야 한다.
• 저장 복원 시 level이 최대 레벨 이상이면 최대 레벨로 clamp하고 currentExp=0으로 정규화한다.

7. Affected Files

Data / codegen:

• input/Domains/Game/ENUM_META.json
• input/Domains/Game/ShopTable.xlsx
• generated domain outputs for SHOP_ITEM_CHEST, SHOP_CATALOG_CHEST, SHOP_PRODUCT_CHEST_TYPE

Runtime (3-path mirror):

• Runtime/Shop/Catalog/ShopCatalogChest.cs
• Runtime/Shop/Catalog/ShopCatalogBase.cs (공통 helper를 올릴 경우)
• Runtime/Shop/ShopProduct.cs
• Runtime/Shop/ShopProductFactory.cs
• Runtime/Shop/ShopManager.cs
• Runtime/Shop/ShopStorage.cs
• Runtime/SaveData/JsonCodec/SaveDataJsonCodecShop.cs

Sample table data:

• framework-cs/apps/UnityExample/Assets/Bundles/Tables/ndjson/SHOP_ITEM_CHEST.json
• framework-cs/apps/UnityExample/Assets/Bundles/Tables/ndjson/SHOP_CATALOG_CHEST.json

8. Recommended Implementation Order

1. ShopTable.xlsx에서 SHOP_PRODUCT_CHEST_TYPE, SHOP_CATALOG_CHEST, 변경된 SHOP_ITEM_CHEST 스키마를 authoring한다.
2. domain enum/table codegen을 다시 돌린다.
3. chest storage + save codec에 level/currentExp를 추가한다.
4. chest product model이 Chest_type, Amount를 알 수 있도록 ShopProduct / ShopProductFactory를 정리한다.
5. ShopCatalogChest에 current row lookup, Level, CurrentExp, Max_exp, LevelUp(), max-level clamp를 구현한다.
6. ShopManager의 chest buy path를 generic reward product path와 분리하고 reward multiplier=amount를 반영한다.
7. ADS refill, remainCount, old save default, max-level exp ignore를 검증한다.
8. 관련 shop 문서를 갱신한다.

9. Related

• 03-ssot
• 11-shop-product
• 12-shop-storage
• 13-shop-catalog
• 14-shop-catalog-factory