AGENT SKILL

03-ssot

暂无简介

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

02 资源文件 1

03 SKILL.md 正文

03-ssot — 49-reward-system (통합 SSOT)

Status: ACTIVE AppliesTo: v10

이 문서가 정본이다 (SSOT)

Reward 관련 규칙의 단일 SSOT는 이 문서다.

  • RewardData(보상 적용 입력) 규약
  • reward_group_id 해석 책임(컨텐츠 레이어)
  • RewardManager의 "지급 실행기" 규약
  • REWARD 테이블 스키마(정규화)
  • 초기 보상 지급(FirstInit) 규약

비정본(이 문서에서 다루지 않음):

  • 멱등/기록/복구(ledger/pending/서버 확정) — 호출자 시스템의 정본을 참조한다.

A) Core Terms (정본)

  • RewardData: 보상 적용 입력 단위 ({ type, id, amount })
  • RewardData[]: 보상 적용 입력 payload (array)
  • reward_group_id: 보상 그룹 키. TB_REWARD 테이블의 group:true 컬럼. 여러 행을 하나의 보상 묶음으로 그룹화한다.
  • reward_num: 개별 보상 행의 PK (TB_REWARD 테이블 키, int). 직접 사용하지 않고, reward_group_id로 그룹 조회하여 사용한다.

B) RewardData Schema (정본)

RewardData는 { type, id, amount } 형태다.

  • type: REWARD_TYPE(enum, Generated) — REWARD_TYPE.CARD | REWARD_TYPE.CURRENCY | REWARD_TYPE.EQUIP | REWARD_TYPE.HERO | REWARD_TYPE.RENTAL | REWARD_TYPE.PASS
    • 입력: input/Domains/Game/ENUM_META.json → 생성: Devian.Domain.Game.REWARD_TYPE
  • id: string
  • amount: long (>= 0만 허용)

이 스키마 문단이 RewardData의 단일 정본이다. 22-inventory-system에서는 스키마를 재정의하지 않고 본 문서를 참조한다.

NOTE:

  • type=REWARD_TYPE.EQUIP의 id는 item_id(pk)를 의미한다.
  • type=REWARD_TYPE.CARD의 id는 item_id(pk)를 의미한다.
  • type=REWARD_TYPE.HERO의 id는 item_id(pk)를 의미한다(TB_ITEM_HERO 테이블 키).
  • type=REWARD_TYPE.RENTAL의 id는 item_id(pk)를 의미한다 (예: "NO_ADS"). Amount=1은 "활성화" 의미.
  • type=REWARD_TYPE.PASS의 id는 item_id(pk)를 의미한다 (예: "S2026_01"). Amount=1은 "소유" 의미.
  • Reward/Purchase grants에는 options가 없다. options는 Inventory 내부 속성으로만 관리된다.

정합:

  • 서버 검증 응답 grants[](지급 내역)과 동일 형태를 사용한다.
  • grants[]는 inventory 지급 전용이며, 권한/플래그 변화는 별도 경로로 처리한다.

NEEDS CHECK (형준 결정 필요):

  • id 네이밍 규칙(예: gem, gold, item_sword_01)

C) REWARD 테이블 스키마 (정본)

REWARD 테이블은 정규화된 1행=1보상 구조다.

필드 타입 Row 3 옵션 설명
Reward_num int pk 행별 고유 PK
Reward_group_id string group:true 보상 그룹 키 (여러 행을 묶음)
Type enum:REWARD_TYPE CARD / CURRENCY / EQUIP / HERO / RENTAL / PASS
Id string 대상 ID (item_id 또는 Currency_type enum name)
Amount int 수량
  • TB_REWARD.GetByGroup(reward_group_id) → IReadOnlyList<REWARD> (자동 생성)
  • Currency의 Id는 CURRENCY_TYPE enum name 문자열 (예: "GOLD", "JEWEL_FREE")

C-2) Reward_group_id 해석 (정본)

