fix(payple-renew): reconcile renewals whose charge outcome was left unknown

server/supabase/functions/payple-renew/renewal.ts

@@ -0,0 +1,377 @@
+// server/supabase/functions/payple-renew/renewal.ts
+// Payple 정기 갱신 유스케이스 — 순수 정책 + 포트(RenewalStore, RenewalPaymentGateway).
+// IO(Supabase RPC, Payple HTTP)는 adapters.ts가 구현하고, 이 모듈은 결정만 내린다.
+
+import {
+  calcSubscriptionPeriod,
+  parsePaypleTimestamp,
+  PaypleBillingError,
+  PaypleVerificationError,
+  TIER_GOODS_NAME,
+  TIER_PRICE,
+} from '../_shared/payple.ts'
+
+export const MAX_RENEWAL_FAILURES = 3
+/** Payple 빌링 호출 상한. 멈춘 호출이 크론 전체 실행 시간을 잡아먹지 않게 한다. */
+export const BILLING_TIMEOUT_MS = 30_000
+/** Payple 결과조회(PayChkAct) 호출 상한. */
+export const LOOKUP_TIMEOUT_MS = 30_000
+
+// ── 도메인 타입 ─────────────────────────────────────────
+
+export type RenewableTier = 'pro' | 'pro_plus'
+
+export interface RenewalCandidate {
+  userId: string
+  tier: RenewableTier
+  payerId: string
+  resourceId: string
+  currentPeriodEnd: string
+  renewalFailures: number
+}
+
+export interface RenewalResult {
+  userId: string
+  tier: string
+  success: boolean
+  orderId?: string
+  error?: string
+}
+
+export type RenewalOperationState =
+  | 'reserved'
+  | 'external_created'
+  | 'charged'
+  | 'applied'
+  | 'failed'
+
+export interface RenewalOperation {
+  id: string
+  state: string
+  providerOrderId: string | null
+  expiresAt: string | null
+}
+
+export type RenewalReservation =
+  | { kind: 'created'; operationId: string }
+  | { kind: 'replay'; operationId: string }
+  | { kind: 'rejected'; reason: string }
+
+export interface RenewalPaymentApplication {
+  candidate: RenewalCandidate
+  orderId: string
+  operationId: string
+  eventTime: Date
+  periodStart: string
+  periodEnd: string
+}
+
+export interface ChargeRequest {
+  payerId: string
+  amount: number
+  orderId: string
+  goodsName: string
+}
+
+export interface ChargeReceipt {
+  orderId: string
+  total: string
+  payerId?: string
+  payTime?: string
+}
+
+export type LookupOutcome =
+  | { kind: 'charged'; payment: ChargeReceipt }
+  | { kind: 'not_charged' }
+  | { kind: 'unknown' }
+
+// ── 포트 ───────────────────────────────────────────────
+
+/** 결제 운영 원장 + 구독 엔타이틀먼트 저장소 포트. */
+export interface RenewalStore {
+  reserveRenewal(
+    candidate: RenewalCandidate,
+    idempotencyKey: string,
+    orderId: string,
+  ): Promise<RenewalReservation>
+  getOperation(operationId: string): Promise<RenewalOperation | null>
+  /** false면 저장소가 상태 전이를 거부했거나 실패했다. */
+  markOperation(
+    operationId: string,
+    state: 'external_created' | 'charged' | 'failed',
+    externalReference: string | null,
+    errorCode: string | null,
+  ): Promise<boolean>
+  /** 갱신 실패를 한 번 기록한다(실패 카운터 증가, 3회 누적 시 회수). false면 기록되지 않았다. */
+  recordRenewalFailure(
+    candidate: RenewalCandidate,
+    operationId: string,
+    at: Date,
+  ): Promise<boolean>
+  applyRenewalPayment(
+    application: RenewalPaymentApplication,
+  ): Promise<{ applied: boolean; duplicate: boolean }>
+}
+
+/** Payple 빌링/결과조회 포트. */
+export interface RenewalPaymentGateway {
+  /** 결과가 불명확하면 PaypleBillingError(definitive=false)를 던진다. */
+  charge(request: ChargeRequest): Promise<ChargeReceipt>
+  lookup(orderId: string): Promise<LookupOutcome>
+}
+
+export interface RenewalDeps {
+  store: RenewalStore
+  gateway: RenewalPaymentGateway
+  now: () => Date
+  newOrderId: (userId: string) => string
+}
+
+// ── 순수 정책 ──────────────────────────────────────────
+
+export function normalizeRenewalCandidate(row: Record<string, unknown>): RenewalCandidate | null {
+  const userId = typeof row.user_id === 'string' ? row.user_id : ''
+  const tier = row.tier === 'pro' || row.tier === 'pro_plus' ? row.tier : null
+  const payerId = typeof row.payple_payer_id === 'string' ? row.payple_payer_id : null
+  const resourceId = typeof row.provider_resource_id === 'string' ? row.provider_resource_id : null
+  const currentPeriodEnd = typeof row.current_period_end === 'string' ? row.current_period_end : null
+  if (!userId || !tier || !payerId || !resourceId || !currentPeriodEnd) return null
+  return {
+    userId,
+    tier,
+    payerId,
+    resourceId,
+    currentPeriodEnd,
+    renewalFailures: Number(row.renewal_failures ?? 0),
+  }
+}
+
+/**
+ * 같은 기간·같은 시도 번호면 같은 키가 나온다. 시도 번호는 기록된 실패 횟수로만
+ * 전진하므로, 결과 불명 작업은 재조정(reconcileReplay)으로 반드시 결론을 내야 한다.
+ */
+export function renewalIdempotencyKey(candidate: RenewalCandidate): string {
+  const attempt = candidate.renewalFailures + 1
+  const periodKey = new Date(candidate.currentPeriodEnd).getTime()
+  return `payple-renew:${candidate.userId}:${periodKey}:attempt${attempt}`
+}
+
+const IN_FLIGHT_STATES: ReadonlySet<string> = new Set(['reserved', 'external_created', 'charged'])
+
+export type ReplayDecision = 'already_applied' | 'in_progress' | 'reconcile'
+
+/**
+ * 멱등 재생된 작업을 어떻게 다룰지 결정한다.
+ * - applied: 이미 반영됨 → 건드리지 않는다.
+ * - 진행 중 상태 + 리스 유효: 다른 실행이 처리 중일 수 있다 → 건너뛴다.
+ * - 그 외(리스 만료, failed): Payple 결과조회로 결론을 낸다.
+ */
+export function decideReplay(operation: RenewalOperation, now: Date): ReplayDecision {
+  if (operation.state === 'applied') return 'already_applied'
+  if (IN_FLIGHT_STATES.has(operation.state)) {
+    const expiresAt = operation.expiresAt ? new Date(operation.expiresAt).getTime() : Number.NaN
+    if (Number.isFinite(expiresAt) && expiresAt > now.getTime()) return 'in_progress'
+  }
+  return 'reconcile'
+}
+
+const CANCELED_PAY_STATES: ReadonlySet<string> = new Set(['승인취소완료', 'canceled'])
+
+/** 결과조회 성공 응답을 결론으로 바꾼다. 취소된 거래는 청구되지 않은 것으로 본다. */
+export function interpretLookup(result: {
+  PCD_PAY_OID: string
+  PCD_PAY_TOTAL?: string
+  PCD_PAYER_ID?: string
+  PCD_PAY_TIME?: string
+  PCD_PAY_STATE?: string
+}): LookupOutcome {
+  if (result.PCD_PAY_STATE && CANCELED_PAY_STATES.has(result.PCD_PAY_STATE)) {
+    return { kind: 'not_charged' }
+  }
+  return {
+    kind: 'charged',
+    payment: {
+      orderId: result.PCD_PAY_OID,
+      total: result.PCD_PAY_TOTAL ?? '',
+      payerId: result.PCD_PAYER_ID,
+      payTime: result.PCD_PAY_TIME,
+    },
+  }
+}
+
+/**
+ * 결과조회 실패를 분류한다. Payple이 거래를 성공으로 확인해 주지 않은 경우
+ * (payple_lookup_mismatch)만 "청구 없음"으로 확정한다 — 웹훅도 같은 결과로는
+ * 엔타이틀먼트를 주지 않는다. 전송/HTTP/파싱 오류는 다음 실행에서 다시 본다.
+ */
+export function classifyLookupFailure(error: unknown): 'not_charged' | 'unknown' {
+  if (error instanceof PaypleVerificationError && error.code === 'payple_lookup_mismatch') {
+    return 'not_charged'
+  }
+  return 'unknown'
+}
+
+export function receiptMatchesCandidate(
+  receipt: ChargeReceipt,
+  orderId: string,
+  candidate: RenewalCandidate,
+): boolean {
+  return receipt.orderId === orderId
+    && receipt.total === String(TIER_PRICE[candidate.tier])
+    && (!receipt.payerId || receipt.payerId === candidate.payerId)
+}
+
+export async function withTimeout<T>(
+  task: Promise<T>,
+  timeoutMs: number,
+  onTimeout: () => Error,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(onTimeout()), timeoutMs)
+  })
+  try {
+    return await Promise.race([task, timeout])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}
+
+// ── 유스케이스 ─────────────────────────────────────────
+
+function buildApplication(
+  candidate: RenewalCandidate,
+  orderId: string,
+  operationId: string,
+  receipt: ChargeReceipt,
+  now: Date,
+): RenewalPaymentApplication {
+  const eventTime = receipt.payTime ? parsePaypleTimestamp(receipt.payTime) : now
+  const { start, end } = calcSubscriptionPeriod(eventTime)
+  return { candidate, orderId, operationId, eventTime, periodStart: start, periodEnd: end }
+}
+
+async function applyConfirmedCharge(
+  deps: RenewalDeps,
+  candidate: RenewalCandidate,
+  orderId: string,
+  operationId: string,
+  receipt: ChargeReceipt,
+): Promise<RenewalResult> {
+  const applied = await deps.store.applyRenewalPayment(
+    buildApplication(candidate, orderId, operationId, receipt, deps.now()),
+  )
+  if (!applied.applied && !applied.duplicate) {
+    throw new Error('renewal_requires_reconciliation')
+  }
+  return { userId: candidate.userId, tier: candidate.tier, success: true, orderId }
+}
+
+/**
+ * 멱등 재생된 갱신 작업에 결론을 낸다. 결과가 불명확한 채로 남은 작업
+ * (external_created/reserved 리스 만료, failed)은 Payple 결과조회로 확인해
+ * 청구됐으면 반영하고, 청구되지 않았으면 실패를 기록해 시도 번호를 전진시킨다.
+ */
+export async function reconcileReplay(
+  deps: RenewalDeps,
+  candidate: RenewalCandidate,
+  operationId: string,
+): Promise<RenewalResult> {
+  const base = { userId: candidate.userId, tier: candidate.tier }
+  const operation = await deps.store.getOperation(operationId)
+  if (!operation) return { ...base, success: false, error: 'renewal_requires_reconciliation' }
+
+  const decision = decideReplay(operation, deps.now())
+  if (decision === 'already_applied') return { ...base, success: false, error: 'idempotent_replay' }
+  if (decision === 'in_progress') {
+    return { ...base, success: false, error: 'renewal_operation_in_progress' }
+  }
+
+  const orderId = operation.providerOrderId
+  const outcome: LookupOutcome = orderId
+    ? await deps.gateway.lookup(orderId)
+    : { kind: 'not_charged' }
+
+  if (outcome.kind === 'unknown') {
+    return { ...base, success: false, error: 'renewal_requires_reconciliation' }
+  }
+  if (outcome.kind === 'not_charged') {
+    const recorded = await deps.store.recordRenewalFailure(candidate, operation.id, deps.now())
+    return {
+      ...base,
+      success: false,
+      error: recorded ? 'payple_renewal_failed' : 'renewal_requires_reconciliation',
+    }
+  }
+
+  // 청구가 확인됐다. 금액·주문·결제자가 어긋나면 자동 반영하지 않는다.
+  if (!orderId || !receiptMatchesCandidate(outcome.payment, orderId, candidate)) {
+    return { ...base, success: false, error: 'renewal_requires_reconciliation' }
+  }
+  try {
+    return await applyConfirmedCharge(deps, candidate, orderId, operation.id, outcome.payment)
+  } catch {
+    return { ...base, success: false, error: 'renewal_requires_reconciliation' }
+  }
+}
+
+/** 구독 한 건을 갱신한다. 새 작업이면 청구하고, 재생된 작업이면 재조정한다. */
+export async function renewSubscription(
+  deps: RenewalDeps,
+  candidate: RenewalCandidate,
+): Promise<RenewalResult> {
+  const { userId, tier, payerId } = candidate
+  const idempotencyKey = renewalIdempotencyKey(candidate)
+  const orderId = deps.newOrderId(userId)
+  let operationId: string | null = null
+  let charged = false
+  try {
+    const reservation = await deps.store.reserveRenewal(candidate, idempotencyKey, orderId)
+    if (reservation.kind === 'replay') {
+      return await reconcileReplay(deps, candidate, reservation.operationId)
+    }
+    if (reservation.kind === 'rejected') {
+      return { userId, tier, success: false, error: reservation.reason }
+    }
+    operationId = reservation.operationId
+
+    const receipt = await deps.gateway.charge({
+      payerId,
+      amount: TIER_PRICE[tier],
+      orderId,
+      goodsName: TIER_GOODS_NAME[tier],
+    })
+    charged = true
+    const marked = await deps.store.markOperation(
+      operationId,
+      'charged',
+      receipt.orderId || orderId,
+      null,
+    )
+    if (!marked) throw new Error('renewal_operation_update_failed')
+    if (!receiptMatchesCandidate(receipt, orderId, candidate)) {
+      throw new Error('renewal_response_mismatch')
+    }
+    return await applyConfirmedCharge(deps, candidate, orderId, operationId, receipt)
+  } catch (error) {
+    const chargeOutcomeUnknown = error instanceof PaypleBillingError && !error.definitive
+    if (operationId && !charged) {
+      if (chargeOutcomeUnknown) {
+        // 결과 불명: 실패로 세지 않고 남겨 둔다. 다음 실행에서 멱등 재생 → reconcileReplay가 결론을 낸다.
+        await deps.store.markOperation(operationId, 'external_created', orderId, null)
+      } else if (error instanceof PaypleBillingError && error.definitive) {
+        await deps.store.recordRenewalFailure(candidate, operationId, deps.now())
+      } else {
+        await deps.store.markOperation(operationId, 'failed', null, 'payple_renewal_failed')
+      }
+    }
+    return {
+      userId,
+      tier,
+      success: false,
+      error: charged || chargeOutcomeUnknown
+        ? 'renewal_requires_reconciliation'
+        : 'payple_renewal_failed',
+    }
+  }
+}