AGENT SKILL

12-shop-storage

ShopStorage에서 catalog별 typed storage data를 저장/복원할 때 사용한다.

License 许可
MIT
所属仓库
devwinsoft/devian
最近更新
2026-04-12
Stars
★ 0
Forks
0

01 前言 Front Matter

name
12-shop-storage
description
ShopStorage에서 catalog별 typed storage data를 저장/복원할 때 사용한다.

03 SKILL.md 正文

12-shop-storage

Status: ACTIVE AppliesTo: v10

ShopStorage는 Shop catalog runtime 상태의 저장 컨테이너다.


1. Class

[Serializable]
public sealed class ShopStorage
  • namespace: Devian
  • asmdef: Devian.Samples.MobilePackage
  • 소유자: ShopManager

2. Typed Storage Data

[Serializable]
public abstract class ShopCatalogStorageDataBase
{
    public abstract SHOP_CATALOG_TYPE CatalogType { get; }
}

[Serializable]
public abstract class ShopCatalogProductRemainStorageDataBase : ShopCatalogStorageDataBase
{
    public Dictionary<string, int> productRemainCounts = new();
}
[Serializable]
public sealed class ShopCatalogDailyStorageData : ShopCatalogStorageDataBase
{
    public override SHOP_CATALOG_TYPE CatalogType => SHOP_CATALOG_TYPE.DAILY;

    public long autoRefreshUtcMs;
    public long adsRefreshUtcMs;
    public long manualRefreshUtcMs;
    public int manualRefreshRemainCount;
    public List<ShopDailyProductState> dailyCatalogProducts = new();
}

[Serializable]
public sealed class ShopCatalogChestStorageData : ShopCatalogProductRemainStorageDataBase
{
    public override SHOP_CATALOG_TYPE CatalogType => SHOP_CATALOG_TYPE.CHEST;

    public long adsRefreshUtcMs;
    public int level;
    public int currentExp;
}

[Serializable]
public sealed class ShopCatalogPurchaseStorageData : ShopCatalogStorageDataBase
{
    public override SHOP_CATALOG_TYPE CatalogType => SHOP_CATALOG_TYPE.PURCHASE;
}

[Serializable]
public sealed class ShopCatalogGoldStorageData : ShopCatalogProductRemainStorageDataBase
{
    public override SHOP_CATALOG_TYPE CatalogType => SHOP_CATALOG_TYPE.GOLD;

    public long adsRefreshUtcMs;
}

[Serializable]
public sealed class ShopCatalogEventStorageData : ShopCatalogStorageDataBase
{
    public override SHOP_CATALOG_TYPE CatalogType => SHOP_CATALOG_TYPE.EVENT;

    public long autoRefreshUtcMs;
}

보조 타입:

  • ShopDailyProductState = { shopId, discountType, remainCount, amount }

ShopStorage 필드:

  • schemaVersion (현재 14)
  • daily: ShopCatalogDailyStorageData
  • chest: ShopCatalogChestStorageData
  • purchase: ShopCatalogPurchaseStorageData
  • gold: ShopCatalogGoldStorageData
  • eventCatalog: ShopCatalogEventStorageData
  • legacy migration buffer:
    • _legacyPurchaseCounts: Dictionary<string, int> (직렬화 안 함)

3. Catalog Data Ownership

  • DAILY
    • autoRefreshUtcMs
    • adsRefreshUtcMs
    • manualRefreshUtcMs
    • manualRefreshRemainCount
    • dailyCatalogProducts
  • CHEST
    • adsRefreshUtcMs
    • productRemainCounts
    • level
    • currentExp
  • GOLD
    • adsRefreshUtcMs
    • productRemainCounts
  • PURCHASE
    • 현재 catalog 전용 저장 상태 없음
  • EVENT
    • autoRefreshUtcMs

규칙:

  • dailyCatalogProducts는 DAILY 최종 snapshot 전체를 저장한다.
  • DAILY snapshot에는 FREE, ADS, 비고정 5개가 모두 포함된다.
  • DAILY의 remainCount/discountType/amount 저장 위치는 dailyCatalogProducts 하나뿐이다.
  • 무제한 상품(max_count=-1)은 CHEST/GOLD.productRemainCounts에 저장하지 않는다.
  • PURCHASE와 EVENT에 필요 없는 상태를 미리 넣지 않는다.
  • 최고 레벨 상태는 currentExp=0으로 저장/복원한다.

