AGENT SKILL
16-shop-catalog-chest
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-04-12
- Stars
- ★ 0
- Forks
- 0
02 资源文件 1
- 参考文档agents/openai.yaml153 B
03 SKILL.md 正文
16-shop-catalog-chest
Status: ACTIVE AppliesTo: v10 Type: Design / Runtime SSOT
ShopCatalogChest는 더 이상 SHOP_ITEM_CHEST.reward_group_id를 직접 소비하는 단순 보상 카탈로그가 아니다.
이 문서는 chest catalog progression(level/exp)과 purchase reward routing을 정의한다.
1. Current Gap
ShopCatalogChest는 현재ShopCatalogBasethin wrapper다.SHOP_ITEM_CHEST는 현재Reward_group_id,Amount를 직접 가진다.ShopProductFactory.CreateChestProduct()는 chest row를 일반ShopRewardProductBase로 만든다.ShopManager.validateShopProductConfig()/buyRewardCatalogAsync()는reward_group_idnon-empty를 전제로 한다.ShopCatalogChestStorageData는adsRefreshUtcMs,productRemainCounts만 저장한다.
따라서 이번 변경은 table 추가만이 아니라 chest 전용 purchase flow 분리가 필요하다.
2. New Table / Enum Contract
Enum
입력: 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_idname_idcurrency_typepriceamountmax_count
- 추가:
productChestType(SHOP_PRODUCT_CHEST_TYPE)
- 삭제:
reward_group_id
- 규칙:
ADSproduct는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_CHESTtable에 존재하는 최대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기본값은1CurrentExp기본값은0Max_exp는 현재SHOP_CATALOG_CHEST.Levelrow의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다.
구매 성공 흐름:
ShopCatalogChestinstance를 얻는다.- 현재
Level의SHOP_CATALOG_CHESTrow를 조회한다. SHOP_PRODUCT_CHEST_TYPE으로 reward / exp를 결정한다.- 광고 시청 또는 재화 차감을 수행한다.
- 결정된 reward group을 적용한다.
- 선택된 reward group을
SHOP_ITEM_CHEST.amount횟수만큼 적용한다. - 결정된 exp를 chest catalog에 적립한다.
- 현재 row의
Max_exp를 넘기면 자동 레벨업 한다. remainCount,adsRefreshUtcMs, save state를 반영한다.
매핑:
ADS-> reward=Reward_ads, exp=Ads_expONE-> reward=Reward_paid01, exp=Gain_exp01TEN-> 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를 유지하되,
CHESTcatalog에 한해 빈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 소유 상태:
adsRefreshUtcMsproductRemainCountslevelcurrentExp
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.jsoninput/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.csRuntime/Shop/Catalog/ShopCatalogBase.cs(공통 helper를 올릴 경우)Runtime/Shop/ShopProduct.csRuntime/Shop/ShopProductFactory.csRuntime/Shop/ShopManager.csRuntime/Shop/ShopStorage.csRuntime/SaveData/JsonCodec/SaveDataJsonCodecShop.cs
Sample table data:
framework-cs/apps/UnityExample/Assets/Bundles/Tables/ndjson/SHOP_ITEM_CHEST.jsonframework-cs/apps/UnityExample/Assets/Bundles/Tables/ndjson/SHOP_CATALOG_CHEST.json
8. Recommended Implementation Order
ShopTable.xlsx에서SHOP_PRODUCT_CHEST_TYPE,SHOP_CATALOG_CHEST, 변경된SHOP_ITEM_CHEST스키마를 authoring한다.- domain enum/table codegen을 다시 돌린다.
- chest storage + save codec에
level/currentExp를 추가한다. - chest product model이
Chest_type,Amount를 알 수 있도록ShopProduct/ShopProductFactory를 정리한다. ShopCatalogChest에 current row lookup,Level,CurrentExp,Max_exp,LevelUp(), max-level clamp를 구현한다.ShopManager의 chest buy path를 generic reward product path와 분리하고 reward multiplier=amount를 반영한다.- ADS refill, remainCount, old save default, max-level exp ignore를 검증한다.
- 관련 shop 문서를 갱신한다.