AGENT SKILL
03-ssot
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-04-12
- Stars
- ★ 0
- Forks
- 0
02 资源文件 1
- 参考文档agents/openai.yaml113 B
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: stringamount: 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_TYPEenum 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) 규약 (정본)
- 초기 지급 데이터 소스는
FirstRewardSettingsScriptableObject다.- Resources 경로:
Devian/FirstRewardSettings - 프로젝트 에셋 경로:
Assets/Resources/Devian/FirstRewardSettings.asset
- Resources 경로:
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_HEROrow의initial_item_##는ITEM_EQUIP +1reward로 자동 합성한다. - 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)로 올리고 상위 호출자가 처리한다.
E) RewardData Runtime Type Location (reference)
REWARD_TYPEenum은 Generated이다 (입력:input/Domains/Game/ENUM_META.json, 네임스페이스:Devian.Domain.Game).RewardDatastruct만 아래 파일에 수동 정의한다 (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
- 11-rewarddata-interpretation — RewardData 해석 절차/타입별 의미/소스별 파싱 가이드
- 10-reward-manager — reward_group_id 변환과 적용 실행기
- 12-first-reward-settings — FirstRewardSettings ScriptableObject (초기 보상 지급 설정)