4. Hard Rules

  • 저장 구조는 generic dictionary가 아니라 catalog별 typed storage data field를 사용한다.
  • ShopCatalogFactory.CreateRuntimeCatalogs(storage)는 catalog 생성 시 해당 catalog type의 storage data를 같이 전달한다.
  • 각 catalog는 자기 storage data만 해석한다.
  • non-daily catalog는 table product 생성 후 자기 storage data의 productRemainCounts를 직접 적용한다.
  • DAILY는 storage의 dailyCatalogProducts가 valid하면 snapshot 전체를 복원하고, invalid/empty면 FREE/ADS 고정 + 비고정 5개 선택으로 새 snapshot을 생성한다.
  • autoRefreshUtcMs는 시작 시각이 아니라 다음 refresh 시각이다.
  • EVENT.autoRefreshUtcMs는 주기값이 아니라 다음 start_time/end_time 경계 시각이다.
  • adsRefreshUtcMs는 ADS/FREE 구매 성공 시 serverNow + 1day로 기록한다.
  • CHEST.level 기본값은 1이다.
  • CHEST.currentExp 기본값은 0이다.
  • CHEST가 최대 레벨이면 currentExp=0으로 정규화한다.
  • manualRefreshUtcMs는 ShopCatalogDaily.RefreshByAdsAsync() 성공 시 serverNow + 1day로 기록한다.
  • manualRefreshRemainCount는 rolling 24시간 남은 횟수다.
  • 초기 상태와 만료 후 reset 상태의 manualRefreshRemainCount는 5다.
  • 수동 refresh 성공 시 manualRefreshRemainCount를 1 감소시킨다.
  • 구 save data의 DAILY productRemainCounts는 deserialize 시 dailyCatalogProducts로 병합 복원하고, 신규 저장에서는 사용하지 않는다.
  • legacy purchaseCounts/purchaseLimits는 _legacyPurchaseCounts로만 1회 마이그레이션한다.

5. SaveData

ShopStorage는 SaveData JSON의 shop 섹션으로 직렬화한다.

  • serialize: SaveDataJsonCodecShop.Serialize(ShopStorage)
  • deserialize: SaveDataJsonCodecShop.DeserializeInto(JObject, ShopStorage)
  • 최신 스키마는 schemaVersion=13
  • 저장 JSON은 catalogs 하위에 catalog 단위로 묶어 저장한다.
  • JSON shape는 grouped catalog 구조를 유지하지만, 런타임 메모리 구조는 typed storage field를 사용한다.
  • DAILY는 adsRefreshUtcMs, autoRefreshUtcMs, manualRefreshUtcMs, manualRefreshRemainCount, dailyCatalogProducts(shopId, discountType, remainCount, amount)를 저장한다.
  • CHEST는 adsRefreshUtcMs, productRemainCounts, level, currentExp를 저장한다.
  • GOLD는 adsRefreshUtcMs, productRemainCounts를 저장한다.
  • EVENT는 autoRefreshUtcMs를 저장한다.
  • PURCHASE는 현재 직렬화할 catalog 전용 상태가 없다.

6. Runtime Usage

  • ShopManager.Initialize()는 SaveData에서 복원된 ShopStorage를 읽어 runtime catalog를 생성한다.
  • ShopCatalogFactory가 ShopStorage.GetCatalogData(...)로 catalog-specific storage data를 주입한다.
  • ShopManager.synchronizeProductIndexFromCatalogs()는 product index rebuild만 한다. storage 복원 책임은 없다.
  • runtime cache invalidation이 필요할 때는 ShopManager.InvalidateRuntimeState()를 호출한다.

7. Implementation Location (3-path mirror)

  • UPM (정본): framework-cs/upm/com.devian.foundation/Samples~/MobilePackage/Runtime/Shop/ShopStorage.cs
  • Packages (sync): framework-cs/apps/UnityExample/Packages/com.devian.foundation/Samples~/MobilePackage/Runtime/Shop/ShopStorage.cs
  • Assets/Samples (import): framework-cs/apps/UnityExample/Assets/Samples/Devian Foundation/0.1.0/MobilePackage/Runtime/Shop/ShopStorage.cs

8. Related

04 同仓库更多 Skills