SaaS 구독 결제를 만들며 이해한 Facade 패턴

// subscription.ts
export class Subscription {
  #state: SubscriptionState;

  constructor(state: SubscriptionState) {
    // 전달받은 객체를 나중에 수정해도 구독 상태가 바뀌지 않도록 복사해요.
    this.#state = structuredClone(state);
  }

  get id(): string {
    return this.#state.id;
  }

  createRenewalInvoice(now: Date): InvoiceDraft | null {
    if (!this.#state.autoRenewalEnabled || now < this.#state.trialEndsAt) {
      return null;
    }

    const plan = PLAN_PRICES[this.#state.billingCycle];
    // 첫 청구일에서 이미 반영한 유료 기간만큼 건너뛰어요.
    const monthsAfterFirstBilling = this.#state.completedBillingPeriods * plan.months;
    const periodStartsAt = getBillingDate(this.#state.firstBillingDate, monthsAfterFirstBilling);
    const periodEndsAt = getBillingDate(
      this.#state.firstBillingDate,
      monthsAfterFirstBilling + plan.months,
    );
    // 청구 시점이 아직 오지 않았거나 해당 이용 기간이 모두 지났으면 청구하지 않아요.
    if (now < periodStartsAt || now >= periodEndsAt) {
      return null;
    }

    return {
      subscriptionId: this.#state.id,
      accountId: this.#state.accountId,
      paymentMethodId: this.#state.paymentMethodId,
      billingPeriodIndex: this.#state.completedBillingPeriods,
      amountKrw: plan.amountKrw,
      description: plan.description,
      periodStartsAt,
      periodEndsAt,
    };
  }

  applyPaidInvoice(invoice: Invoice): void {
    const isExpectedInvoice =
      invoice.subscriptionId === this.#state.id &&
      invoice.billingPeriodIndex === this.#state.completedBillingPeriods;
    if (!isExpectedInvoice) {
      throw new Error("현재 구독 기간에 해당하는 청구서가 아닙니다.");
    }

    // 결제 확인이 늦어져도 이용 종료일은 청구서에 정한 날짜를 유지해요.
    this.#state.paidUntil = new Date(invoice.periodEndsAt);
    this.#state.completedBillingPeriods += 1;
  }

  getAccessLevel(now: Date): AccessLevel {
    if (now < this.#state.trialEndsAt) {
      return "TRIAL";
    }

    if (this.#state.paidUntil && now < this.#state.paidUntil) {
      return "PAID";
    }

    return "FREE";
  }

  // 저장용 데이터도 사본으로 반환해 내부 객체의 참조를 노출하지 않아요.
  toState(): SubscriptionState {
    return structuredClone(this.#state);
  }
}ts

// subscription.ts
import { getBillingDate, type BillingDate } from "./billing-date";
import type { Invoice, InvoiceDraft } from "./contracts";

export type BillingCycle = "MONTHLY" | "YEARLY";
export type AccessLevel = "TRIAL" | "PAID" | "FREE";

export interface SubscriptionState {
  id: string;
  accountId: string;
  paymentMethodId: string;
  billingCycle: BillingCycle;
  firstBillingDate: BillingDate;
  completedBillingPeriods: number;
  autoRenewalEnabled: boolean;
  trialEndsAt: Date;
  paidUntil: Date | null;
}

const PLAN_PRICES = {
  MONTHLY: { amountKrw: 10_000, months: 1, description: "월간 구독" },
  YEARLY: { amountKrw: 100_000, months: 12, description: "연간 구독" },
} as const;ts

// contracts.ts
export interface InvoiceDraft {
  subscriptionId: string;
  accountId: string;
  paymentMethodId: string;
  billingPeriodIndex: number;
  amountKrw: number;
  description: string;
  periodStartsAt: Date;
  periodEndsAt: Date;
}

export interface Invoice extends InvoiceDraft {
  id: string;
  status: "OPEN" | "PAID";
}ts

// billing-date.ts
export interface BillingDate {
  year: number;
  month: number;
  day: number;
}

export function getBillingDate(firstBillingDate: BillingDate, monthsAfter: number): Date {
  const targetMonth = new Date(
    Date.UTC(firstBillingDate.year, firstBillingDate.month - 1 + monthsAfter, 1),
  );
  const year = targetMonth.getUTCFullYear();
  const month = targetMonth.getUTCMonth();
  const lastDay = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
  const day = Math.min(firstBillingDate.day, lastDay);

  // 한국 시간 자정을 UTC로 변환해 저장해요.
  return new Date(Date.UTC(year, month, day, -9));
}ts

// subscription.service.ts
import { Injectable } from "@nestjs/common";
import type { Invoice } from "./contracts";
import { SubscriptionRepository } from "./subscription.repository";

@Injectable()
export class SubscriptionService {
  constructor(private readonly subscriptionRepository: SubscriptionRepository) {}

  async prepareRenewal(subscriptionId: string): Promise<Invoice | null> {
    const subscription = await this.subscriptionRepository.getById(subscriptionId);
    const invoiceDraft = subscription.createRenewalInvoice(new Date());
    if (!invoiceDraft) {
      return null;
    }

    // 같은 구독 기간의 청구서가 이미 있으면 저장된 금액과 기간을 그대로 사용해요.
    return this.subscriptionRepository.getOrCreateInvoice(invoiceDraft);
  }

  async applyPayment(invoiceId: string, paymentId: string): Promise<void> {
    await this.subscriptionRepository.transaction(async (transaction) => {
      const invoice = await transaction.getInvoiceForUpdate(invoiceId);

      // 이 청구서와 연결된 결제인지, 금액·통화가 맞고 성공했는지 확인해요.
      await transaction.assertSuccessfulPayment(invoice, paymentId);

      // 복구 작업이 반복돼도 같은 이용 기간을 두 번 반영하지 않아요.
      if (invoice.status === "PAID") {
        return;
      }

      const subscription = await transaction.getSubscriptionForUpdate(invoice.subscriptionId);
      subscription.applyPaidInvoice(invoice);

      // 이용 기간 변경과 청구서의 결제 완료 처리를 함께 저장해요.
      await transaction.saveSubscription(subscription);
      await transaction.markInvoicePaid(invoice.id, paymentId);
    });
  }
}ts

// subscription.repository.ts
import type { Invoice, InvoiceDraft } from "./contracts";
import type { Subscription } from "./subscription";

export interface SubscriptionTransaction {
  getInvoiceForUpdate(invoiceId: string): Promise<Invoice>;
  getSubscriptionForUpdate(subscriptionId: string): Promise<Subscription>;
  assertSuccessfulPayment(invoice: Invoice, paymentId: string): Promise<void>;
  saveSubscription(subscription: Subscription): Promise<void>;
  markInvoicePaid(invoiceId: string, paymentId: string): Promise<void>;
}

export abstract class SubscriptionRepository {
  abstract getById(subscriptionId: string): Promise<Subscription>;
  abstract getOrCreateInvoice(draft: InvoiceDraft): Promise<Invoice>;
  abstract transaction<T>(work: (transaction: SubscriptionTransaction) => Promise<T>): Promise<T>;
}ts

// payment.service.ts
import { Inject, Injectable } from "@nestjs/common";
import {
  PAYMENT_GATEWAY,
  type Invoice,
  type PaymentGateway,
  type PaymentResult,
  type GatewayPaymentResult,
} from "./contracts";
import { PaymentRepository, type PaymentExecution } from "./payment.repository";

@Injectable()
export class PaymentService {
  constructor(
    private readonly paymentRepository: PaymentRepository,
    @Inject(PAYMENT_GATEWAY) private readonly paymentGateway: PaymentGateway,
  ) {}

  async payInvoice(invoice: Invoice): Promise<PaymentResult> {
    // 저장된 결제 시도를 확인해 새 승인, 기존 결제 조회, 결과 반환 중 하나를 정해요.
    const execution = await this.paymentRepository.prepare(invoice);

    return this.execute(execution);
  }

  async reconcile(paymentId: string): Promise<{ invoiceId: string; result: PaymentResult }> {
    const payment = await this.paymentRepository.getById(paymentId);
    const execution = await this.paymentRepository.prepareReconciliation(paymentId);
    const result = await this.execute(execution);

    return { invoiceId: payment.invoiceId, result };
  }

  private async execute(execution: PaymentExecution): Promise<PaymentResult> {
    if (execution.action === "RETURN_RESULT") {
      return execution.result;
    }

    const payment = execution.payment;
    let result: GatewayPaymentResult;

    try {
      if (execution.action === "LOOKUP") {
        // 승인 응답을 놓쳤을 수 있으므로 저장된 주문번호로 기존 결제를 조회해요.
        result = await this.paymentGateway.findPayment(payment.request);
      } else {
        result = await this.paymentGateway.charge(payment.request);
      }
    } catch (error) {
      // 자동으로 처리할 수 없는 연동 오류는 운영 확인 대상으로 기록해요.
      await this.paymentRepository.markForReview(payment);
      throw error;
    }

    // 승인 후 저장 실패를 외부 결제 실패로 바꾸지 않아요.
    return this.paymentRepository.saveResult(payment, result);
  }
}ts

// payment.repository.ts
import type { GatewayPaymentResult, Invoice, PaymentRequest, PaymentResult } from "./contracts";

export interface PaymentAttempt {
  id: string;
  invoiceId: string;
  lockToken: string;
  request: PaymentRequest;
}

export type PaymentExecution =
  | { action: "RETURN_RESULT"; result: PaymentResult }
  | { action: "CHARGE"; payment: PaymentAttempt }
  | { action: "LOOKUP"; payment: PaymentAttempt };

export abstract class PaymentRepository {
  abstract prepare(invoice: Invoice): Promise<PaymentExecution>;
  abstract getById(paymentId: string): Promise<PaymentAttempt>;
  abstract prepareReconciliation(
    paymentId: string,
  ): Promise<Exclude<PaymentExecution, { action: "CHARGE" }>>;
  abstract saveResult(
    payment: PaymentAttempt,
    result: GatewayPaymentResult,
  ): Promise<PaymentResult>;
  abstract markForReview(payment: PaymentAttempt): Promise<void>;
}ts

// contracts.ts
export interface PaymentRequest {
  accountId: string;
  paymentMethodId: string;
  orderId: string;
  amountKrw: number;
  description: string;
  idempotencyKey: string;
}

export type GatewayPaymentResult =
  | { status: "SUCCEEDED"; providerPaymentId: string; approvedAt: Date }
  | { status: "FAILED"; failureCode: PaymentFailureCode }
  | { status: "PENDING" };ts

// toss.schema.ts
import { z } from "zod";

export const tossBillingBodySchema = z.object({
  // 2~50자이고, 특수문자(-, _, =, ., @)를 하나 이상 포함해야 해요.
  customerKey: z.string().regex(/^(?=.{2,50}$)(?=.*[-_=.@])[-A-Za-z0-9_=.@]+$/),
  amount: z.number().int().min(100),
  orderId: z.string().regex(/^[A-Za-z0-9_-]{6,64}$/),
  orderName: z.string().min(1).max(100),
});

export const tossChargeRequestSchema = z.object({
  billingKey: z.string().min(1).max(200),
  idempotencyKey: z.string().min(1).max(300),
  body: tossBillingBodySchema,
});

export const tossErrorSchema = z.object({
  code: z.string().min(1),
  message: z.string(),
});

export const tossPaymentSchema = z.object({
  paymentKey: z.string().min(1).max(200),
  orderId: z.string().min(1),
  type: z.string(),
  currency: z.string(),
  totalAmount: z.number().int().nonnegative(),
  status: z.string(),
  approvedAt: z.iso.datetime({ offset: true }).nullable(),
  card: z.object({}).nullable(),
  failure: tossErrorSchema.nullish(),
});

export type TossChargeRequest = z.infer<typeof tossChargeRequestSchema>;
export type TossPaymentResponse = z.infer<typeof tossPaymentSchema>;ts

// toss-payment.gateway.ts
import { Injectable } from "@nestjs/common";
import type { GatewayPaymentResult, PaymentGateway, PaymentRequest } from "./contracts";
import { TossBillingClient } from "./toss-billing.client";
import { TossPaymentMethodRepository } from "./toss-payment-method.repository";
import { mapTossError, mapTossPayment } from "./toss-payment.mapper";
import type { TossPaymentResponse } from "./toss.schema";

@Injectable()
export class TossPaymentGateway implements PaymentGateway {
  constructor(
    private readonly tossBillingClient: TossBillingClient,
    private readonly paymentMethodRepository: TossPaymentMethodRepository,
  ) {}

  async charge(request: PaymentRequest): Promise<GatewayPaymentResult> {
    const paymentMethod = await this.paymentMethodRepository.findForAccount(
      request.paymentMethodId,
      request.accountId,
    );
    if (!paymentMethod) {
      // 이 계정의 결제수단을 찾지 못했으므로 토스에 승인 요청을 보내지 않아요.
      return { status: "FAILED", failureCode: "INVALID_PAYMENT_METHOD" };
    }

    return this.send(request, "CHARGE", () =>
      this.tossBillingClient.charge({
        billingKey: paymentMethod.billingKey,
        idempotencyKey: request.idempotencyKey,
        body: {
          customerKey: paymentMethod.customerKey,
          amount: request.amountKrw,
          orderId: request.orderId,
          orderName: request.description,
        },
      }),
    );
  }

  findPayment(request: PaymentRequest): Promise<GatewayPaymentResult> {
    return this.send(request, "LOOKUP", () =>
      this.tossBillingClient.findByOrderId(request.orderId),
    );
  }

  private async send(
    request: PaymentRequest,
    operation: "CHARGE" | "LOOKUP",
    sendRequest: () => Promise<TossPaymentResponse>,
  ): Promise<GatewayPaymentResult> {
    let response: TossPaymentResponse;

    try {
      response = await sendRequest();
    } catch (error) {
      return mapTossError(error, operation);
    }

    return mapTossPayment(response, request);
  }
}ts

// toss-payment.mapper.ts
import {
  PaymentIntegrationError,
  type GatewayPaymentResult,
  type PaymentFailureCode,
  type PaymentRequest,
} from "./contracts";
import {
  TossApiError,
  TossInvalidRequestError,
  TossUnconfirmedResponseError,
} from "./toss-billing.client";
import type { TossPaymentResponse } from "./toss.schema";

const CARD_FAILURE_CODES = new Map<string, PaymentFailureCode>([
  ["REJECT_CARD_PAYMENT", "CARD_DECLINED"],
  ["REJECT_CARD_COMPANY", "CARD_DECLINED"],
  ["INVALID_REJECT_CARD", "CARD_DECLINED"],
  ["INVALID_STOPPED_CARD", "INVALID_PAYMENT_METHOD"],
  ["INVALID_CARD_EXPIRATION", "INVALID_PAYMENT_METHOD"],
]);

export function mapTossPayment(
  response: TossPaymentResponse,
  request: PaymentRequest,
): GatewayPaymentResult {
  const matchesInvoice =
    response.orderId === request.orderId &&
    response.totalAmount === request.amountKrw &&
    response.currency === "KRW" &&
    response.type === "BILLING";
  if (!matchesInvoice) {
    throw new PaymentIntegrationError("승인 내역이 청구서와 일치하지 않습니다.");
  }

  switch (response.status) {
    case "DONE": {
      if (!response.approvedAt || !response.card) {
        throw new PaymentIntegrationError("카드 승인 정보를 확인할 수 없습니다.");
      }

      return {
        status: "SUCCEEDED",
        providerPaymentId: response.paymentKey,
        approvedAt: new Date(response.approvedAt),
      };
    }
    case "ABORTED":
      return {
        status: "FAILED",
        failureCode: CARD_FAILURE_CODES.get(response.failure?.code ?? "") ?? "PAYMENT_FAILED",
      };
    case "EXPIRED":
      return { status: "FAILED", failureCode: "PAYMENT_FAILED" };
    case "READY":
    case "IN_PROGRESS":
      return { status: "PENDING" };
    default:
      // 취소·부분 취소·예상하지 못한 상태는 운영 확인 대상으로 남겨요.
      throw new PaymentIntegrationError("별도 확인이 필요한 결제 상태입니다.");
  }
}

export function mapTossError(error: unknown, operation: "CHARGE" | "LOOKUP"): GatewayPaymentResult {
  if (error instanceof TossUnconfirmedResponseError) {
    // timeout이나 응답 해석 실패만으로 실제 승인까지 실패했다고 판단하지 않아요.
    return { status: "PENDING" };
  }

  if (error instanceof TossInvalidRequestError) {
    throw new PaymentIntegrationError("결제 요청 값이 올바르지 않습니다.", { cause: error });
  }

  if (!(error instanceof TossApiError)) {
    throw error;
  }

  const failureCode = CARD_FAILURE_CODES.get(error.code);
  if (operation === "CHARGE" && failureCode) {
    return { status: "FAILED", failureCode };
  }

  const needsConfirmation =
    error.httpStatus >= 500 ||
    error.code === "IDEMPOTENT_REQUEST_PROCESSING" ||
    error.code === "DUPLICATED_ORDER_ID" ||
    (operation === "LOOKUP" && error.code === "NOT_FOUND_PAYMENT");
  if (needsConfirmation) {
    return { status: "PENDING" };
  }

  throw new PaymentIntegrationError(undefined, { cause: error });
}ts

// contracts.ts
export class PaymentIntegrationError extends Error {
  constructor(message = "결제 연동을 확인해야 합니다.", options?: ErrorOptions) {
    super(message, options);
    this.name = "PaymentIntegrationError";
  }
}ts

// toss-payment-method.repository.ts
export interface TossPaymentMethod {
  billingKey: string;
  customerKey: string;
}

export abstract class TossPaymentMethodRepository {
  abstract findForAccount(
    paymentMethodId: string,
    accountId: string,
  ): Promise<TossPaymentMethod | null>;
}ts

// toss-billing.client.ts
import { Inject, Injectable } from "@nestjs/common";
import {
  tossBillingBodySchema,
  tossChargeRequestSchema,
  tossErrorSchema,
  tossPaymentSchema,
  type TossChargeRequest,
  type TossPaymentResponse,
} from "./toss.schema";

export class TossApiError extends Error {
  constructor(
    public httpStatus: number,
    public code: string,
  ) {
    super("Toss API request failed");
  }
}

export class TossInvalidRequestError extends Error {}
export class TossUnconfirmedResponseError extends Error {}

export const TOSS_SECRET_KEY = Symbol("TOSS_SECRET_KEY");
const TOSS_API_URL = "https://api.tosspayments.com";
const TOSS_CHARGE_TIMEOUT_MS = 60_000;
const TOSS_LOOKUP_TIMEOUT_MS = 10_000;

@Injectable()
export class TossBillingClient {
  constructor(@Inject(TOSS_SECRET_KEY) private readonly secretKey: string) {}

  async charge(request: TossChargeRequest): Promise<TossPaymentResponse> {
    const validation = tossChargeRequestSchema.safeParse(request);
    if (!validation.success) {
      throw new TossInvalidRequestError();
    }

    const { billingKey, idempotencyKey, body } = validation.data;

    return this.request(
      `/v1/billing/${encodeURIComponent(billingKey)}`,
      {
        method: "POST",
        headers: { "Idempotency-Key": idempotencyKey },
        body: JSON.stringify(body),
      },
      TOSS_CHARGE_TIMEOUT_MS,
    );
  }

  async findByOrderId(orderId: string): Promise<TossPaymentResponse> {
    const validation = tossBillingBodySchema.shape.orderId.safeParse(orderId);
    if (!validation.success) {
      throw new TossInvalidRequestError();
    }

    return this.request(
      `/v1/payments/orders/${encodeURIComponent(validation.data)}`,
      {
        method: "GET",
      },
      TOSS_LOOKUP_TIMEOUT_MS,
    );
  }

  private async request(
    path: string,
    options: RequestInit,
    timeoutMs: number,
  ): Promise<TossPaymentResponse> {
    const headers = new Headers(options.headers);
    const credentials = Buffer.from(`${this.secretKey}:`).toString("base64");

    headers.set("Authorization", `Basic ${credentials}`);
    headers.set("Content-Type", "application/json");

    let response: Response;
    let body: unknown;

    try {
      response = await fetch(`${TOSS_API_URL}${path}`, {
        ...options,
        headers,
        signal: AbortSignal.timeout(timeoutMs),
      });
      body = await response.json();
    } catch {
      throw new TossUnconfirmedResponseError();
    }

    if (!response.ok) {
      const validation = tossErrorSchema.safeParse(body);
      if (!validation.success) {
        throw new TossUnconfirmedResponseError();
      }

      throw new TossApiError(response.status, validation.data.code);
    }

    const validation = tossPaymentSchema.safeParse(body);
    if (!validation.success) {
      throw new TossUnconfirmedResponseError();
    }

    return validation.data;
  }
}ts

// billing.module.ts
import { Module } from "@nestjs/common";
import { PAYMENT_GATEWAY } from "./contracts";
import { PaymentService } from "./payment.service";
import { SubscriptionService } from "./subscription.service";
import { SubscriptionBillingFacade } from "./subscription-billing.facade";
import { TossBillingClient, TOSS_SECRET_KEY } from "./toss-billing.client";
import { TossPaymentGateway } from "./toss-payment.gateway";
import { BillingPersistenceModule } from "./billing-persistence.module";

@Module({
  imports: [BillingPersistenceModule],
  providers: [
    SubscriptionBillingFacade,
    SubscriptionService,
    PaymentService,
    TossBillingClient,
    { provide: PAYMENT_GATEWAY, useClass: TossPaymentGateway },
    {
      provide: TOSS_SECRET_KEY,
      useFactory: () => {
        const secretKey = process.env.TOSS_SECRET_KEY;
        if (!secretKey) {
          throw new Error("TOSS_SECRET_KEY is required");
        }

        return secretKey;
      },
    },
  ],
  exports: [SubscriptionBillingFacade],
})
export class BillingModule {}ts

// subscription-billing.fixture.ts
import { Test } from "@nestjs/testing";
import { onTestFinished } from "vitest";
import type { Invoice, InvoiceDraft, PaymentResult } from "./contracts";
import { PaymentService } from "./payment.service";
import { PaymentServiceStub } from "./payment-service.stub";
import { Subscription } from "./subscription";
import { SubscriptionService } from "./subscription.service";
import { SubscriptionRepository, type SubscriptionTransaction } from "./subscription.repository";
import { SubscriptionBillingFacade } from "./subscription-billing.facade";

interface SavedPayment {
  id: string;
  invoiceId: string;
  amountKrw: number;
  currency: "KRW";
}

// 상태를 메모리에 보관하는 Fake예요. DB의 잠금과 transaction은 재현하지 않아요.
class InMemorySubscriptionRepository extends SubscriptionRepository {
  invoice: Invoice | null = null;

  constructor(
    private subscription: Subscription,
    private successfulPayment: SavedPayment | null,
  ) {
    super();
  }

  async getById(subscriptionId: string): Promise<Subscription> {
    if (subscriptionId !== this.subscription.id) {
      throw new Error("구독을 찾을 수 없습니다.");
    }

    return this.subscription;
  }

  async getOrCreateInvoice(draft: InvoiceDraft): Promise<Invoice> {
    this.invoice ??= { ...draft, id: "invoice_001", status: "OPEN" };

    return this.invoice;
  }

  async transaction<T>(work: (transaction: SubscriptionTransaction) => Promise<T>): Promise<T> {
    const transaction: SubscriptionTransaction = {
      getInvoiceForUpdate: async (invoiceId) => {
        if (!this.invoice || this.invoice.id !== invoiceId) {
          throw new Error("청구서를 찾을 수 없습니다.");
        }

        return this.invoice;
      },
      getSubscriptionForUpdate: (subscriptionId) => this.getById(subscriptionId),
      assertSuccessfulPayment: async (invoice, paymentId) => {
        const payment = this.successfulPayment;
        if (
          !payment ||
          payment.id !== paymentId ||
          payment.invoiceId !== invoice.id ||
          payment.amountKrw !== invoice.amountKrw ||
          payment.currency !== "KRW"
        ) {
          throw new Error("청구서와 일치하는 성공한 결제가 없습니다.");
        }
      },
      saveSubscription: async (subscription) => {
        this.subscription = subscription;
      },
      markInvoicePaid: async (invoiceId, paymentId) => {
        if (
          !this.invoice ||
          this.invoice.id !== invoiceId ||
          this.successfulPayment?.id !== paymentId
        ) {
          throw new Error("청구서에 결제를 연결할 수 없습니다.");
        }

        this.invoice.status = "PAID";
      },
    };

    return work(transaction);
  }
}

export async function createTestContext(paymentResult: PaymentResult | Error) {
  const subscription = new Subscription({
    id: "subscription_001",
    accountId: "account_001",
    paymentMethodId: "method_001",
    billingCycle: "MONTHLY",
    // 9월 21일 가입, 14일 체험 뒤 10월 5일이 첫 청구일이에요.
    firstBillingDate: { year: 2026, month: 10, day: 5 },
    completedBillingPeriods: 0,
    autoRenewalEnabled: true,
    trialEndsAt: new Date("2026-10-05T00:00:00+09:00"),
    paidUntil: null,
  });

  // SUCCEEDED는 내부 결제 기록까지 저장한 결과이므로 해당 기록도 준비해요.
  const successfulPayment: SavedPayment | null =
    !(paymentResult instanceof Error) && paymentResult.status === "SUCCEEDED"
      ? {
          id: paymentResult.paymentId,
          invoiceId: "invoice_001",
          amountKrw: 10_000,
          currency: "KRW",
        }
      : null;
  const repository = new InMemorySubscriptionRepository(subscription, successfulPayment);
  const module = await Test.createTestingModule({
    providers: [
      SubscriptionBillingFacade,
      SubscriptionService,
      { provide: SubscriptionRepository, useValue: repository },
      { provide: PaymentService, useValue: new PaymentServiceStub(paymentResult) },
    ],
  }).compile();
  onTestFinished(() => module.close());

  return {
    repository,
    facade: module.get(SubscriptionBillingFacade),
  };
}ts

// vitest.config.ts
import { defineConfig } from "vitest/config";
import swc from "unplugin-swc";

export default defineConfig({
  test: {
    environment: "node",
    globals: false,
  },
  plugins: [
    swc.vite({
      jsc: {
        parser: { syntax: "typescript", decorators: true },
        transform: { legacyDecorator: true, decoratorMetadata: true },
      },
      module: { type: "es6" },
    }),
  ],
});ts

// reconcile-payment.job.ts
// 미확정 결제를 조회하는 Worker에서 호출해요.
await subscriptionBillingFacade.reconcilePayment(paymentId);ts