10-purchase-manager
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-04-12
- Stars
- ★ 0
- Forks
- 0
02 资源文件 1
- 参考文档agents/openai.yaml120 B
03 SKILL.md 正文
10-purchase-manager
Status: ACTIVE AppliesTo: v13
PurchaseManager(구매 샘플)의 위치/역할/규약을 설명한다.
문서 경계 (Scope)
- 이 문서는 PurchaseManager 클라이언트 샘플 코드의 위치/흐름/규약을 설명한다.
- Firebase Functions 구현 상세, Firestore 스키마, 배포/레포 셋업을 이 문서에 복제하지 않는다.
- 서버 관련 정본은
40(구현),44(셋업),46(결정),43(클라-서버 연동 규약)를 참조한다.
PurchaseManager는 단일 concrete 클래스이다.
TB_PURCHASE 테이블을 직접 참조하여 internal_product_id -> reward_group_id 변환과 ProductDefinition 빌드를 수행한다.
Implementation Location (3-path mirror)
3-path mirror 정책: devian-unity/04-package-policy, devian-unity/01-policy §SSOT 원칙
-
UPM (정본):
framework-cs/upm/com.devian.foundation/Samples~/MobilePackage/Runtime/Purchase/PurchaseManager.cs -
UPM (정본):
framework-cs/upm/com.devian.foundation/Samples~/MobilePackage/Runtime/Purchase/PurchaseSettings.cs -
UPM (정본):
framework-cs/upm/com.devian.foundation/Samples~/MobilePackage/Runtime/Purchase/PurchaseStorage.cs(상태 스냅샷) -
Packages (sync):
framework-cs/apps/UnityExample/Packages/com.devian.foundation/Samples~/MobilePackage/Runtime/Purchase/PurchaseManager.cs -
Packages (sync):
framework-cs/apps/UnityExample/Packages/com.devian.foundation/Samples~/MobilePackage/Runtime/Purchase/PurchaseSettings.cs -
Packages (sync):
framework-cs/apps/UnityExample/Packages/com.devian.foundation/Samples~/MobilePackage/Runtime/Purchase/PurchaseStorage.cs -
Assets/Samples (import):
framework-cs/apps/UnityExample/Assets/Samples/Devian Samples/{version}/MobilePackage/Runtime/Purchase/PurchaseManager.cs -
Assets/Samples (import):
framework-cs/apps/UnityExample/Assets/Samples/Devian Samples/{version}/MobilePackage/Runtime/Purchase/PurchaseSettings.cs -
Assets/Samples (import):
framework-cs/apps/UnityExample/Assets/Samples/Devian Samples/{version}/MobilePackage/Runtime/Purchase/PurchaseStorage.cs -
asmdef:
Devian.Samples.MobilePackage(Samples~/MobilePackage/Runtime/Devian.Samples.MobilePackage.asmdef)- 참조:
Devian.Domain.Game(TB_PURCHASE 테이블, GameResult)
Singleton
CompoSingleton<PurchaseManager>.Instance
- Registry key:
PurchaseManager - 다른 매니저에서 접근:
Singleton.Get<PurchaseManager>()
Public API (Sample)
InitializeAsync(ct)→Task<GameResult>- IAP 초기화 (Connect + FetchProducts). 선택적 prewarm 호출이며, Purchase/RetryInterruptedPurchase/Restore 경로에서 lazy-init로 자동 호출될 수 있음.
- Idempotent: 여러 번 호출해도 동일 Task 반환.
- Editor에서는 즉시
GAME_ERROR_TYPE.PURCHASE_UNSUPPORTED_PLATFORM반환.
PurchaseAsync(internal_product_id, ct)→Task<GameResult<PurchaseFinalResult>>- 단일 구매 진입점.
TB_PURCHASE에서Kind를 조회하여 구매 유형(Consumable/Rental/Subscription/SeasonPass)을 자동 결정 - 최종 지급은 서버
verifyPurchase결과만 신뢰 - 구매 보상(
AppliedRewards)에amount < 0값이 있으면 즉시 실패(GAME_ERROR_TYPE.GAME_INVALID_ARGUMENT) 처리한다. - Caller-managed client grant:
NeedsClientGrantDelivery=true이면 호출자가 보상을 적용한 뒤AckPurchaseClientGrantAppliedAsync로 ACK
- 단일 구매 진입점.
RetryInterruptedPurchaseAsync(ct)→Task<GameResult<RetryInterruptedPurchaseResult>>PurchaseStorage.current에 중단된 결제가 있으면 새 구매를 시작하지 않고 상태 전이를 재개/마무리- 중단 내역이 없으면
Success(Status=SkippedNoCurrent)(skip, 정상) - UI/Debug 표시는 반환 payload(
Status,Internal_product_id,ResultStatus,AppliedRewards)를 사용
AckPurchaseClientGrantAppliedAsync(purchaseId, ct)— 로컬 지급 성공 보고ReportPurchaseClientGrantFailureAsync(purchaseId, ct)— 로컬 지급 실패 보고RestoreAsync(ct)(iOS 스토어 복원, manual/fallback)- 스토어 복원 직후 서버
getEntitlements를 조회해mPasses/mRentals를 덮어써 복원한다. pass는 시즌 유효 구간(TB_SEASON)일 때만 복원한다.rental은 만료시각이 서버 현재시각보다 미래일 때만 복원하며, 누적 연장을 허용한다.
- 스토어 복원 직후 서버
GetLatestConsumablePurchase30dAsync(ct)→Task<GameResult<RecentPurchaseItem>>- 서버에서 최근 30일 내 최신 Consumable 구매 1건 조회
SyncEntitlementsAsync(ct)→Task<GameResult>- 서버
getEntitlements를 조회해mPasses/mRentals를 덮어써 동기화하고 결과 스냅샷을 반환한다. rental은 만료시각 미래값만 반영하며, 누적 연장을 허용한다.
- 서버
RefundAsync(ct)→Task<GameResult<RefundResult>>- 서버에서 환불/조정 내역을 조회하여 로컬 인벤토리 회수 적용
컨텐츠 카탈로그 통합 (TB_PURCHASE 직접 참조)
PurchaseManager가 Game 도메인 테이블을 직접 참조한다:
ResolveRewardGroupId(internal_product_id):TB_PURCHASE에서Reward_group_id조회 (없으면 빈 값)PurchaseFinalResult,RetryInterruptedPurchaseResultReward_group_id와AppliedRewards: RewardData[]를 포함한다.skip/reward_group_id 없음/이번 호출에서 지급 없음(ALREADY_GRANTED + APPLIED_ACKED)은AppliedRewards=[]가 정상이다.
BuildProductDefinitions():TB_PURCHASE.GetAll()에서is_active필터링 후 ProductDefinition 목록 생성- 플랫폼별 StoreSku 매핑:
#if UNITY_IOS→Store_sku_apple,#elif UNITY_ANDROID→Store_sku_google Kind→ProductType매핑: Consumable→Consumable, Subscription→Subscription, SeasonPass→NonConsumable
- 플랫폼별 StoreSku 매핑:
Server Integration (구현 완료)
서버 구현의 상세 규칙/스키마/배포 절차는 이 문서가 아니라 40/44/46 문서를 우선한다.
- VerifyPurchaseAsync:
FirebaseCallableManager.Instance.VerifyPurchaseAsync(data, ct)— ✅ 구현됨- 요청 키:
storeKey,internal_product_id,kind,payload - 응답:
GameResult<VerifyPurchaseResponse>
- 요청 키:
- reportPurchaseClientGrantResultAsync:
FirebaseCallableManager.Instance.AckPurchaseClientGrantAsync(data, ct)— ✅ 구현됨- 요청 키:
purchaseId,clientGrantStatus - 응답:
GameResult
- 요청 키:
- ackPurchaseStoreConfirmAsync:
FirebaseCallableManager.Instance.AckPurchaseStoreConfirmAsync(data, ct)— ✅ 구현됨- 요청 키:
purchaseId - 응답:
GameResult
- 요청 키:
- SyncEntitlementsAsync:
FirebaseCallableManager.Instance.GetEntitlementsAsync(ct)기반 복원 — ✅ 구현됨- 응답:
GameResult<EntitlementsSnapshot>(서버 entitlements를mPasses/mRentals에 덮어쓴 결과)
- 응답:
- GetLatestConsumablePurchase30dAsync:
FirebaseCallableManager.Instance.GetRecentPurchases30dAsync(data, ct)— ✅ 구현됨- 응답:
GameResult<RecentPurchaseItem>
- 응답:
- syncRefundsPageAsync:
FirebaseCallableManager.Instance.GetPurchaseAdjustmentsAsync(data, ct)— ✅ 구현됨- 응답:
GameResult<RefundPageResult>(raw item → PurchaseManager가 domain 보강)
- 응답:
- ackRefundAppliedAsync:
FirebaseCallableManager.Instance.AckRefundAppliedAsync(data, ct)— ✅ 구현됨- 응답:
GameResult
- 응답:
- Firebase callable 호출/에러 매핑/응답 파싱은 23-firebase-callable-manager에 통합.
PurchaseManager는
FunctionsException을 직접 catch하지 않는다.using Firebase.Functions불필요. domain 변환(ResolveRewardGroupId 등)은 PurchaseManager가 typed result 수신 후 수행한다.
Post-Sync Orchestration (SaveData 로드 후 표준 순서)
SaveDataManager.SyncGameStorageAsync(ct)→SyncResultSaveDataManager가 성공 시 payload를 직접 복원 → inventory, purchase, account 역직렬화PurchaseManager.InitializeAsync(ct)→ IAP 초기화PurchaseManager.RetryInterruptedPurchaseAsync(ct)→ 중단 구매 복구PurchaseManager.RefundAsync(ct)→ 환불 처리PurchaseManager.SyncEntitlementsAsync(ct)→ 서버getEntitlements기준으로mPasses/mRentals덮어쓰기 복원pass: 시즌 유효 구간 체크rental: 만료시각 미래값만 반영, 누적 연장 허용
Hard Rules (Sample must follow)
- Unity IAP "스토어 구매 성공 콜백"만으로 지급/NoAds 적용 금지
- 최종 지급/상태 반영은 서버(Cloud Functions) 결과(verifyPurchase)만 기준으로 한다.
- 지급 여부는 서버
verifyPurchase.resultStatus만 기준으로 한다(스토어 콜백만으로 지급 금지). resultStatus == GRANTED이면ConfirmPurchase+ackPurchaseStoreConfirm를 먼저 수행한 뒤 로컬 지급/ackPurchaseClientGrant(APPLIED_ACKED)를 진행한다.PurchaseStorage.current는Confirm + storeConfirm ACK + clientGrant report가 종결되기 전에는 clear하지 않는다.- 구매 보상(
RewardData[])의amount < 0은 허용하지 않는다. 음수 보상이 감지되면 구매/복구 경로를 실패 처리한다. - 로컬 지급 실패 시
FAILED_REPORTED를 서버에 기록할 수 있으나, confirm 미완 상태에서는current를 유지해 복구 경로를 보존한다. resultStatus == ALREADY_GRANTED라도clientGrantStatus == PENDING또는FAILED_REPORTED이면 로컬 지급 복구 경로를 사용할 수 있다.reward_group_id가 비어 있으면 로컬 보상 지급은 스킵하고, 클라이언트 지급 완료 처리만 진행한다. (결제/재구매 동일 규칙)- 구매 전 인증 게이트는
LoginManagerAPI(IsPurchaseLoginReady,EnsurePurchaseLoginReadyAsync)를 사용한다. (FirebaseAuth.CurrentUser직접 판정 금지) - 로컬/클라우드 저장용 구매 상태는
PurchaseManager.Instance.Storage(PurchaseStorage)에 기록한다. PurchaseStorage는 진행 중 결제(current), 환불/지원 대응용 최소 로그(refundSupportLogs), 환불 동기화 상태(refundSync)를 저장한다.- 실패 코드/메시지/최근 실패 요약/전체 이력/영수증(raw receipt)은 저장 금지.
- 환불/지원 로그 조회/삭제는
PurchaseStorageAPI를 직접 사용한다.GetRefundSupportLogs(),TryGetRefundSupportLog(...),RemoveRefundSupportLog(purchaseId),ClearRefundSupportLogs()
Related SSOT
skills/devian-unity/50-mobile-package/30-purchase-system/14-purchase-settings/SKILL.mdskills/devian-unity/50-mobile-package/30-purchase-system/03-ssot/SKILL.mdskills/devian-unity/50-mobile-package/30-purchase-system/33-purchase-storage/SKILL.mdskills/devian-unity/50-mobile-package/30-purchase-system/09-ssot-operations/SKILL.mdskills/devian-unity/50-mobile-package/30-purchase-system/40-purchase-backend-firebase/SKILL.mdskills/devian-unity/50-mobile-package/30-purchase-system/43-purchase-client-server-integration/SKILL.mdskills/devian-unity/50-mobile-package/30-purchase-system/11-purchase-repo-firebase-functions-setup/SKILL.mdskills/devian-unity/50-mobile-package/30-purchase-system/46-purchase-decisions/SKILL.md