[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CBKSXGQQCZ185M8DH2K70B":3,"skill-same:01M6CBKSXGQQCZ185M8DH2K70B":50},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":13,"repositoryHtmlUrl":26,"repositoryHomepageUrl":6,"ownerHtmlUrl":27,"ownerBlogUrl":6,"ownerDescription":28,"updatedAt":29,"install":30,"resources":43},"01M6CBKSXGQQCZ185M8DH2K70B","10-purchase-manager",null,"devwinsoft\u002Fdevian","devwinsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F22570160?v=4","01M6C6RR8W05NH8NPKQNCE3Q72","maoshy","01M6C6RRDJ5TJJCZXRTY801YDH",0,"MIT","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F10-purchase-manager\u002FSKILL.md",[],[18],"10 purchase manager","2026-11-10 10:12:30",false,"# 10-purchase-manager\n\nStatus: ACTIVE\nAppliesTo: v13\n\nPurchaseManager(구매 샘플)의 위치\u002F역할\u002F규약을 설명한다.\n\n## 문서 경계 (Scope)\n\n- 이 문서는 **PurchaseManager 클라이언트 샘플 코드의 위치\u002F흐름\u002F규약**을 설명한다.\n- Firebase Functions 구현 상세, Firestore 스키마, 배포\u002F레포 셋업을 이 문서에 복제하지 않는다.\n- 서버 관련 정본은 `40`(구현), `44`(셋업), `46`(결정), `43`(클라-서버 연동 규약)를 참조한다.\n\nPurchaseManager는 **단일 concrete 클래스**이다.\n`TB_PURCHASE` 테이블을 직접 참조하여 `internal_product_id -> reward_group_id` 변환과 ProductDefinition 빌드를 수행한다.\n\n\n---\n\n\n## Implementation Location (3-path mirror)\n\n> 3-path mirror 정책: [devian-unity\u002F04-package-policy](..\u002F..\u002F..\u002F..\u002Fdevian-unity\u002F04-package-policy\u002FSKILL.md), [devian-unity\u002F01-policy](..\u002F..\u002F..\u002F..\u002Fdevian-unity\u002F01-policy\u002FSKILL.md) §SSOT 원칙\n\n- UPM (정본): `framework-cs\u002Fupm\u002Fcom.devian.foundation\u002FSamples~\u002FMobilePackage\u002FRuntime\u002FPurchase\u002FPurchaseManager.cs`\n- UPM (정본): `framework-cs\u002Fupm\u002Fcom.devian.foundation\u002FSamples~\u002FMobilePackage\u002FRuntime\u002FPurchase\u002FPurchaseSettings.cs`\n- UPM (정본): `framework-cs\u002Fupm\u002Fcom.devian.foundation\u002FSamples~\u002FMobilePackage\u002FRuntime\u002FPurchase\u002FPurchaseStorage.cs` (상태 스냅샷)\n- Packages (sync): `framework-cs\u002Fapps\u002FUnityExample\u002FPackages\u002Fcom.devian.foundation\u002FSamples~\u002FMobilePackage\u002FRuntime\u002FPurchase\u002FPurchaseManager.cs`\n- Packages (sync): `framework-cs\u002Fapps\u002FUnityExample\u002FPackages\u002Fcom.devian.foundation\u002FSamples~\u002FMobilePackage\u002FRuntime\u002FPurchase\u002FPurchaseSettings.cs`\n- Packages (sync): `framework-cs\u002Fapps\u002FUnityExample\u002FPackages\u002Fcom.devian.foundation\u002FSamples~\u002FMobilePackage\u002FRuntime\u002FPurchase\u002FPurchaseStorage.cs`\n- Assets\u002FSamples (import): `framework-cs\u002Fapps\u002FUnityExample\u002FAssets\u002FSamples\u002FDevian Samples\u002F{version}\u002FMobilePackage\u002FRuntime\u002FPurchase\u002FPurchaseManager.cs`\n- Assets\u002FSamples (import): `framework-cs\u002Fapps\u002FUnityExample\u002FAssets\u002FSamples\u002FDevian Samples\u002F{version}\u002FMobilePackage\u002FRuntime\u002FPurchase\u002FPurchaseSettings.cs`\n- Assets\u002FSamples (import): `framework-cs\u002Fapps\u002FUnityExample\u002FAssets\u002FSamples\u002FDevian Samples\u002F{version}\u002FMobilePackage\u002FRuntime\u002FPurchase\u002FPurchaseStorage.cs`\n\n\n- asmdef:\n  - `Devian.Samples.MobilePackage` (`Samples~\u002FMobilePackage\u002FRuntime\u002FDevian.Samples.MobilePackage.asmdef`)\n  - 참조: `Devian.Domain.Game` (TB_PURCHASE 테이블, GameResult)\n\n\n---\n\n\n## Singleton\n\n```csharp\nCompoSingleton\u003CPurchaseManager>.Instance\n```\n\n- Registry key: `PurchaseManager`\n- 다른 매니저에서 접근: `Singleton.Get\u003CPurchaseManager>()`\n\n\n---\n\n\n## Public API (Sample)\n\n\n- `InitializeAsync(ct)` → `Task\u003CGameResult>`\n  - IAP 초기화 (Connect + FetchProducts). 선택적 prewarm 호출이며, Purchase\u002FRetryInterruptedPurchase\u002FRestore 경로에서 lazy-init로 자동 호출될 수 있음.\n  - Idempotent: 여러 번 호출해도 동일 Task 반환.\n  - Editor에서는 즉시 `GAME_ERROR_TYPE.PURCHASE_UNSUPPORTED_PLATFORM` 반환.\n- `PurchaseAsync(internal_product_id, ct)` → `Task\u003CGameResult\u003CPurchaseFinalResult>>`\n  - 단일 구매 진입점. `TB_PURCHASE`에서 `Kind`를 조회하여 구매 유형(Consumable\u002FRental\u002FSubscription\u002FSeasonPass)을 자동 결정\n  - 최종 지급은 서버 `verifyPurchase` 결과만 신뢰\n  - 구매 보상(`AppliedRewards`)에 `amount \u003C 0` 값이 있으면 즉시 실패(`GAME_ERROR_TYPE.GAME_INVALID_ARGUMENT`) 처리한다.\n  - **Caller-managed client grant**: `NeedsClientGrantDelivery=true`이면 호출자가 보상을 적용한 뒤 `AckPurchaseClientGrantAppliedAsync`로 ACK\n- `RetryInterruptedPurchaseAsync(ct)` → `Task\u003CGameResult\u003CRetryInterruptedPurchaseResult>>`\n  - `PurchaseStorage.current`에 중단된 결제가 있으면 새 구매를 시작하지 않고 상태 전이를 재개\u002F마무리\n  - 중단 내역이 없으면 `Success(Status=SkippedNoCurrent)` (skip, 정상)\n  - UI\u002FDebug 표시는 반환 payload(`Status`, `Internal_product_id`, `ResultStatus`, `AppliedRewards`)를 사용\n- `AckPurchaseClientGrantAppliedAsync(purchaseId, ct)` — 로컬 지급 성공 보고\n- `ReportPurchaseClientGrantFailureAsync(purchaseId, ct)` — 로컬 지급 실패 보고\n- `RestoreAsync(ct)` (iOS 스토어 복원, manual\u002Ffallback)\n  - 스토어 복원 직후 서버 `getEntitlements`를 조회해 `mPasses\u002FmRentals`를 덮어써 복원한다.\n  - `pass`는 시즌 유효 구간(`TB_SEASON`)일 때만 복원한다.\n  - `rental`은 만료시각이 서버 현재시각보다 미래일 때만 복원하며, 누적 연장을 허용한다.\n- `GetLatestConsumablePurchase30dAsync(ct)` → `Task\u003CGameResult\u003CRecentPurchaseItem>>`\n  - 서버에서 최근 30일 내 최신 Consumable 구매 1건 조회\n- `SyncEntitlementsAsync(ct)` → `Task\u003CGameResult>`\n  - 서버 `getEntitlements`를 조회해 `mPasses\u002FmRentals`를 덮어써 동기화하고 결과 스냅샷을 반환한다.\n  - `rental`은 만료시각 미래값만 반영하며, 누적 연장을 허용한다.\n- `RefundAsync(ct)` → `Task\u003CGameResult\u003CRefundResult>>`\n  - 서버에서 환불\u002F조정 내역을 조회하여 로컬 인벤토리 회수 적용\n\n\n---\n\n\n## 컨텐츠 카탈로그 통합 (TB_PURCHASE 직접 참조)\n\nPurchaseManager가 Game 도메인 테이블을 직접 참조한다:\n\n- `ResolveRewardGroupId(internal_product_id)`: `TB_PURCHASE`에서 `Reward_group_id` 조회 (없으면 빈 값)\n- `PurchaseFinalResult`, `RetryInterruptedPurchaseResult`\n  - `Reward_group_id`와 `AppliedRewards: RewardData[]`를 포함한다.\n  - `skip`\u002F`reward_group_id 없음`\u002F이번 호출에서 지급 없음(`ALREADY_GRANTED + APPLIED_ACKED`)은 `AppliedRewards=[]`가 정상이다.\n- `BuildProductDefinitions()`: `TB_PURCHASE.GetAll()`에서 `is_active` 필터링 후 ProductDefinition 목록 생성\n  - 플랫폼별 StoreSku 매핑: `#if UNITY_IOS` → `Store_sku_apple`, `#elif UNITY_ANDROID` → `Store_sku_google`\n  - `Kind` → `ProductType` 매핑: Consumable→Consumable, Subscription→Subscription, SeasonPass→NonConsumable\n\n\n---\n\n\n## Server Integration (구현 완료)\n\n서버 구현의 상세 규칙\u002F스키마\u002F배포 절차는 이 문서가 아니라 `40\u002F44\u002F46` 문서를 우선한다.\n\n\n- **VerifyPurchaseAsync**: `FirebaseCallableManager.Instance.VerifyPurchaseAsync(data, ct)` — ✅ 구현됨\n  - 요청 키: `storeKey`, `internal_product_id`, `kind`, `payload`\n  - 응답: `GameResult\u003CVerifyPurchaseResponse>`\n- **reportPurchaseClientGrantResultAsync**: `FirebaseCallableManager.Instance.AckPurchaseClientGrantAsync(data, ct)` — ✅ 구현됨\n  - 요청 키: `purchaseId`, `clientGrantStatus`\n  - 응답: `GameResult`\n- **ackPurchaseStoreConfirmAsync**: `FirebaseCallableManager.Instance.AckPurchaseStoreConfirmAsync(data, ct)` — ✅ 구현됨\n  - 요청 키: `purchaseId`\n  - 응답: `GameResult`\n- **SyncEntitlementsAsync**: `FirebaseCallableManager.Instance.GetEntitlementsAsync(ct)` 기반 복원 — ✅ 구현됨\n  - 응답: `GameResult\u003CEntitlementsSnapshot>` (서버 entitlements를 `mPasses\u002FmRentals`에 덮어쓴 결과)\n- **GetLatestConsumablePurchase30dAsync**: `FirebaseCallableManager.Instance.GetRecentPurchases30dAsync(data, ct)` — ✅ 구현됨\n  - 응답: `GameResult\u003CRecentPurchaseItem>`\n- **syncRefundsPageAsync**: `FirebaseCallableManager.Instance.GetPurchaseAdjustmentsAsync(data, ct)` — ✅ 구현됨\n  - 응답: `GameResult\u003CRefundPageResult>` (raw item → PurchaseManager가 domain 보강)\n- **ackRefundAppliedAsync**: `FirebaseCallableManager.Instance.AckRefundAppliedAsync(data, ct)` — ✅ 구현됨\n  - 응답: `GameResult`\n- Firebase callable 호출\u002F에러 매핑\u002F응답 파싱은 [23-firebase-callable-manager](..\u002F..\u002F23-firebase-callable-manager\u002FSKILL.md)에 통합.\n  PurchaseManager는 `FunctionsException`을 직접 catch하지 않는다. `using Firebase.Functions` 불필요.\n  domain 변환(ResolveRewardGroupId 등)은 PurchaseManager가 typed result 수신 후 수행한다.\n\n\n---\n\n\n## Post-Sync Orchestration (SaveData 로드 후 표준 순서)\n\n1. `SaveDataManager.SyncGameStorageAsync(ct)` → `SyncResult`\n2. `SaveDataManager`가 성공 시 payload를 직접 복원 → inventory, purchase, account 역직렬화\n3. `PurchaseManager.InitializeAsync(ct)` → IAP 초기화\n4. `PurchaseManager.RetryInterruptedPurchaseAsync(ct)` → 중단 구매 복구\n5. `PurchaseManager.RefundAsync(ct)` → 환불 처리\n6. `PurchaseManager.SyncEntitlementsAsync(ct)` → 서버 `getEntitlements` 기준으로 `mPasses\u002FmRentals` 덮어쓰기 복원\n   - `pass`: 시즌 유효 구간 체크\n   - `rental`: 만료시각 미래값만 반영, 누적 연장 허용\n\n\n---\n\n\n## Hard Rules (Sample must follow)\n\n\n- Unity IAP \"스토어 구매 성공 콜백\"만으로 지급\u002FNoAds 적용 금지\n- 최종 지급\u002F상태 반영은 서버(Cloud Functions) 결과(verifyPurchase)만 기준으로 한다.\n- 지급 여부는 서버 `verifyPurchase.resultStatus`만 기준으로 한다(스토어 콜백만으로 지급 금지).\n- `resultStatus == GRANTED`이면 `ConfirmPurchase` + `ackPurchaseStoreConfirm`를 먼저 수행한 뒤 로컬 지급\u002F`ackPurchaseClientGrant(APPLIED_ACKED)`를 진행한다.\n- `PurchaseStorage.current`는 `Confirm + storeConfirm ACK + clientGrant report`가 종결되기 전에는 clear하지 않는다.\n- 구매 보상(`RewardData[]`)의 `amount \u003C 0`은 허용하지 않는다. 음수 보상이 감지되면 구매\u002F복구 경로를 실패 처리한다.\n- 로컬 지급 실패 시 `FAILED_REPORTED`를 서버에 기록할 수 있으나, confirm 미완 상태에서는 `current`를 유지해 복구 경로를 보존한다.\n- `resultStatus == ALREADY_GRANTED`라도 `clientGrantStatus == PENDING` 또는 `FAILED_REPORTED`이면 로컬 지급 복구 경로를 사용할 수 있다.\n- `reward_group_id`가 비어 있으면 로컬 보상 지급은 스킵하고, 클라이언트 지급 완료 처리만 진행한다. (결제\u002F재구매 동일 규칙)\n- 구매 전 인증 게이트는 `LoginManager` API(`IsPurchaseLoginReady`, `EnsurePurchaseLoginReadyAsync`)를 사용한다. (`FirebaseAuth.CurrentUser` 직접 판정 금지)\n- 로컬\u002F클라우드 저장용 구매 상태는 `PurchaseManager.Instance.Storage`(`PurchaseStorage`)에 기록한다.\n- `PurchaseStorage`는 진행 중 결제(`current`), 환불\u002F지원 대응용 최소 로그(`refundSupportLogs`), 환불 동기화 상태(`refundSync`)를 저장한다.\n- 실패 코드\u002F메시지\u002F최근 실패 요약\u002F전체 이력\u002F영수증(raw receipt)은 저장 금지.\n- 환불\u002F지원 로그 조회\u002F삭제는 `PurchaseStorage` API를 직접 사용한다.\n  - `GetRefundSupportLogs()`, `TryGetRefundSupportLog(...)`, `RemoveRefundSupportLog(purchaseId)`, `ClearRefundSupportLogs()`\n\n\n---\n\n\n## Related SSOT\n\n\n- `skills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F14-purchase-settings\u002FSKILL.md`\n- `skills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F03-ssot\u002FSKILL.md`\n- `skills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F33-purchase-storage\u002FSKILL.md`\n- `skills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F09-ssot-operations\u002FSKILL.md`\n- `skills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F40-purchase-backend-firebase\u002FSKILL.md`\n- `skills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F43-purchase-client-server-integration\u002FSKILL.md`\n- `skills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F11-purchase-repo-firebase-functions-setup\u002FSKILL.md`\n- `skills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F46-purchase-decisions\u002FSKILL.md`\n",{},"main","8cb5bd877a3a7004867d2f55697cb9e4ff2f1734","skills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F10-purchase-manager","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian","https:\u002F\u002Fgithub.com\u002Fdevwinsoft","Kim Hyong Joon","2026-04-12 18:44:10",{"source":7,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add devwinsoft\u002Fdevian --skill 10-purchase-manager",{"tool":36,"command":37},"bunx","bunx skills add devwinsoft\u002Fdevian --skill 10-purchase-manager",{"tool":39,"command":40},"pnpm","pnpm dlx skills add devwinsoft\u002Fdevian --skill 10-purchase-manager","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F10-purchase-manager\u002FSKILL.md",true,[44],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"agents\u002Fopenai.yaml","REFERENCE","参考文档",120,"https:\u002F\u002Fgithub.com\u002Fmalinskibeniamin\u002Fskills\u002Fblob\u002Fmain\u002Fcodex-skills\u002Fci-maintenance\u002Fagents\u002Fopenai.yaml",[51,57,65,73,82,89],{"skillNo":52,"name":53,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":19},"01M6CBX3K2JJV38ANHVGCAT8A0","devian","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002FSKILL.md",[],[53],{"skillNo":58,"name":59,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M6CBX210BFMM8AMN770J9WY8","90-project-archive","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F90-project-archive\u002FSKILL.md",[],[63,64],"archive","90 project archive",{"skillNo":66,"name":67,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M6CBWZSGRR9R3YJZB3177667","30-env-management","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F30-env-management\u002FSKILL.md",[],[71,72],"management","30 env management",{"skillNo":74,"name":75,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":19},"01M6CBWYD3TGWBQV7V35551THF","19-page-push-send","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F20-operation\u002F19-page-push-send\u002FSKILL.md",[],[79,80,81],"push","page","19 page push send",{"skillNo":83,"name":84,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M6CBWWRQ05A7604GHJKTPJTF","18-page-savedata","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F20-operation\u002F18-page-savedata\u002FSKILL.md",[],[80,88],"18 page savedata",{"skillNo":90,"name":91,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M6CBWVH4S2VF1V7B2GBTESCT","17-page-deobfuscate","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F20-operation\u002F17-page-deobfuscate\u002FSKILL.md",[],[80,95],"17 page deobfuscate"]