RewardManager가 TB_REWARD 테이블을 직접 참조하여 reward_group_id를 RewardData[]로 변환한다. Devian.Samples.MobilePackage.asmdef에 Devian.Domain.Game 참조가 포함되어 있다.

  • lookup key: reward_group_id (TB_REWARD group key)
  • API: TB_REWARD.GetByGroup(reward_group_id) → 행 리스트
  • 결과: RewardData[] (각 행의 { Type, Id, Amount } → RewardData 변환)

NOTE:

  • RewardManager는 변환된 RewardData[]를 "적용(지급 실행)"만 한다(멱등/기록/복구 금지).

D) RewardManager 적용 규약 (정본)

  • RewardManager는 입력 RewardData[]를 받아 REWARD_TYPE별로 해석하고, InventoryManager의 타입별 구체 API를 호출하여 로컬 인벤토리에 적용한다.
  • RewardManager는 RewardData 선검증(type/id/amount) + 원자성(all-or-nothing)을 보장한다.
  • public reward 적용 API의 실패 모델은 GameResult다. invalid reward / table lookup / parse 실패를 throw 기본값으로 바꾸지 않는다.
  • RewardManager는 다음을 하지 않는다:
    • 멱등 처리(grantId 사용 금지)
    • 지급 기록(ledger) 저장
    • 서버 확정/조회

D-2) 초기 보상 지급 (FirstInit) 규약 (정본)

  • 초기 지급 데이터 소스는 FirstRewardSettings ScriptableObject다.
    • Resources 경로: Devian/FirstRewardSettings
    • 프로젝트 에셋 경로: Assets/Resources/Devian/FirstRewardSettings.asset
  • RewardManager.FirstInitAsync()는 위 에셋의 InitialRewards(CString) payload를 읽는다.
  • FirstRewardSettings는 SelectedHeroUnitId(UNIT_HERO_ID)도 함께 가진다.
  • JSON을 RewardData[] 규약으로 파싱/검증한다.
  • 허용 JSON:
    • RewardData[]
    • { "rewards": RewardData[] }
  • 파싱/검증 실패 시 CommonResult.Failure를 반환하고 적용하지 않는다.
  • 파싱 성공 시 RewardManager.ApplyRewardDatas로 적용한다.
  • SelectedHeroUnitId가 설정되어 있으면 대응 ITEM_HERO.item_id를 hero reward +1로 자동 합성한다.
  • 같은 ITEM_HERO row의 initial_item_##는 ITEM_EQUIP +1 reward로 자동 합성한다.
  • apply 후 방금 지급된 equip uid를 initial_slot_##에 장착한다.
  • 이후 SelectedHeroUnitId를 TB_ITEM_HERO.unit_id -> item_id로 해석하여 InventoryManager.SelectedHeroId에 적용한다.
  • SelectedHeroUnitId가 비어 있거나 매핑/보유 상태가 invalid면 선택 hero만 비운다(soft-fail).
  • LoginManager는 FirstInitAsync를 직접 호출한다. LoginInitializeResult.IsInitial을 확인한 뒤 실행한다.
  • first-init payload는 운영 데이터 경계다. AES/JSON 실패도 결과 코드(GameResult)로 올리고 상위 호출자가 처리한다.

정본: 12-first-reward-settings


E) RewardData Runtime Type Location (reference)

  • REWARD_TYPE enum은 Generated이다 (입력: input/Domains/Game/ENUM_META.json, 네임스페이스: Devian.Domain.Game).
  • RewardData struct만 아래 파일에 수동 정의한다 (using Devian.Domain.Game; 필요).
  • UPM (정본): framework-cs/upm/com.devian.foundation/Samples~/MobilePackage/Runtime/Reward/RewardData.cs
  • Packages (sync): framework-cs/apps/UnityExample/Packages/com.devian.foundation/Samples~/MobilePackage/Runtime/Reward/RewardData.cs
  • Assets/Samples (import): framework-cs/apps/UnityExample/Assets/Samples/Devian Samples/{version}/MobilePackage/Runtime/Reward/RewardData.cs
  • 3-path mirror 정책: devian-unity/04-package-policy

Related

04 同仓库更多 Skills