[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CBKN3G9W2NEVWDXR9D667Z":3,"skill-same:01M6CBKN3G9W2NEVWDXR9D667Z":59},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":33,"linkOnly":34,"markdownContent":35,"markdownBody":36,"frontMatter":37,"refName":38,"commitSha":39,"skillDirectory":40,"forksCount":14,"repositoryHtmlUrl":41,"repositoryHomepageUrl":6,"ownerHtmlUrl":42,"ownerBlogUrl":6,"ownerDescription":43,"updatedAt":44,"install":45,"resources":58},"01M6CBKN3G9W2NEVWDXR9D667Z","03-ssot",null,"Define the single source of truth for the purchase system across Unity IAP, backend verification, entitlements, restore rules, and routing. Use when deciding canonical purchase concepts and cross-document invariants for the purchase module.","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\u002F03-ssot\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32],"03 ssot","routing","verification","iap","system","Rules","use","backend","restore","2026-11-10 10:12:30",false,"---\nname: 03-ssot\ndescription: Define the single source of truth for the purchase system across Unity IAP, backend verification, entitlements, restore rules, and routing. Use when deciding canonical purchase concepts and cross-document invariants for the purchase module.\n---\n\n# 03-ssot — 30-purchase-system (통합 SSOT)\n\n\nStatus: ACTIVE\nAppliesTo: v10\n\n\n## 이 문서가 정본이다 (SSOT)\n\n이 문서는 30-purchase-system의 **단일 SSOT 허브**이다.\n기존 04~08 분할 문서의 핵심 내용이 이 문서에 통합되었다.\n운영\u002F보안\u002F테스트\u002FDoD는 [09-ssot-operations](..\u002F09-ssot-operations\u002FSKILL.md)를 참조한다.\n\n## 관심사별 라우팅 (중복 금지)\n\n- 운영\u002F보안\u002F테스트\u002FDoD 체크리스트: `..\u002F09-ssot-operations\u002FSKILL.md`\n- PurchaseStorage(로컬\u002F클라우드 저장용 최소 상태 스냅샷): `..\u002F33-purchase-storage\u002FSKILL.md`\n- Firebase Functions + Firestore 구현 상세: `..\u002F40-purchase-backend-firebase\u002FSKILL.md`\n- Firebase 레포 구성\u002FCLI\u002F배포 셋업: `..\u002F11-purchase-repo-firebase-functions-setup\u002FSKILL.md`\n- 고정 결정사항(Callable 이름\u002F경로\u002F시크릿\u002F정책 결정): `..\u002F46-purchase-decisions\u002FSKILL.md`\n\n이 문서(03)는 통합 SSOT 허브\u002F핵심 합의에 집중하고, 구현\u002F운영 상세의 원문은 위 문서로 분리한다.\n\n\n## 우선순위\n\n- Root SSOT: `skills\u002Fdevian\u002F10-module\u002F03-ssot\u002FSKILL.md`\n- Unity 관련 SSOT: `skills\u002Fdevian-unity\u002F03-ssot\u002FSKILL.md`\n- 결제\u002FIAP 관련 SSOT: 이 문서\n\n충돌 시 Root SSOT의 정의\u002F플레이스홀더\u002F규약이 우선한다.\n\n\n---\n\n\n## A. Unity IAP (from 04-ssot-unity-iap)\n\n\n### 전제\n\n- 결제 SDK는 Unity **In-App Purchasing (Unity IAP) 5.1.2** (`com.unity.purchasing@5.1.2`)를 사용한다.\n- 스토어별 구현 차이는 존재하지만, 최종 지급\u002F상태는 서버 검증 결과를 따른다.\n\n\n### Unity IAP 5.x v5 API 정책\n\n- 현재 구현은 **v5 신규 API** (`StoreController` + `UnityIAPServices` + 이벤트 기반)를 사용한다.\n- `[Obsolete]` Legacy API (`IDetailedStoreListener`, `UnityPurchasing.Initialize`, `ConfigurationBuilder`, `IStoreController`, `Product.receipt`)는 **사용하지 않는다**.\n\n#### v5 API 사용 패턴\n\n| 기능 | v5 API |\n|------|--------|\n| 초기화 | `UnityIAPServices.StoreController()` → `await controller.Connect()` → `controller.FetchProducts(definitions)` |\n| 제품 등록 | `List\u003CProductDefinition>` + `controller.FetchProducts(...)` (ProductCatalog에서 변환) |\n| 구매 시작 | `controller.PurchaseProduct(productId)` |\n| 구매 확인 | `controller.ConfirmPurchase(pendingOrder)` |\n| Receipt 접근 | `PendingOrder.Info.Receipt` |\n| Restore | `controller.RestoreTransactions(Action\u003Cbool, string?>)` (플랫폼 분기 불필요) |\n| 구매 성공 콜백 | `controller.OnPurchasePending` (PendingOrder) |\n| 구매 실패 콜백 | `controller.OnPurchaseFailed` (FailedOrder) |\n| 제품 Fetch 콜백 | `controller.OnProductsFetched` \u002F `OnProductsFetchFailed` |\n\n#### 참고: 4.x → 5.x 주요 변경 사항\n\n| 항목 | 변경 |\n|------|------|\n| Amazon\u002FUWP\u002FFacebook 스토어 | **제거됨** |\n| Apple Receipt Validation | **Deprecated** (Google Play만 지원) |\n| `IAppleExtensions.RestoreTransactions` | `Action\u003Cbool>` → `Action\u003Cbool, string>` |\n\n\n### 플랫폼 차이\n\n#### iOS: Restore(복원)\n\n- iOS는 재설치\u002F기기 변경 시 Restore 플로우가 필요하다.\n- Restore는 \"스토어 구매 이력 재동기화 트리거\"이며,\n  최종 Entitlement는 서버 상태(purchases\u002Fentitlements)를 기준으로 확정한다.\n\n#### Android: 복원 UX\n\n- Android는 보통 Restore 버튼을 직접 노출하지 않고,\n  앱 시작\u002F로그인 시 서버 상태 동기화로 복원을 처리해도 된다.\n\n\n### Pending \u002F Deferred 상태\n\n- iOS: 승인 대기(deferred) 상태가 발생할 수 있다.\n- Android: pending 상태가 발생할 수 있다.\n- 공통 규칙: **PENDING\u002FDEFERRED 상태에서는 지급 금지** (서버 검증 확정 전 지급 금지)\n\n\n---\n\n\n## B. Product Catalog (from 05-ssot-product-catalog)\n\n\n### SSOT 원칙\n\n#### 1) 내부 표준 ID가 정본\n\n- 상위 로직은 `internal_product_id`를 정본으로 사용한다.\n- Store SKU는 매핑 데이터로만 취급한다.\n\n#### 2) 타입 규칙\n\n- Consumable: 재화 등 반복 구매\u002F즉시 지급\n- Rental: 기간제 구매(예: NoAds 30일). 반복 구매 허용, 만료일 연장 방식\n- Subscription: \"구독 기반 NoAds\" 등 상태 기반\n- Season Pass: 시즌별 구매 1회성 Entitlement로 운영\n\n- kind의 정본 enum은 컨텐츠 레이어가 정의한 `PurchaseKind`다.\n- 테이블(`ShopTable.xlsx` PURCHASE.kind)의 타입은 `PurchaseKind`를 사용한다.\n\n### 카탈로그 통합\n\nPurchaseManager는 `TB_PURCHASE` 테이블을 **직접 참조**하여 카탈로그를 구성한다.\n`Devian.Samples.MobilePackage.asmdef`에 `Devian.Domain.Game` 참조가 포함되어 있다.\n\nPurchase 지급을 위해 `internal_product_id -> reward_group_id` 변환이 필요하다.\n- `PurchaseManager`가 `ResolveRewardGroupId(internal_product_id)` → `TB_PURCHASE.Get(internal_product_id).Reward_group_id`로 직접 변환한다.\n- `BuildProductDefinitions()` → `TB_PURCHASE.GetAll()`에서 `is_active` 필터링 후 ProductDefinition 목록을 생성한다.\n\n### Unity IAP 5.x (v5) Catalog Notes\n\n- 본 SSOT에서 \"카탈로그\"는 **내부 ID(`internal_product_id`) ↔ 스토어 SKU(Apple\u002FGoogle) 매핑 데이터**를 의미한다.\n- Unity IAP 5.x(v5)에서는 과거 방식의 `ProductCatalog.LoadDefaultCatalog()` 같은 런타임 로딩 API에 의존하지 않는다. (obsolete 전제 제거)\n- 런타임에서는 \"등록된 제품 정의\"를 사용해 구매를 시작하며, 상위 로직은 반드시 `internal_product_id`만 사용한다.\n- 스토어 SKU는 플랫폼별 매핑 데이터일 뿐이며, 운영\u002F코드에서 직접 참조하지 않는다.\n\n### NEEDS CHECK (형준 결정 필요)\n\n#### Product Catalog (상품 요약\u002F매핑) SSOT — ✅ 전체 결정됨\n- [x] SSOT 저장 위치: **(A) Devian input 테이블(Excel) 기반** — 결정됨\n  - PURCHASE 테이블 스키마를 이 문서(03-ssot)에서 SSOT로 정의한다.\n  - `ShopTable.xlsx`의 PURCHASE 시트에서 데이터를 관리한다.\n- [x] `{buildInputJson}` 도메인 등록: — 결정됨\n  - 도메인 등록 정보는 컨텐츠 레이어 SSOT에서 관리\n- [x] ShopTable.xlsx 경로: — 결정됨\n  - 경로는 컨텐츠 레이어 SSOT에서 관리\n- [x] PURCHASE 테이블 스키마\u002F필드: — 결정됨\n  - `internal_product_id` (string, pk) — 내부 상품 ID (정본)\n  - `reward_group_id` (string) — 지급 Reward Key, `internal_product_id -> reward_group_id` 변환의 SSOT\n  - `kind` (PurchaseKind) — 상품 타입 (`Consumable` \u002F `Rental` \u002F `Subscription` \u002F `SeasonPass`)\n  - `is_active` (bool) — 운영 활성 토글\n  - `store_sku_apple` (string) — Apple Store SKU\n  - `store_sku_google` (string) — Google Play SKU\n- [x] 시즌 매핑 필드 위치: — 결정됨\n  - 시즌 구매 제한용 `season_id`는 `SHOP_ITEM_PURCHASE.season_id`에서 관리한다. (`PURCHASE` 스키마에는 포함하지 않는다.)\n\n\n---\n\n\n## C. Verification Server + Idempotency + Firestore Ledger (from 06-ssot-verify-idempotency)\n\n\n### SSOT (핵심 합의)\n\n- 별도 VM 서버 없이 **Firebase Cloud Functions**를 \"검증 서버\"로 사용한다.\n- 결제\u002F구매 정보는 **Firestore Cloud에 저장**한다. (원장\u002Fentitlements)\n- 클라이언트는 결제 원장에 직접 write 하지 않는다. (서버 write only)\n- 멱등 처리(Idempotency)로 중복 verify\u002F중복 지급을 방지한다.\n\n구현 상세(함수 구조\u002F스키마\u002F인덱스)는 `40`, 레포\u002F배포 셋업은 `44`, 최종 고정 결정값은 `46`을 참조한다.\n\n\n### resultStatus (정본 enum)\n\n클라이언트·서버 모두 아래 값만 사용한다. (문자열 비교, 대문자)\n\n| 값 | 의미 |\n|----|------|\n| `GRANTED` | 신규 검증 성공 — 지급 실행 |\n| `ALREADY_GRANTED` | 동일 구매 재요청 — 이미 지급됨(멱등) |\n| `REJECTED` | 스토어 검증 실패 \u002F 위변조 |\n| `PENDING` | 스토어가 아직 확정하지 않은 상태 (deferred\u002Fpending) — 지급 금지 |\n| `REVOKED` | 환불\u002F취소 등으로 사후 철회 |\n| `REFUNDED` | 스토어 환불 확인 |\n\n- Firestore purchase 문서의 정본 상태 필드는 `verifyStatus`다. (`resultStatus`와 같은 의미의 서버 상태)\n- `clientGrantStatus`는 클라이언트 로컬 지급 결과 보고 상태를 별도로 저장한다. (`PENDING` \u002F `APPLIED_ACKED` \u002F `FAILED_REPORTED`)\n- `storeConfirmStatus`는 스토어 `ConfirmPurchase` 처리 상태를 별도로 저장한다. (`PENDING` \u002F `CONFIRMED`)\n- 01-policy의 기존 표기(`GRANTED|ALREADY_GRANTED|REJECTED|PENDING`)와 정합.\n\n\n### 엔드포인트(최소 세트)\n\n#### 1) verifyPurchase (Callable 권장)\n\n- 입력\n  - `uid` — Auth context에서 확보 (클라가 보내지 않음)\n  - `storeKey: string` — \"apple\" | \"google\"\n  - `internal_product_id: string`\n  - `kind: string` — \"Consumable\" | \"Rental\" | \"Subscription\" | \"SeasonPass\" (=`PurchaseKind` string)\n  - `payload: string` — 스토어 영수증\u002F검증 데이터 (클라에서 `BuildVerifyPayload(receipt)` 결과)\n- 처리\n  1) 스토어 서버 검증(Apple\u002FGoogle)\n  2) Firestore 원장 기록 upsert (멱등)\n  3) 결과 반환 (entitlements 갱신은 별도 `getEntitlements` 호출로 분리)\n- 출력\n  - `resultStatus: string` — 위 enum 중 하나\n  - `purchaseId: string` — `{storeKey}_{storePurchaseId}`\n  - `verifyStatus: string` — 서버 purchase 상태 필드(`verifyStatus`)와 정합\n  - `clientGrantStatus: string` — `\"PENDING\" | \"APPLIED_ACKED\" | \"FAILED_REPORTED\"`\n  - `storeConfirmStatus: string` — `\"PENDING\" | \"CONFIRMED\"`\n  - `grants: array` — (server informational, 클라 지급 입력으로 미사용) 지급 내역 참고용. 보상은 `reward_group_id` 경로로 지급\n  - `entitlementsSnapshot: object?` — (optional) 갱신된 entitlements 스냅샷. GRANTED\u002FALREADY_GRANTED 시 포함. 클라는 `ParseEntitlementsSnapshot`으로 파싱 + `cacheEntitlementsSnapshot`으로 InventoryStorage에 동기화\n\n##### C# ↔ Callable 필드 매핑\n\n| C# (`VerifyPurchaseRequest`) | Callable JSON key | 비고 |\n|------------------------------|-------------------|------|\n| `Internal_product_id` | `internal_product_id` | |\n| `Kind` (enum → string) | `kind` | `\"Consumable\"` \u002F `\"Rental\"` \u002F `\"Subscription\"` \u002F `\"SeasonPass\"` |\n| `Store` | `storeKey` | |\n| `Payload` | `payload` | |\n\n| Callable JSON response | C# (`VerifyPurchaseResponse`) | 비고 |\n|------------------------|-------------------------------|------|\n| `resultStatus` | `ResultStatus` | 위 enum 값 |\n| `purchaseId` | `PurchaseId` | verify 멱등키 |\n| `verifyStatus` | `VerifyStatus` | Firestore purchase 상태 필드와 정합 |\n| `clientGrantStatus` | `ClientGrantStatus` | 로컬 지급 결과 보고 상태 |\n| `storeConfirmStatus` | `StoreConfirmStatus` | 스토어 Confirm 처리 상태 |\n| `grants[]` | (클라이언트 미사용 — 무시) | 서버 informational. 보상은 `reward_group_id` 경로로 지급 |\n| `entitlementsSnapshot` | `Snapshot` (`EntitlementsSnapshot?`) | optional |\n\n#### 1-1) ackPurchaseClientGrant (Callable)\n\n- 입력\n  - `uid` — Auth context에서 확보 (클라가 보내지 않음)\n  - `purchaseId: string`\n  - `clientGrantStatus: string` — `\"APPLIED_ACKED\"` | `\"FAILED_REPORTED\"`\n- 처리\n  1) purchase 문서 소유자\u002F상태 확인 (`verifyStatus == GRANTED`)\n  2) `clientGrantStatus = APPLIED_ACKED | FAILED_REPORTED` 멱등 업데이트\n- 출력\n  - `purchaseId`\n  - `verifyStatus`\n  - `clientGrantStatus`\n\n#### 1-2) ackPurchaseStoreConfirm (Callable)\n\n- 입력\n  - `uid` — Auth context에서 확보 (클라가 보내지 않음)\n  - `purchaseId: string`\n- 처리\n  1) purchase 문서 소유자\u002F상태 확인 (`verifyStatus == GRANTED`)\n  2) `storeConfirmStatus = CONFIRMED` 멱등 업데이트\n- 출력\n  - `purchaseId`\n  - `verifyStatus`\n  - `clientGrantStatus`\n  - `storeConfirmStatus`\n\n#### 2) getEntitlements (Callable\u002FHTTPS 중 택1)\n\n- 입력: `uid` (Auth context)\n- 출력:\n\n| Callable JSON response | C# (`EntitlementsSnapshot`) | 비고 |\n|------------------------|------------------------------|------|\n| `ownedSeasonPasses` | `OwnedSeasonPasses: IReadOnlyList\u003Cstring>` | |\n| `rentals` | `Rentals: IReadOnlyDictionary\u003Cstring, long>` | key=`internal_product_id`, value=`expiresAtServerUtcMs` |\n| `currencyBalances` | `CurrencyBalances: IReadOnlyDictionary\u003Cstring, long>` | key=재화ID, value=잔고 |\n| `serverNowUtcMs` | `ServerNowUtcMs: long` | Rental 남은시간 계산 기준 |\n\n#### 3) getRecentPurchases30d (Callable)\n\n- 목적: \"최근 30일 이내\" 구매 내역 조회 (kind 파라미터로 필터)\n- 기준 시각: `storePurchasedAt`(영수증 날짜)\n- 30일 기준: 서버 now − 30일 (클라\u002F기기 시간 금지)\n- 최신(latest): `storePurchasedAt` desc, 동률이면 docId desc\n- 인증: `context.auth.uid` 필수\n- 입력: `kind` (string, 필수 — PurchaseKind 값. `Consumable`\u002F`Rental` 등), `pageSize` (optional, 기본 20)\n- 출력:\n  - `items: array` — 각 원소: `{ purchaseId, internal_product_id, storePurchasedAt, verifyStatus, status }`\n    - `status`는 legacy response compatibility alias (temporary)\n  - `nextCursor: string | null` — 형식: `\"storePurchasedAtMs|docId\"` (페이지네이션 토큰)\n\n#### PurchaseManager 정식 API\n\n- `GetLatestConsumablePurchase30dAsync()`\n  - 서버 Callable: `getRecentPurchases30d` (`kind=\"Consumable\"`, `pageSize=1`로 호출, `items[0]`만 사용)\n  - 최근 30일 내 해당 kind 내역이 없으면 실패(`GAME_ERROR_TYPE.PURCHASE_*` + 메시지)로 처리\n  - 페이지네이션 없이 최신 1건만 반환하는 단일 API\n\n\n### Client-Side Purchase Flow (정본)\n\n#### ConfirmPurchase 타이밍 정책\n\n- `verifyPurchase` 응답의 `resultStatus`에 따라:\n  - `GRANTED`\n    - `controller.ConfirmPurchase(pendingOrder)` → `ackPurchaseStoreConfirm` **먼저 실행** (스토어 잠김 방지 우선)\n    - 이후 로컬 지급 → `ackPurchaseClientGrant(APPLIED_ACKED)` 수행\n    - `PurchaseStorage.current`는 `Confirm + storeConfirm ACK + clientGrant report` 종결 후 clear\n    - 로컬 지급 실패 → `ackPurchaseClientGrant(FAILED_REPORTED)` 보고 가능, 단 `storeConfirmStatus != CONFIRMED`이면 clear 금지\n  - `ALREADY_GRANTED`\n    - `storeConfirmStatus == PENDING`이고 로컬에서 이미 Confirm 완료(`storeConfirmedLocal`) 상태면 `ackPurchaseStoreConfirm` 복구 먼저 수행\n    - `clientGrantStatus == APPLIED_ACKED` → 중복 지급 없이 Confirm\u002FACK 복구만 진행\n    - `clientGrantStatus == PENDING` 또는 `FAILED_REPORTED` → 로컬 지급 복구 재시도 허용 → APPLIED_ACKED 보고\n    - `PurchaseStorage.current`는 복구 단계가 모두 종결될 때만 clear\n  - `REJECTED` → Confirm **하지 않음** (Unity가 자동 환불 처리)\n  - `PENDING` → Confirm **하지 않음** (스토어 확정 대기)\n- Confirm을 호출하지 않으면 Unity IAP가 다음 앱 실행 시 `OnPurchasePending`을 재전달한다.\n\n#### Client-side local snapshot (PurchaseStorage)\n\n- 클라이언트는 `PurchaseManager`가 소유하는 `PurchaseStorage`에 **최소 상태 스냅샷**만 기록할 수 있다.\n- 목적: 구매 진행 중 상태(current)의 local\u002Fcloud 저장 (복구 보조) + 환불\u002F지원 대응용 최소 로그(refundSupportLogs)\n- `current`는 복구 워크아이템이며, `Confirm + storeConfirm ACK + clientGrant report`가 종결되기 전에는 clear하지 않는다.\n- 금지: 전체 구매 이력 정본 저장, 구매 실패 상세(코드\u002F메시지) 저장, raw receipt 저장, 서버 원장\u002F멱등 대체\n- Rental 만료 시각(`expiresAtClientUtcMs`) \u002F SeasonPass 소유권은 **InventoryStorage**에서 관리한다 (PurchaseStorage 범위 아님).\n  - InventoryStorage: `Rentals` (rentalTypeId → expiresAtClientUtcMs), `SeasonPasses` (seasonPassTypeId → owned)\n  - Reward 파이프라인(`REWARD_TYPE.RENTAL` \u002F `REWARD_TYPE.PASS`)을 통해 설정하고, 만료 시각은 서버 데이터 Sync에서 갱신한다.\n- `RetryInterruptedPurchaseAsync()`는 \"재구매\"가 아니라 `PurchaseStorage.current` + 서버 상태를 바탕으로 **중단된 상태 전이를 재개**하는 경로다.\n- 정본 문서: `33-purchase-storage`\n\n#### Reward 적용(클라) 규칙\n\n- `GRANTED`이면 컨텐츠 레이어 매핑(`internal_product_id -> reward_group_id`) 후 RewardManager의 `ApplyRewardGroup(reward_group_id)`를 호출한다. (`AppliedRewards` 수집 가능)\n- `ALREADY_GRANTED`는 기본적으로 재지급 금지이나, `clientGrantStatus == PENDING` 또는 `FAILED_REPORTED`인 경우에는 로컬 지급 복구 경로를 허용한다.\n- `grants[]`는 응답 스키마에 존재할 수 있으나, **클라 지급 입력으로 사용하지 않는다**(지급 호출은 reward_group_id 기반).\n- RewardManager는 지급 실행만 담당하며, 멱등\u002F기록\u002F복구는 PurchaseManager(+서버)가 책임진다.\n\n연관:\n- [49-reward-system\u002F01-policy](..\u002F..\u002F49-reward-system\u002F01-policy\u002FSKILL.md)\n- [49-reward-system\u002F03-ssot](..\u002F..\u002F49-reward-system\u002F03-ssot\u002FSKILL.md)\n\n#### Pending \u002F Deferred 처리 규칙 (v5)\n\n- v5 `OnPurchasePending`은 **정상 구매와 deferred\u002Fpending을 모두 포함**한다.\n- 클라이언트 처리 흐름:\n  1) `OnPurchasePending` 수신 → 무조건 서버 `verifyPurchase` 호출\n  2) 서버가 스토어 검증 시 pending\u002Fdeferred 상태 감지 → `PENDING` 반환\n  3) 클라: `PENDING` 수신 → Confirm 하지 않음, 지급 하지 않음\n  4) 스토어 확정 후 다음 앱 실행 시 `OnPurchasePending` 재전달 → 1)부터 재시도\n- **PENDING 상태에서는 절대 지급\u002FConfirm 금지**\n\n\n### Firestore SSOT Schema (Canonical)\n\n> 결제 운영(조회\u002F감사\u002F복구)을 위해 \"구매 상세 조회\"가 가능한 최소 필드를 유지한다.\n\n#### `\u002Fusers\u002F{uid}\u002Fpurchases\u002F{purchaseId}`\n\n- `purchaseId` 권장 규칙: `{storeKey}_{storePurchaseId}`\n  - `storePurchaseId`는 Apple transaction id \u002F Google orderId 또는 purchaseToken 기반 식별자 등 \"스토어에서 유일한 값\"\n- 최소 필드\n  - `storeKey: string`\n  - `storePurchaseId: string`\n  - `internal_product_id: string`\n  - `kind: string`\n  - `verifyStatus: string`  \u002F\u002F \"GRANTED\" | \"REJECTED\" | \"PENDING\" | \"REVOKED\" | \"REFUNDED\"\n  - `clientGrantStatus: string` \u002F\u002F \"PENDING\" | \"APPLIED_ACKED\" | \"FAILED_REPORTED\"\n  - `storeConfirmStatus: string` \u002F\u002F \"PENDING\" | \"CONFIRMED\"\n  - `status: string`  \u002F\u002F legacy compatibility field (temporary)\n  - `lastStatusChangeAt: timestamp` \u002F\u002F server timestamp (상태 변경 시각)\n  - `statusReason: string`          \u002F\u002F \"refund\" | \"refund_reversed\" | \"chargeback\" | \"manual\" 등\n  - `payloadHash: string` \u002F\u002F 원문 저장 대신 해시 권장\n  - `environment: string` \u002F\u002F \"sandbox\" | \"production\" (가능하면 기록)\n  - `storePurchasedAt: timestamp` \u002F\u002F 스토어(영수증\u002F서버 검증 응답)에서 추출한 \"구매 시각\" — 클라이언트\u002F디바이스 시간 사용 금지(서버에서만 생성)\n  - `createdAt: timestamp` (server timestamp)\n  - `updatedAt: timestamp` (server timestamp)\n  - `raw: map` (optional; 민감정보 제외한 최소 subset)\n\n#### `\u002Fusers\u002F{uid}\u002Fentitlements\u002Fcurrent`\n\n- 최소 필드(프로젝트 확장 가능)\n  - `updatedAt: timestamp` (server timestamp)\n  - (예시) `ownedSeasonPasses: array\u003Cstring>`\n  - (예시) `rentals: map\u003Cstring, number>` \u002F\u002F `internal_product_id -> expiresAtServerUtcMs`\n  - (예시) `currencyBalances: map\u003Cstring, number>`\n\n### SeasonPass \u002F Rental Restore Projection (design fixed, server-side)\n\n- `SeasonPass`\u002F`Rental` 복원 정본은 서버 Firestore projection(`\u002Fusers\u002F{uid}\u002Fentitlements\u002Fcurrent`)을 사용한다.\n- `SyncEntitlementsAsync()`는 `getEntitlements`를 호출해 `InventoryStorage.Passes\u002FRentals`를 서버 값으로 덮어쓴 뒤 snapshot을 반환한다.\n- `RestoreAsync()`(스토어 복원)는 스토어 복원 트리거 후 동일한 entitlements 복원 규칙을 적용한다.\n- `SeasonPass` 복원은 시즌 유효 구간(`TB_SEASON.start \u003C= now \u003C end`)일 때만 반영한다.\n- Rental\u002FSeasonPass 조회: `GetRentalRemainingMsAsync`는 로컬 저장값 기준 남은 시간(ms)을 조회한다.\n- `Rental` 재구매 만료일 계산 정책(클라이언트):\n  - `newExpiry = max(existingExpiry, now) + 30일` (연장 방식)\n- Rental 복원 정책(클라이언트):\n  - `expiresAtServerUtcMs > serverNowUtcMs`만 반영\n  - 누적 연장을 허용하므로 복원 시 상한(30일 cap)을 두지 않는다.\n\n\n### Idempotency (멱등) 규칙\n\n- 멱등 키는 `purchaseId`(권장: `{storeKey}_{storePurchaseId}`)를 사용한다.\n- `verifyPurchase`는 같은 `purchaseId`로 여러 번 호출되어도:\n  - purchases 문서는 upsert로 유지\n  - entitlements는 \"원장 기반 재계산\" 또는 트랜잭션으로 갱신\n  - **중복 지급이 발생하지 않아야 한다**\n\n\n### Write \u002F Read Policy\n\n- Firestore write는 **서버(Functions\u002FAdmin SDK)** 만 수행한다.\n- 클라이언트는 verify + `getEntitlements` 동기화 + SaveData(local\u002Fcloud) 저장\u002F복원으로 상태를 갱신\u002F조회한다.\n- (정책 선택) 클라이언트 Firestore direct read를 허용한다면:\n  - `\u002Fusers\u002F{uid}\u002Fentitlements\u002Fcurrent`만 제한적으로 허용을 권장\n  - purchases 원장 direct read는 기본 비권장\n- Refund visibility (minimum)\n  - 환불 발생 시: `verifyStatus=\"REFUNDED\"`, `statusReason=\"refund\"`, `lastStatusChangeAt=serverTimestamp`\n  - 환불 취소(철회) 시: `verifyStatus`를 정상 상태로 되돌리고, `statusReason=\"refund_reversed\"`, `lastStatusChangeAt=serverTimestamp`\n  - 이 2개 필드로 \"환불\u002F환불취소가 실제로 있었는지\"를 `purchaseId` 단건 조회에서 확인 가능하다.\n\n### Privacy (Raw 데이터)\n\n- receipt\u002Fpayload 원문 저장은 피한다.\n- `payloadHash` 저장을 기본으로 하고,\n  raw 저장이 필요하면 \"민감정보 제외 + 최소 subset\"만 저장한다.\n\n### End-to-End Flow\n\n1) 클라: Unity IAP로 구매 진행\n2) 클라: 영수증\u002Freceipt 확보 후 서버 `verifyPurchase` 호출\n3) 서버: 스토어 검증(Apple\u002FGoogle) 수행\n4) 서버: Firestore에 purchases 기록 저장 + entitlements\u002Fcurrent 갱신 (필수)\n5) 클라: 서버 verify 성공 응답 수신 후에만 ConfirmPendingPurchase \u002F 지급 처리\n6) 클라: `SyncEntitlementsAsync`로 entitlements\u002Fcurrent를 반영해 `mPasses\u002FmRentals`를 복원\n7) 클라: 반영된 상태를 SaveData(local\u002Fcloud) payload에 저장\u002F복원\n\n### Security Rules (High-level)\n\n- purchases 컬렉션은 클라이언트 write 금지.\n- entitlements\u002Fcurrent는 (정책에 따라) 클라 read 허용 가능, write 금지.\n- UID 스코프는 반드시 `request.auth.uid == uid`로 제한.\n\n### NEEDS CHECK (code alignment)\n\n- 현재 저장소 코드가 실제로 어떤 Firestore 경로\u002F필드를 사용 중인지 별도 점검 필요.\n  (본 작업은 문서-only이며 코드 변경 금지)\n\n\n---\n\n\n## D. Subscription NoAds (from 07-ssot-subscription-noads)\n\n\n### SSOT 원칙\n\n- NoAds는 \"구독 Active 상태\"로만 판정한다.\n- 클라이언트 Unity IAP 콜백만으로 NoAds를 영구 적용하지 않는다.\n- 최종 상태는 verifyPurchase + `SyncEntitlementsAsync`(server restore) + SaveData(local\u002Fcloud) 저장\u002F복원으로 확정한다.\n\n\n### 상태 갱신\n\n#### iOS\n\n- 서버 알림(Apple Server Notifications)을 수신하여 구독 상태를 갱신하는 구성을 권장한다.\n- 알림 기반 갱신이 불가할 경우, scheduled recheck로 보조할 수 있다.\n\n#### Android\n\n- 운영 초기에는 scheduled recheck로 시작할 수 있다(선택).\n- 최종 목표는 서버에서 \"현재 유효 구독\"을 신뢰 가능한 방식으로 유지하는 것이다.\n\n\n### 클라이언트 적용 규칙\n\n- NoAds 상태의 정본은 서버 entitlements 기반으로 복원된 `InventoryStorage` Rental(`NO_ADS`) 값이다.\n- 동기화 방식: `PurchaseManager.SyncEntitlementsAsync(ct)`가 서버 `getEntitlements`를 호출해 Rental\u002FSeasonPass를 복원(덮어쓰기)한다.\n- NoAds는 광고 표시 로직의 단일 입력값으로 사용한다(여러 군데 중복 판정 금지).\n\n\n---\n\n\n## E. Season Pass (from 08-ssot-season-pass)\n\n\n### SSOT 원칙\n\n- 시즌 패스는 시즌별 구매 1회성 Entitlement로 운영한다.\n- 시즌별 Store SKU를 분리한다(시즌별 SKU 1개 원칙).\n  - 예: `season_pass_s2026_01`, `season_pass_s2026_02`\n- 소유 여부는 Firestore Entitlement 상태로 저장\u002F복구한다.\n- 시즌 패스 구매 결과는 Entitlement(`SeasonPass(season_id) owned`)로 저장한다.\n\n\n### 구매\u002F지급 규칙\n\n- `verifyPurchase` 결과가 `GRANTED`인 경우에만,\n  해당 시즌 `owned=true`로 반영한다.\n- 이미 소유(owned=true)인 시즌은 \"추가 구매\u002F중복 지급\"이 발생하지 않도록 처리한다.\n  - 중복 방지는 서버 멱등 원장과 Entitlement 상태가 최종 방어선이다.\n\n\n---\n\n\n## Legacy \u002F Deprecated Notes\n\n- 과거 문서에서 `purchaseRecords`, `userEntitlements`, `subscriptionState` 같은 루트 컬렉션 명칭이 등장할 수 있다.\n- SSOT는 본 문서의 `\u002Fusers\u002F{uid}\u002F...` 스키마를 기준으로 한다.\n","# 03-ssot — 30-purchase-system (통합 SSOT)\n\n\nStatus: ACTIVE\nAppliesTo: v10\n\n\n## 이 문서가 정본이다 (SSOT)\n\n이 문서는 30-purchase-system의 **단일 SSOT 허브**이다.\n기존 04~08 분할 문서의 핵심 내용이 이 문서에 통합되었다.\n운영\u002F보안\u002F테스트\u002FDoD는 [09-ssot-operations](..\u002F09-ssot-operations\u002FSKILL.md)를 참조한다.\n\n## 관심사별 라우팅 (중복 금지)\n\n- 운영\u002F보안\u002F테스트\u002FDoD 체크리스트: `..\u002F09-ssot-operations\u002FSKILL.md`\n- PurchaseStorage(로컬\u002F클라우드 저장용 최소 상태 스냅샷): `..\u002F33-purchase-storage\u002FSKILL.md`\n- Firebase Functions + Firestore 구현 상세: `..\u002F40-purchase-backend-firebase\u002FSKILL.md`\n- Firebase 레포 구성\u002FCLI\u002F배포 셋업: `..\u002F11-purchase-repo-firebase-functions-setup\u002FSKILL.md`\n- 고정 결정사항(Callable 이름\u002F경로\u002F시크릿\u002F정책 결정): `..\u002F46-purchase-decisions\u002FSKILL.md`\n\n이 문서(03)는 통합 SSOT 허브\u002F핵심 합의에 집중하고, 구현\u002F운영 상세의 원문은 위 문서로 분리한다.\n\n\n## 우선순위\n\n- Root SSOT: `skills\u002Fdevian\u002F10-module\u002F03-ssot\u002FSKILL.md`\n- Unity 관련 SSOT: `skills\u002Fdevian-unity\u002F03-ssot\u002FSKILL.md`\n- 결제\u002FIAP 관련 SSOT: 이 문서\n\n충돌 시 Root SSOT의 정의\u002F플레이스홀더\u002F규약이 우선한다.\n\n\n---\n\n\n## A. Unity IAP (from 04-ssot-unity-iap)\n\n\n### 전제\n\n- 결제 SDK는 Unity **In-App Purchasing (Unity IAP) 5.1.2** (`com.unity.purchasing@5.1.2`)를 사용한다.\n- 스토어별 구현 차이는 존재하지만, 최종 지급\u002F상태는 서버 검증 결과를 따른다.\n\n\n### Unity IAP 5.x v5 API 정책\n\n- 현재 구현은 **v5 신규 API** (`StoreController` + `UnityIAPServices` + 이벤트 기반)를 사용한다.\n- `[Obsolete]` Legacy API (`IDetailedStoreListener`, `UnityPurchasing.Initialize`, `ConfigurationBuilder`, `IStoreController`, `Product.receipt`)는 **사용하지 않는다**.\n\n#### v5 API 사용 패턴\n\n| 기능 | v5 API |\n|------|--------|\n| 초기화 | `UnityIAPServices.StoreController()` → `await controller.Connect()` → `controller.FetchProducts(definitions)` |\n| 제품 등록 | `List\u003CProductDefinition>` + `controller.FetchProducts(...)` (ProductCatalog에서 변환) |\n| 구매 시작 | `controller.PurchaseProduct(productId)` |\n| 구매 확인 | `controller.ConfirmPurchase(pendingOrder)` |\n| Receipt 접근 | `PendingOrder.Info.Receipt` |\n| Restore | `controller.RestoreTransactions(Action\u003Cbool, string?>)` (플랫폼 분기 불필요) |\n| 구매 성공 콜백 | `controller.OnPurchasePending` (PendingOrder) |\n| 구매 실패 콜백 | `controller.OnPurchaseFailed` (FailedOrder) |\n| 제품 Fetch 콜백 | `controller.OnProductsFetched` \u002F `OnProductsFetchFailed` |\n\n#### 참고: 4.x → 5.x 주요 변경 사항\n\n| 항목 | 변경 |\n|------|------|\n| Amazon\u002FUWP\u002FFacebook 스토어 | **제거됨** |\n| Apple Receipt Validation | **Deprecated** (Google Play만 지원) |\n| `IAppleExtensions.RestoreTransactions` | `Action\u003Cbool>` → `Action\u003Cbool, string>` |\n\n\n### 플랫폼 차이\n\n#### iOS: Restore(복원)\n\n- iOS는 재설치\u002F기기 변경 시 Restore 플로우가 필요하다.\n- Restore는 \"스토어 구매 이력 재동기화 트리거\"이며,\n  최종 Entitlement는 서버 상태(purchases\u002Fentitlements)를 기준으로 확정한다.\n\n#### Android: 복원 UX\n\n- Android는 보통 Restore 버튼을 직접 노출하지 않고,\n  앱 시작\u002F로그인 시 서버 상태 동기화로 복원을 처리해도 된다.\n\n\n### Pending \u002F Deferred 상태\n\n- iOS: 승인 대기(deferred) 상태가 발생할 수 있다.\n- Android: pending 상태가 발생할 수 있다.\n- 공통 규칙: **PENDING\u002FDEFERRED 상태에서는 지급 금지** (서버 검증 확정 전 지급 금지)\n\n\n---\n\n\n## B. Product Catalog (from 05-ssot-product-catalog)\n\n\n### SSOT 원칙\n\n#### 1) 내부 표준 ID가 정본\n\n- 상위 로직은 `internal_product_id`를 정본으로 사용한다.\n- Store SKU는 매핑 데이터로만 취급한다.\n\n#### 2) 타입 규칙\n\n- Consumable: 재화 등 반복 구매\u002F즉시 지급\n- Rental: 기간제 구매(예: NoAds 30일). 반복 구매 허용, 만료일 연장 방식\n- Subscription: \"구독 기반 NoAds\" 등 상태 기반\n- Season Pass: 시즌별 구매 1회성 Entitlement로 운영\n\n- kind의 정본 enum은 컨텐츠 레이어가 정의한 `PurchaseKind`다.\n- 테이블(`ShopTable.xlsx` PURCHASE.kind)의 타입은 `PurchaseKind`를 사용한다.\n\n### 카탈로그 통합\n\nPurchaseManager는 `TB_PURCHASE` 테이블을 **직접 참조**하여 카탈로그를 구성한다.\n`Devian.Samples.MobilePackage.asmdef`에 `Devian.Domain.Game` 참조가 포함되어 있다.\n\nPurchase 지급을 위해 `internal_product_id -> reward_group_id` 변환이 필요하다.\n- `PurchaseManager`가 `ResolveRewardGroupId(internal_product_id)` → `TB_PURCHASE.Get(internal_product_id).Reward_group_id`로 직접 변환한다.\n- `BuildProductDefinitions()` → `TB_PURCHASE.GetAll()`에서 `is_active` 필터링 후 ProductDefinition 목록을 생성한다.\n\n### Unity IAP 5.x (v5) Catalog Notes\n\n- 본 SSOT에서 \"카탈로그\"는 **내부 ID(`internal_product_id`) ↔ 스토어 SKU(Apple\u002FGoogle) 매핑 데이터**를 의미한다.\n- Unity IAP 5.x(v5)에서는 과거 방식의 `ProductCatalog.LoadDefaultCatalog()` 같은 런타임 로딩 API에 의존하지 않는다. (obsolete 전제 제거)\n- 런타임에서는 \"등록된 제품 정의\"를 사용해 구매를 시작하며, 상위 로직은 반드시 `internal_product_id`만 사용한다.\n- 스토어 SKU는 플랫폼별 매핑 데이터일 뿐이며, 운영\u002F코드에서 직접 참조하지 않는다.\n\n### NEEDS CHECK (형준 결정 필요)\n\n#### Product Catalog (상품 요약\u002F매핑) SSOT — ✅ 전체 결정됨\n- [x] SSOT 저장 위치: **(A) Devian input 테이블(Excel) 기반** — 결정됨\n  - PURCHASE 테이블 스키마를 이 문서(03-ssot)에서 SSOT로 정의한다.\n  - `ShopTable.xlsx`의 PURCHASE 시트에서 데이터를 관리한다.\n- [x] `{buildInputJson}` 도메인 등록: — 결정됨\n  - 도메인 등록 정보는 컨텐츠 레이어 SSOT에서 관리\n- [x] ShopTable.xlsx 경로: — 결정됨\n  - 경로는 컨텐츠 레이어 SSOT에서 관리\n- [x] PURCHASE 테이블 스키마\u002F필드: — 결정됨\n  - `internal_product_id` (string, pk) — 내부 상품 ID (정본)\n  - `reward_group_id` (string) — 지급 Reward Key, `internal_product_id -> reward_group_id` 변환의 SSOT\n  - `kind` (PurchaseKind) — 상품 타입 (`Consumable` \u002F `Rental` \u002F `Subscription` \u002F `SeasonPass`)\n  - `is_active` (bool) — 운영 활성 토글\n  - `store_sku_apple` (string) — Apple Store SKU\n  - `store_sku_google` (string) — Google Play SKU\n- [x] 시즌 매핑 필드 위치: — 결정됨\n  - 시즌 구매 제한용 `season_id`는 `SHOP_ITEM_PURCHASE.season_id`에서 관리한다. (`PURCHASE` 스키마에는 포함하지 않는다.)\n\n\n---\n\n\n## C. Verification Server + Idempotency + Firestore Ledger (from 06-ssot-verify-idempotency)\n\n\n### SSOT (핵심 합의)\n\n- 별도 VM 서버 없이 **Firebase Cloud Functions**를 \"검증 서버\"로 사용한다.\n- 결제\u002F구매 정보는 **Firestore Cloud에 저장**한다. (원장\u002Fentitlements)\n- 클라이언트는 결제 원장에 직접 write 하지 않는다. (서버 write only)\n- 멱등 처리(Idempotency)로 중복 verify\u002F중복 지급을 방지한다.\n\n구현 상세(함수 구조\u002F스키마\u002F인덱스)는 `40`, 레포\u002F배포 셋업은 `44`, 최종 고정 결정값은 `46`을 참조한다.\n\n\n### resultStatus (정본 enum)\n\n클라이언트·서버 모두 아래 값만 사용한다. (문자열 비교, 대문자)\n\n| 값 | 의미 |\n|----|------|\n| `GRANTED` | 신규 검증 성공 — 지급 실행 |\n| `ALREADY_GRANTED` | 동일 구매 재요청 — 이미 지급됨(멱등) |\n| `REJECTED` | 스토어 검증 실패 \u002F 위변조 |\n| `PENDING` | 스토어가 아직 확정하지 않은 상태 (deferred\u002Fpending) — 지급 금지 |\n| `REVOKED` | 환불\u002F취소 등으로 사후 철회 |\n| `REFUNDED` | 스토어 환불 확인 |\n\n- Firestore purchase 문서의 정본 상태 필드는 `verifyStatus`다. (`resultStatus`와 같은 의미의 서버 상태)\n- `clientGrantStatus`는 클라이언트 로컬 지급 결과 보고 상태를 별도로 저장한다. (`PENDING` \u002F `APPLIED_ACKED` \u002F `FAILED_REPORTED`)\n- `storeConfirmStatus`는 스토어 `ConfirmPurchase` 처리 상태를 별도로 저장한다. (`PENDING` \u002F `CONFIRMED`)\n- 01-policy의 기존 표기(`GRANTED|ALREADY_GRANTED|REJECTED|PENDING`)와 정합.\n\n\n### 엔드포인트(최소 세트)\n\n#### 1) verifyPurchase (Callable 권장)\n\n- 입력\n  - `uid` — Auth context에서 확보 (클라가 보내지 않음)\n  - `storeKey: string` — \"apple\" | \"google\"\n  - `internal_product_id: string`\n  - `kind: string` — \"Consumable\" | \"Rental\" | \"Subscription\" | \"SeasonPass\" (=`PurchaseKind` string)\n  - `payload: string` — 스토어 영수증\u002F검증 데이터 (클라에서 `BuildVerifyPayload(receipt)` 결과)\n- 처리\n  1) 스토어 서버 검증(Apple\u002FGoogle)\n  2) Firestore 원장 기록 upsert (멱등)\n  3) 결과 반환 (entitlements 갱신은 별도 `getEntitlements` 호출로 분리)\n- 출력\n  - `resultStatus: string` — 위 enum 중 하나\n  - `purchaseId: string` — `{storeKey}_{storePurchaseId}`\n  - `verifyStatus: string` — 서버 purchase 상태 필드(`verifyStatus`)와 정합\n  - `clientGrantStatus: string` — `\"PENDING\" | \"APPLIED_ACKED\" | \"FAILED_REPORTED\"`\n  - `storeConfirmStatus: string` — `\"PENDING\" | \"CONFIRMED\"`\n  - `grants: array` — (server informational, 클라 지급 입력으로 미사용) 지급 내역 참고용. 보상은 `reward_group_id` 경로로 지급\n  - `entitlementsSnapshot: object?` — (optional) 갱신된 entitlements 스냅샷. GRANTED\u002FALREADY_GRANTED 시 포함. 클라는 `ParseEntitlementsSnapshot`으로 파싱 + `cacheEntitlementsSnapshot`으로 InventoryStorage에 동기화\n\n##### C# ↔ Callable 필드 매핑\n\n| C# (`VerifyPurchaseRequest`) | Callable JSON key | 비고 |\n|------------------------------|-------------------|------|\n| `Internal_product_id` | `internal_product_id` | |\n| `Kind` (enum → string) | `kind` | `\"Consumable\"` \u002F `\"Rental\"` \u002F `\"Subscription\"` \u002F `\"SeasonPass\"` |\n| `Store` | `storeKey` | |\n| `Payload` | `payload` | |\n\n| Callable JSON response | C# (`VerifyPurchaseResponse`) | 비고 |\n|------------------------|-------------------------------|------|\n| `resultStatus` | `ResultStatus` | 위 enum 값 |\n| `purchaseId` | `PurchaseId` | verify 멱등키 |\n| `verifyStatus` | `VerifyStatus` | Firestore purchase 상태 필드와 정합 |\n| `clientGrantStatus` | `ClientGrantStatus` | 로컬 지급 결과 보고 상태 |\n| `storeConfirmStatus` | `StoreConfirmStatus` | 스토어 Confirm 처리 상태 |\n| `grants[]` | (클라이언트 미사용 — 무시) | 서버 informational. 보상은 `reward_group_id` 경로로 지급 |\n| `entitlementsSnapshot` | `Snapshot` (`EntitlementsSnapshot?`) | optional |\n\n#### 1-1) ackPurchaseClientGrant (Callable)\n\n- 입력\n  - `uid` — Auth context에서 확보 (클라가 보내지 않음)\n  - `purchaseId: string`\n  - `clientGrantStatus: string` — `\"APPLIED_ACKED\"` | `\"FAILED_REPORTED\"`\n- 처리\n  1) purchase 문서 소유자\u002F상태 확인 (`verifyStatus == GRANTED`)\n  2) `clientGrantStatus = APPLIED_ACKED | FAILED_REPORTED` 멱등 업데이트\n- 출력\n  - `purchaseId`\n  - `verifyStatus`\n  - `clientGrantStatus`\n\n#### 1-2) ackPurchaseStoreConfirm (Callable)\n\n- 입력\n  - `uid` — Auth context에서 확보 (클라가 보내지 않음)\n  - `purchaseId: string`\n- 처리\n  1) purchase 문서 소유자\u002F상태 확인 (`verifyStatus == GRANTED`)\n  2) `storeConfirmStatus = CONFIRMED` 멱등 업데이트\n- 출력\n  - `purchaseId`\n  - `verifyStatus`\n  - `clientGrantStatus`\n  - `storeConfirmStatus`\n\n#### 2) getEntitlements (Callable\u002FHTTPS 중 택1)\n\n- 입력: `uid` (Auth context)\n- 출력:\n\n| Callable JSON response | C# (`EntitlementsSnapshot`) | 비고 |\n|------------------------|------------------------------|------|\n| `ownedSeasonPasses` | `OwnedSeasonPasses: IReadOnlyList\u003Cstring>` | |\n| `rentals` | `Rentals: IReadOnlyDictionary\u003Cstring, long>` | key=`internal_product_id`, value=`expiresAtServerUtcMs` |\n| `currencyBalances` | `CurrencyBalances: IReadOnlyDictionary\u003Cstring, long>` | key=재화ID, value=잔고 |\n| `serverNowUtcMs` | `ServerNowUtcMs: long` | Rental 남은시간 계산 기준 |\n\n#### 3) getRecentPurchases30d (Callable)\n\n- 목적: \"최근 30일 이내\" 구매 내역 조회 (kind 파라미터로 필터)\n- 기준 시각: `storePurchasedAt`(영수증 날짜)\n- 30일 기준: 서버 now − 30일 (클라\u002F기기 시간 금지)\n- 최신(latest): `storePurchasedAt` desc, 동률이면 docId desc\n- 인증: `context.auth.uid` 필수\n- 입력: `kind` (string, 필수 — PurchaseKind 값. `Consumable`\u002F`Rental` 등), `pageSize` (optional, 기본 20)\n- 출력:\n  - `items: array` — 각 원소: `{ purchaseId, internal_product_id, storePurchasedAt, verifyStatus, status }`\n    - `status`는 legacy response compatibility alias (temporary)\n  - `nextCursor: string | null` — 형식: `\"storePurchasedAtMs|docId\"` (페이지네이션 토큰)\n\n#### PurchaseManager 정식 API\n\n- `GetLatestConsumablePurchase30dAsync()`\n  - 서버 Callable: `getRecentPurchases30d` (`kind=\"Consumable\"`, `pageSize=1`로 호출, `items[0]`만 사용)\n  - 최근 30일 내 해당 kind 내역이 없으면 실패(`GAME_ERROR_TYPE.PURCHASE_*` + 메시지)로 처리\n  - 페이지네이션 없이 최신 1건만 반환하는 단일 API\n\n\n### Client-Side Purchase Flow (정본)\n\n#### ConfirmPurchase 타이밍 정책\n\n- `verifyPurchase` 응답의 `resultStatus`에 따라:\n  - `GRANTED`\n    - `controller.ConfirmPurchase(pendingOrder)` → `ackPurchaseStoreConfirm` **먼저 실행** (스토어 잠김 방지 우선)\n    - 이후 로컬 지급 → `ackPurchaseClientGrant(APPLIED_ACKED)` 수행\n    - `PurchaseStorage.current`는 `Confirm + storeConfirm ACK + clientGrant report` 종결 후 clear\n    - 로컬 지급 실패 → `ackPurchaseClientGrant(FAILED_REPORTED)` 보고 가능, 단 `storeConfirmStatus != CONFIRMED`이면 clear 금지\n  - `ALREADY_GRANTED`\n    - `storeConfirmStatus == PENDING`이고 로컬에서 이미 Confirm 완료(`storeConfirmedLocal`) 상태면 `ackPurchaseStoreConfirm` 복구 먼저 수행\n    - `clientGrantStatus == APPLIED_ACKED` → 중복 지급 없이 Confirm\u002FACK 복구만 진행\n    - `clientGrantStatus == PENDING` 또는 `FAILED_REPORTED` → 로컬 지급 복구 재시도 허용 → APPLIED_ACKED 보고\n    - `PurchaseStorage.current`는 복구 단계가 모두 종결될 때만 clear\n  - `REJECTED` → Confirm **하지 않음** (Unity가 자동 환불 처리)\n  - `PENDING` → Confirm **하지 않음** (스토어 확정 대기)\n- Confirm을 호출하지 않으면 Unity IAP가 다음 앱 실행 시 `OnPurchasePending`을 재전달한다.\n\n#### Client-side local snapshot (PurchaseStorage)\n\n- 클라이언트는 `PurchaseManager`가 소유하는 `PurchaseStorage`에 **최소 상태 스냅샷**만 기록할 수 있다.\n- 목적: 구매 진행 중 상태(current)의 local\u002Fcloud 저장 (복구 보조) + 환불\u002F지원 대응용 최소 로그(refundSupportLogs)\n- `current`는 복구 워크아이템이며, `Confirm + storeConfirm ACK + clientGrant report`가 종결되기 전에는 clear하지 않는다.\n- 금지: 전체 구매 이력 정본 저장, 구매 실패 상세(코드\u002F메시지) 저장, raw receipt 저장, 서버 원장\u002F멱등 대체\n- Rental 만료 시각(`expiresAtClientUtcMs`) \u002F SeasonPass 소유권은 **InventoryStorage**에서 관리한다 (PurchaseStorage 범위 아님).\n  - InventoryStorage: `Rentals` (rentalTypeId → expiresAtClientUtcMs), `SeasonPasses` (seasonPassTypeId → owned)\n  - Reward 파이프라인(`REWARD_TYPE.RENTAL` \u002F `REWARD_TYPE.PASS`)을 통해 설정하고, 만료 시각은 서버 데이터 Sync에서 갱신한다.\n- `RetryInterruptedPurchaseAsync()`는 \"재구매\"가 아니라 `PurchaseStorage.current` + 서버 상태를 바탕으로 **중단된 상태 전이를 재개**하는 경로다.\n- 정본 문서: `33-purchase-storage`\n\n#### Reward 적용(클라) 규칙\n\n- `GRANTED`이면 컨텐츠 레이어 매핑(`internal_product_id -> reward_group_id`) 후 RewardManager의 `ApplyRewardGroup(reward_group_id)`를 호출한다. (`AppliedRewards` 수집 가능)\n- `ALREADY_GRANTED`는 기본적으로 재지급 금지이나, `clientGrantStatus == PENDING` 또는 `FAILED_REPORTED`인 경우에는 로컬 지급 복구 경로를 허용한다.\n- `grants[]`는 응답 스키마에 존재할 수 있으나, **클라 지급 입력으로 사용하지 않는다**(지급 호출은 reward_group_id 기반).\n- RewardManager는 지급 실행만 담당하며, 멱등\u002F기록\u002F복구는 PurchaseManager(+서버)가 책임진다.\n\n연관:\n- [49-reward-system\u002F01-policy](..\u002F..\u002F49-reward-system\u002F01-policy\u002FSKILL.md)\n- [49-reward-system\u002F03-ssot](..\u002F..\u002F49-reward-system\u002F03-ssot\u002FSKILL.md)\n\n#### Pending \u002F Deferred 처리 규칙 (v5)\n\n- v5 `OnPurchasePending`은 **정상 구매와 deferred\u002Fpending을 모두 포함**한다.\n- 클라이언트 처리 흐름:\n  1) `OnPurchasePending` 수신 → 무조건 서버 `verifyPurchase` 호출\n  2) 서버가 스토어 검증 시 pending\u002Fdeferred 상태 감지 → `PENDING` 반환\n  3) 클라: `PENDING` 수신 → Confirm 하지 않음, 지급 하지 않음\n  4) 스토어 확정 후 다음 앱 실행 시 `OnPurchasePending` 재전달 → 1)부터 재시도\n- **PENDING 상태에서는 절대 지급\u002FConfirm 금지**\n\n\n### Firestore SSOT Schema (Canonical)\n\n> 결제 운영(조회\u002F감사\u002F복구)을 위해 \"구매 상세 조회\"가 가능한 최소 필드를 유지한다.\n\n#### `\u002Fusers\u002F{uid}\u002Fpurchases\u002F{purchaseId}`\n\n- `purchaseId` 권장 규칙: `{storeKey}_{storePurchaseId}`\n  - `storePurchaseId`는 Apple transaction id \u002F Google orderId 또는 purchaseToken 기반 식별자 등 \"스토어에서 유일한 값\"\n- 최소 필드\n  - `storeKey: string`\n  - `storePurchaseId: string`\n  - `internal_product_id: string`\n  - `kind: string`\n  - `verifyStatus: string`  \u002F\u002F \"GRANTED\" | \"REJECTED\" | \"PENDING\" | \"REVOKED\" | \"REFUNDED\"\n  - `clientGrantStatus: string` \u002F\u002F \"PENDING\" | \"APPLIED_ACKED\" | \"FAILED_REPORTED\"\n  - `storeConfirmStatus: string` \u002F\u002F \"PENDING\" | \"CONFIRMED\"\n  - `status: string`  \u002F\u002F legacy compatibility field (temporary)\n  - `lastStatusChangeAt: timestamp` \u002F\u002F server timestamp (상태 변경 시각)\n  - `statusReason: string`          \u002F\u002F \"refund\" | \"refund_reversed\" | \"chargeback\" | \"manual\" 등\n  - `payloadHash: string` \u002F\u002F 원문 저장 대신 해시 권장\n  - `environment: string` \u002F\u002F \"sandbox\" | \"production\" (가능하면 기록)\n  - `storePurchasedAt: timestamp` \u002F\u002F 스토어(영수증\u002F서버 검증 응답)에서 추출한 \"구매 시각\" — 클라이언트\u002F디바이스 시간 사용 금지(서버에서만 생성)\n  - `createdAt: timestamp` (server timestamp)\n  - `updatedAt: timestamp` (server timestamp)\n  - `raw: map` (optional; 민감정보 제외한 최소 subset)\n\n#### `\u002Fusers\u002F{uid}\u002Fentitlements\u002Fcurrent`\n\n- 최소 필드(프로젝트 확장 가능)\n  - `updatedAt: timestamp` (server timestamp)\n  - (예시) `ownedSeasonPasses: array\u003Cstring>`\n  - (예시) `rentals: map\u003Cstring, number>` \u002F\u002F `internal_product_id -> expiresAtServerUtcMs`\n  - (예시) `currencyBalances: map\u003Cstring, number>`\n\n### SeasonPass \u002F Rental Restore Projection (design fixed, server-side)\n\n- `SeasonPass`\u002F`Rental` 복원 정본은 서버 Firestore projection(`\u002Fusers\u002F{uid}\u002Fentitlements\u002Fcurrent`)을 사용한다.\n- `SyncEntitlementsAsync()`는 `getEntitlements`를 호출해 `InventoryStorage.Passes\u002FRentals`를 서버 값으로 덮어쓴 뒤 snapshot을 반환한다.\n- `RestoreAsync()`(스토어 복원)는 스토어 복원 트리거 후 동일한 entitlements 복원 규칙을 적용한다.\n- `SeasonPass` 복원은 시즌 유효 구간(`TB_SEASON.start \u003C= now \u003C end`)일 때만 반영한다.\n- Rental\u002FSeasonPass 조회: `GetRentalRemainingMsAsync`는 로컬 저장값 기준 남은 시간(ms)을 조회한다.\n- `Rental` 재구매 만료일 계산 정책(클라이언트):\n  - `newExpiry = max(existingExpiry, now) + 30일` (연장 방식)\n- Rental 복원 정책(클라이언트):\n  - `expiresAtServerUtcMs > serverNowUtcMs`만 반영\n  - 누적 연장을 허용하므로 복원 시 상한(30일 cap)을 두지 않는다.\n\n\n### Idempotency (멱등) 규칙\n\n- 멱등 키는 `purchaseId`(권장: `{storeKey}_{storePurchaseId}`)를 사용한다.\n- `verifyPurchase`는 같은 `purchaseId`로 여러 번 호출되어도:\n  - purchases 문서는 upsert로 유지\n  - entitlements는 \"원장 기반 재계산\" 또는 트랜잭션으로 갱신\n  - **중복 지급이 발생하지 않아야 한다**\n\n\n### Write \u002F Read Policy\n\n- Firestore write는 **서버(Functions\u002FAdmin SDK)** 만 수행한다.\n- 클라이언트는 verify + `getEntitlements` 동기화 + SaveData(local\u002Fcloud) 저장\u002F복원으로 상태를 갱신\u002F조회한다.\n- (정책 선택) 클라이언트 Firestore direct read를 허용한다면:\n  - `\u002Fusers\u002F{uid}\u002Fentitlements\u002Fcurrent`만 제한적으로 허용을 권장\n  - purchases 원장 direct read는 기본 비권장\n- Refund visibility (minimum)\n  - 환불 발생 시: `verifyStatus=\"REFUNDED\"`, `statusReason=\"refund\"`, `lastStatusChangeAt=serverTimestamp`\n  - 환불 취소(철회) 시: `verifyStatus`를 정상 상태로 되돌리고, `statusReason=\"refund_reversed\"`, `lastStatusChangeAt=serverTimestamp`\n  - 이 2개 필드로 \"환불\u002F환불취소가 실제로 있었는지\"를 `purchaseId` 단건 조회에서 확인 가능하다.\n\n### Privacy (Raw 데이터)\n\n- receipt\u002Fpayload 원문 저장은 피한다.\n- `payloadHash` 저장을 기본으로 하고,\n  raw 저장이 필요하면 \"민감정보 제외 + 최소 subset\"만 저장한다.\n\n### End-to-End Flow\n\n1) 클라: Unity IAP로 구매 진행\n2) 클라: 영수증\u002Freceipt 확보 후 서버 `verifyPurchase` 호출\n3) 서버: 스토어 검증(Apple\u002FGoogle) 수행\n4) 서버: Firestore에 purchases 기록 저장 + entitlements\u002Fcurrent 갱신 (필수)\n5) 클라: 서버 verify 성공 응답 수신 후에만 ConfirmPendingPurchase \u002F 지급 처리\n6) 클라: `SyncEntitlementsAsync`로 entitlements\u002Fcurrent를 반영해 `mPasses\u002FmRentals`를 복원\n7) 클라: 반영된 상태를 SaveData(local\u002Fcloud) payload에 저장\u002F복원\n\n### Security Rules (High-level)\n\n- purchases 컬렉션은 클라이언트 write 금지.\n- entitlements\u002Fcurrent는 (정책에 따라) 클라 read 허용 가능, write 금지.\n- UID 스코프는 반드시 `request.auth.uid == uid`로 제한.\n\n### NEEDS CHECK (code alignment)\n\n- 현재 저장소 코드가 실제로 어떤 Firestore 경로\u002F필드를 사용 중인지 별도 점검 필요.\n  (본 작업은 문서-only이며 코드 변경 금지)\n\n\n---\n\n\n## D. Subscription NoAds (from 07-ssot-subscription-noads)\n\n\n### SSOT 원칙\n\n- NoAds는 \"구독 Active 상태\"로만 판정한다.\n- 클라이언트 Unity IAP 콜백만으로 NoAds를 영구 적용하지 않는다.\n- 최종 상태는 verifyPurchase + `SyncEntitlementsAsync`(server restore) + SaveData(local\u002Fcloud) 저장\u002F복원으로 확정한다.\n\n\n### 상태 갱신\n\n#### iOS\n\n- 서버 알림(Apple Server Notifications)을 수신하여 구독 상태를 갱신하는 구성을 권장한다.\n- 알림 기반 갱신이 불가할 경우, scheduled recheck로 보조할 수 있다.\n\n#### Android\n\n- 운영 초기에는 scheduled recheck로 시작할 수 있다(선택).\n- 최종 목표는 서버에서 \"현재 유효 구독\"을 신뢰 가능한 방식으로 유지하는 것이다.\n\n\n### 클라이언트 적용 규칙\n\n- NoAds 상태의 정본은 서버 entitlements 기반으로 복원된 `InventoryStorage` Rental(`NO_ADS`) 값이다.\n- 동기화 방식: `PurchaseManager.SyncEntitlementsAsync(ct)`가 서버 `getEntitlements`를 호출해 Rental\u002FSeasonPass를 복원(덮어쓰기)한다.\n- NoAds는 광고 표시 로직의 단일 입력값으로 사용한다(여러 군데 중복 판정 금지).\n\n\n---\n\n\n## E. Season Pass (from 08-ssot-season-pass)\n\n\n### SSOT 원칙\n\n- 시즌 패스는 시즌별 구매 1회성 Entitlement로 운영한다.\n- 시즌별 Store SKU를 분리한다(시즌별 SKU 1개 원칙).\n  - 예: `season_pass_s2026_01`, `season_pass_s2026_02`\n- 소유 여부는 Firestore Entitlement 상태로 저장\u002F복구한다.\n- 시즌 패스 구매 결과는 Entitlement(`SeasonPass(season_id) owned`)로 저장한다.\n\n\n### 구매\u002F지급 규칙\n\n- `verifyPurchase` 결과가 `GRANTED`인 경우에만,\n  해당 시즌 `owned=true`로 반영한다.\n- 이미 소유(owned=true)인 시즌은 \"추가 구매\u002F중복 지급\"이 발생하지 않도록 처리한다.\n  - 중복 방지는 서버 멱등 원장과 Entitlement 상태가 최종 방어선이다.\n\n\n---\n\n\n## Legacy \u002F Deprecated Notes\n\n- 과거 문서에서 `purchaseRecords`, `userEntitlements`, `subscriptionState` 같은 루트 컬렉션 명칭이 등장할 수 있다.\n- SSOT는 본 문서의 `\u002Fusers\u002F{uid}\u002F...` 스키마를 기준으로 한다.\n",{"name":5,"description":7},"main","8cb5bd877a3a7004867d2f55697cb9e4ff2f1734","skills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F03-ssot","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian","https:\u002F\u002Fgithub.com\u002Fdevwinsoft","Kim Hyong Joon","2026-04-12 18:44:10",{"source":8,"skillName":5,"commands":46,"prompt":56,"zipAvailable":57},[47,50,53],{"tool":48,"command":49},"npx","npx skills add devwinsoft\u002Fdevian --skill 03-ssot",{"tool":51,"command":52},"bunx","bunx skills add devwinsoft\u002Fdevian --skill 03-ssot",{"tool":54,"command":55},"pnpm","pnpm dlx skills add devwinsoft\u002Fdevian --skill 03-ssot","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian-unity\u002F50-mobile-package\u002F30-purchase-system\u002F03-ssot\u002FSKILL.md",true,[],[60,66,74,82,91,98],{"skillNo":61,"name":62,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":33},"01M6CBX3K2JJV38ANHVGCAT8A0","devian","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002FSKILL.md",[],[62],{"skillNo":67,"name":68,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":33},"01M6CBX210BFMM8AMN770J9WY8","90-project-archive","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F90-project-archive\u002FSKILL.md",[],[72,73],"archive","90 project archive",{"skillNo":75,"name":76,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":33},"01M6CBWZSGRR9R3YJZB3177667","30-env-management","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F30-env-management\u002FSKILL.md",[],[80,81],"management","30 env management",{"skillNo":83,"name":84,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":33},"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",[],[88,89,90],"push","page","19 page push send",{"skillNo":92,"name":93,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":33},"01M6CBWWRQ05A7604GHJKTPJTF","18-page-savedata","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F20-operation\u002F18-page-savedata\u002FSKILL.md",[],[89,97],"18 page savedata",{"skillNo":99,"name":100,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":103,"publishedAt":33},"01M6CBWVH4S2VF1V7B2GBTESCT","17-page-deobfuscate","https:\u002F\u002Fgithub.com\u002Fdevwinsoft\u002Fdevian\u002Fblob\u002Fmain\u002Fskills\u002Fdevian\u002F80-tools\u002F20-operation\u002F17-page-deobfuscate\u002FSKILL.md",[],[89,104],"17 page deobfuscate"]