[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CBM9Y7NVJ024S5PEETF7XB":3,"skill-same:01M6CBM9Y7NVJ024S5PEETF7XB":51},{"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":20,"linkOnly":21,"markdownContent":22,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":13,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":29,"updatedAt":30,"install":31,"resources":44},"01M6CBM9Y7NVJ024S5PEETF7XB","33-purchase-storage",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\u002F33-purchase-storage\u002FSKILL.md",[],[18,19],"storage","33 purchase storage","2026-11-10 10:12:30",false,"# 33-purchase-storage\n\n\nPurchaseStorage(구매 상태 스냅샷)의 위치\u002F역할\u002F저장 규칙을 설명한다.\n\n## 문서 경계 (Scope)\n\n- 이 문서는 `PurchaseStorage`의 **역할\u002F필드 범위\u002F소유자(PurchaseManager)** 를 정의한다.\n- 전체 구매 이력(ledger) 설계, 서버 검증\u002F멱등, 환불\u002F복구 정책은 이 문서의 범위가 아니다.\n- 서버 정본은 `40\u002F41\u002F42\u002F46`, 클라이언트 구매 흐름은 `10-purchase-manager`를 참조한다.\n\n\n---\n\n\n## Purpose\n\n- `PurchaseManager`의 **진행 중인 결제 상태(current)** 만 최소 정보로 저장한다.\n- `PurchaseManager`가 소유하며 SaveData(local\u002Fcloud) 경로에 포함될 수 있게 한다.\n- 앱 재시작\u002F동기화 이후에도 미완료 구매 흐름(verify 성공 후 ACK\u002FConfirm 이전 등)의 복구 보조용으로 사용할 수 있다.\n\n\n---\n\n\n## Ownership (SSOT)\n\n- 소유자: `PurchaseManager`\n- 사용처: `PurchaseManager` (구매 시작\u002F스토어 pending\u002Fverify 성공\u002F로컬지급 완료\u002FACK 완료 시점에 기록)\n- 저장 경로: `SaveDataManager` JSON의 `purchase` 섹션\n\n중요:\n- `PurchaseStorage`는 **PurchaseManager 소유 필드**이다.\n- `PurchaseStorage`는 **서버 구매 원장(Firestore purchases\u002Fgrants\u002Fentitlements) 대체가 아니다**.\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\u002FPurchaseStorage.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\u002FPurchaseStorage.cs`\n\n- asmdef: `Devian.Samples.MobilePackage` (`Samples~\u002FMobilePackage\u002FRuntime\u002FDevian.Samples.MobilePackage.asmdef`)\n\n\n---\n\n\n## Data Scope (Minimal Snapshot)\n\n`PurchaseStorage`는 \"전체 구매 기록 배열\"을 저장하지 않는다.\n저장 범위는 아래 3개로 제한한다.\n- `current` (진행 중 결제 1건)\n- `refundSupportLogs` (환불\u002F지원 대응용 최소 로그, bounded)\n- `refundSync` (환불 동기화 처리 완료 키, bounded)\n\n### 1) current (진행 중 구매, 최대 1건)\n\n- 코드 구조는 `PurchaseStorage.Current` (중첩 클래스 `CurrentPurchaseState`)로 묶어 관리한다.\n\n- `isPurchaseInProgress`\n- `internal_product_id`\n- `kind`\n- `storeKey`\n- `startedAtUtcMs`\n- `isStorePending`\n- `storePendingAtUtcMs`\n- `purchaseId` (서버 verify 후 확정되는 멱등키)\n- `verifyStatus` (`GRANTED` \u002F `ALREADY_GRANTED` 등 verify 결과)\n- `clientGrantApplied` (로컬 지급 완료 여부)\n- `clientGrantReported` (로컬 지급 결과를 서버에 보고 완료했는지)\n- `storeConfirmedLocal` (클라가 `ConfirmPurchase`를 로컬에서 성공 호출했는지)\n\n### 2) refundSupportLogs (환불\u002F지원 대응용 최소 로그, bounded)\n\n- 목적: 환불\u002F지원 대응 시 필요한 최소 구매 상태 스냅샷 보조 로그\n- 정본 아님: 서버 purchases ledger가 정본\n- bounded: 무제한 저장 금지 (현재 구현은 개수 상한 적용)\n- 보관 정책(초기값, 구현됨):\n  - 보관 기간(TTL): `30일` (`lastUpdatedAtUtcMs` 기준)\n  - 개수 상한(Cap): `32개`\n  - 정리 순서: `TTL prune` 후 `count cap trim`\n- 정리 실행 시점(구현됨):\n  - `UpsertRefundSupportLog(...)` 직후\n  - `RestoreRefundSupportLogs(...)` 복원 직후\n  - `SaveDataManager.ToJson()` 경로의 `PurchaseStorage.PruneRefundSupportLogs()` 호출 시\n- 항목 예시:\n  - `purchaseId`\n  - `internal_product_id`\n  - `kind`\n  - `storeKey`\n  - `verifyStatus`\n  - `clientGrantStatus`\n  - `storeConfirmStatus`\n  - `firstSeenAtUtcMs`\n  - `lastUpdatedAtUtcMs`\n\n### 2-1) 조회\u002F삭제 API (구현됨)\n\n- 조회:\n  - `RefundSupportLogs` (read-only 프로퍼티)\n  - `GetRefundSupportLogs()`\n  - `TryGetRefundSupportLog(purchaseId, out entry)`\n- 삭제:\n  - `RemoveRefundSupportLog(purchaseId)` (개별 삭제)\n  - `ClearRefundSupportLogs()` (전체 삭제)\n- 식별\u002F표시:\n  - 환불 로그 항목에는 `internal_product_id`가 포함되어 있어 상품 식별에 사용할 수 있다.\n\n### 3) refundSync (환불 동기화 상태, 구현됨)\n\n- 목적: `RefundAsync()`가 서버의 환불\u002F조정 내역을 페이지네이션 조회할 때, 처리 완료 위치와 이미 처리한 항목을 저장하여 중복 처리를 방지\n- 필드:\n  - `cursor` (string) — 서버 페이지네이션 커서. `RefundAsync()` 호출마다 newest부터 재스캔하므로 **런타임에서 사용하지 않는다**. JSON codec에서 persist되지만 `RefundAsync()`는 항상 빈 커서로 시작한다. (dead field, 향후 정리 대상)\n  - `processedKeys` (string[]) — 이미 처리 완료한 refund adjustment 키 목록. 중복 처리 방지용으로 persist\n- 개수 상한(Cap): `128개` (`MaxProcessedRefundSyncKeys`)\n  - 초과 시 가장 오래된 키부터 FIFO 제거\n- API (구현됨):\n  - `RefundSyncCursor` (read-only 프로퍼티)\n  - `ProcessedRefundSyncKeys` (read-only 프로퍼티)\n  - `SetRefundSyncCursor(cursor)`\n  - `IsRefundAdjustmentProcessed(key)`\n  - `MarkRefundAdjustmentProcessed(key)`\n  - `ClearRefundSyncState()` (커서 + 처리 키 전체 초기화)\n  - `RestoreRefundSyncState(cursor, processedKeys)` (SaveData 복원 시)\n\n### Future (지금 구현 안 함)\n\n- `lastSyncedServerUtcMs`\n\n위 항목은 필요 시 추가할 수 있으나, 현재 구현 범위에 포함되지 않는다.\n\nNOTE:\n- `noAdsExpireAtClientUtcMs`, `seasonPassOwnership`, `Rental 로컬 캐시 상태`는 **InventoryStorage로 이동됨** (PurchaseStorage 범위 아님).\n  - InventoryStorage: `Rentals` (rentalTypeId → expiresAtClientUtcMs), `SeasonPasses` (seasonPassTypeId → owned)\n  - Reward 파이프라인(`REWARD_TYPE.RENTAL` \u002F `REWARD_TYPE.PASS`)을 통해 관리된다.\n\n\n---\n\n\n## Hard Rules\n\n### 1) 전체 구매 이력 저장 금지\n\n- `PurchaseStorage`는 구매 이력 리스트\u002F배열(정본 로그)을 저장하지 않는다.\n- 전체 구매 내역의 정본은 서버(Firestore purchases\u002Fentitlements\u002Fgrants)다.\n\n### 1-1) 구매 실패 내역 저장 금지\n\n- 실패 코드\u002F실패 메시지\u002F최근 실패 요약을 `PurchaseStorage`에 저장하지 않는다.\n- 사용하지 않는 진단 데이터는 클라이언트에 저장하지 않는다.\n\n### 2) 민감정보 저장 금지\n\n- raw receipt \u002F 영수증 payload 저장 금지\n- Firebase\u002FAuth token 저장 금지\n- Store token\u002F서명 원문 저장 금지\n\n### 3) 서버 검증\u002F멱등 대체 금지\n\n- `PurchaseStorage`의 값으로 지급 결정\u002F환불 판정\u002F중복 지급 방지를 수행하지 않는다.\n- 지급\u002F엔타이틀먼트 최종 판정은 서버 `verifyPurchase` + `getEntitlements` 복원 결과를 사용한다.\n\n### 4) PurchaseManager 소유 유지\n\n- 로컬\u002F클라우드 저장 연동을 위해 `PurchaseManager`가 `PurchaseStorage`를 직접 소유한다.\n- `SaveDataManager`는 직렬화\u002F역직렬화 시 `PurchaseManager.Instance.Storage`를 사용한다.\n\n\n---\n\n\n## Integration Notes\n\n- `PurchaseManager`는 자신의 `Storage`에 기록한다.\n- `SaveDataManager.ClearGameState()`는 `PurchaseStorage.ClearAll()`을 호출한다.\n- SaveData(local\u002Fcloud)는 `SaveDataManager` JSON 전체를 저장하므로 `purchase` 섹션도 함께 저장\u002F복구된다.\n- `PurchaseStorage`는 `current`, `refundSupportLogs`, `refundSync`만 저장하며, 실패 이력\u002F전체 구매 정본 로그는 저장하지 않는다.\n- `current`는 복구 워크아이템이며, `Confirm + storeConfirm ACK + clientGrant report`가 종결되기 전에는 clear하지 않는다.\n- `storeConfirmedLocal=true` + `storeConfirmStatus=PENDING`인 경우 `RetryInterruptedPurchaseAsync()`는 `ackPurchaseStoreConfirm`부터 재개할 수 있어야 한다.\n- `refundSupportLogs`는 지원\u002F환불 대응 보조용이며, TTL\u002FCap 정책에 따라 자동 정리된다.\n\n\n---\n\n\n## Related\n\n- [00-overview](..\u002F00-overview\u002FSKILL.md) — Purchase System 개요\n- [03-ssot](..\u002F03-ssot\u002FSKILL.md) — Purchase 통합 SSOT\n- [21-savedata-system\u002F43-savedata-json-codec](..\u002F..\u002F21-savedata-system\u002F43-savedata-json-codec\u002FSKILL.md) — SaveData JSON 직렬화 정본\n- [21-savedata-system\u002F00-overview](..\u002F..\u002F21-savedata-system\u002F00-overview\u002FSKILL.md) — local\u002Fcloud 저장 시스템 개요\n",{},"main","8cb5bd877a3a7004867d2f55697cb9e4ff2f1734","skills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F33-purchase-storage","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":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add devwinsoft\u002Fdevian --skill 33-purchase-storage",{"tool":37,"command":38},"bunx","bunx skills add devwinsoft\u002Fdevian --skill 33-purchase-storage",{"tool":40,"command":41},"pnpm","pnpm dlx skills add devwinsoft\u002Fdevian --skill 33-purchase-storage","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F33-purchase-storage\u002FSKILL.md",true,[45],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"agents\u002Fopenai.yaml","REFERENCE","参考文档",119,"https:\u002F\u002Fgithub.com\u002Fmalinskibeniamin\u002Fskills\u002Fblob\u002Fmain\u002Fcodex-skills\u002Fconnect-query\u002Fagents\u002Fopenai.yaml",[52,58,66,74,83,90],{"skillNo":53,"name":54,"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":55,"categories":56,"keywords":57,"publishedAt":20},"01M6CBX3K2JJV38ANHVGCAT8A0","devian","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002FSKILL.md",[],[54],{"skillNo":59,"name":60,"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":61,"categories":62,"keywords":63,"publishedAt":20},"01M6CBX210BFMM8AMN770J9WY8","90-project-archive","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F90-project-archive\u002FSKILL.md",[],[64,65],"archive","90 project archive",{"skillNo":67,"name":68,"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":69,"categories":70,"keywords":71,"publishedAt":20},"01M6CBWZSGRR9R3YJZB3177667","30-env-management","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F30-env-management\u002FSKILL.md",[],[72,73],"management","30 env management",{"skillNo":75,"name":76,"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":77,"categories":78,"keywords":79,"publishedAt":20},"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",[],[80,81,82],"push","page","19 page push send",{"skillNo":84,"name":85,"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":86,"categories":87,"keywords":88,"publishedAt":20},"01M6CBWWRQ05A7604GHJKTPJTF","18-page-savedata","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F20-operation\u002F18-page-savedata\u002FSKILL.md",[],[81,89],"18 page savedata",{"skillNo":91,"name":92,"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":93,"categories":94,"keywords":95,"publishedAt":20},"01M6CBWVH4S2VF1V7B2GBTESCT","17-page-deobfuscate","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F20-operation\u002F17-page-deobfuscate\u002FSKILL.md",[],[81,96],"17 page deobfuscate"]