리액트 클린 아키텍처 - 3개 핵심 레이어로 설계하는 유지보수성

// ❌ TossConfirmButton.tsx - 토스 페이먼츠 결제 승인
import { useMutation } from "@tanstack/react-query";
import axios from "axios";

export function TossConfirmButton({ order, paymentKey }) {
  const { mutate } = useMutation({
    mutationFn: async () => {
      // ❌ 문제 2: 비즈니스 로직 산재 - 검증 로직이 컴포넌트에 직접 있음
      if (order.totalAmount < 10_000) {
        throw new Error("최소 결제 금액은 10,000원입니다");
      }

      // ❌ 문제 1: API 엔드포인트가 컴포넌트에 박혀있음
      const response = await axios.post("/api/payments/toss/confirm", {
        paymentKey,
        orderId: order.orderId,
        amount: order.totalAmount,
      });

      return response.data; // { paymentKey, status: "DONE", totalAmount, ... }
    },
    onSuccess: (data) => {
      // ❌ 문제 3: 토스 응답 형식에 직접 의존
      alert(
        `결제 완료! 결제 키: ${data.paymentKey}, 금액: ${data.totalAmount}원`
      );
    },
  });

  return <button onClick={() => mutate()}>토스 결제 승인</button>;
}ts

// ❌ StripeConfirmButton.tsx - Stripe 결제 승인
import { useMutation } from "@tanstack/react-query";
import axios from "axios";

export function StripeConfirmButton({ order, paymentIntentId }) {
  const { mutate } = useMutation({
    mutationFn: async () => {
      // ❌ 문제 2: 검증 로직이 중복됨
      if (order.totalAmount < 10_000) {
        throw new Error("최소 결제 금액은 10,000원입니다");
      }

      // ❌ 문제 1: Stripe 엔드포인트가 컴포넌트에 박혀있음
      const response = await axios.post("/api/payments/stripe/confirm", {
        paymentIntentId, // 다른 필드명
        orderId: order.orderId,
        amount: order.totalAmount,
      });

      return response.data; // { id, amount, status: "succeeded", ... }
    },
    onSuccess: (data) => {
      // ❌ 문제 3: Stripe 응답 형식에 직접 의존 (필드명이 다름)
      alert(`결제 완료! 결제 ID: ${data.id}, 금액: ${data.amount}원`);
    },
  });

  return <button onClick={() => mutate()}>Stripe 결제 승인</button>;
}ts

// ❌ TossConfirmButton.tsx
await axios.post("/api/payments/toss/confirm", { ... });

// ❌ StripeConfirmButton.tsx
await axios.post("/api/payments/stripe/confirm", { ... });ts

// ❌ TossConfirmButton.tsx
if (order.totalAmount < 10_000)
  throw new Error("최소 결제 금액은 10,000원입니다");

// ❌ StripeConfirmButton.tsx
if (order.totalAmount < 10_000)
  throw new Error("최소 결제 금액은 10,000원입니다");ts

// ❌ TossConfirmButton.tsx
alert(`결제 키: ${data.paymentKey}, 금액: ${data.totalAmount}원`);

// ❌ StripeConfirmButton.tsx
alert(`결제 ID: ${data.id}, 금액: ${data.amount}원`);ts

// ❌ 훅으로만 분리하면 여전히 문제
async function confirmTossPayment(order, paymentKey) {
  if (order.totalAmount < MIN_AMOUNT) throw new Error(); // 검증 (Domain)

  const response = await axios.post(
    // API 호출 (Infrastructure)
    "/api/payments/toss/confirm",
    {
      paymentKey, // 토스 형식 (Data)
      orderId: order.orderId,
      amount: order.totalAmount,
    }
  );

  return response.data; // 토스 응답 형식 (Data)
}ts

┌─────────────────────────────────────────────────────────┐
│              Presentation Layer (React)                  │
│  Components, Pages, Hooks, State (Zustand + TanStack)   │
└────────────────────┬────────────────────────────────────┘
                     │ depends on
┌────────────────────▼────────────────────────────────────┐
│           Domain Layer (Business Logic)                  │
│     Use Cases, Entities, Repository Interfaces          │
└────────────────────▲────────────────────────────────────┘
                     │ implements
┌────────────────────┴────────────────────────────────────┐
│              Data Layer (API Access)                     │
│    Repository Impl, DTOs, Mappers, Data Sources         │
└────────────────────┬────────────────────────────────────┘
                     │ uses
┌────────────────────▼────────────────────────────────────┐
│         Infrastructure Layer (External Services)         │
│            HTTP Client (Axios), Storage                  │
└─────────────────────────────────────────────────────────┘

              Core Layer (Cross-cutting Concerns)
          Config, Constants, Utils, Errors, Validators
            ← 모든 레이어에서 참조 가능

Presentation → Domain ← Data ← Infrastructure
       ↓          ↓        ↓          ↓
                  DI (모든 레이어를 조합)
       ↓          ↓        ↓          ↓
              Core (모든 레이어가 의존 가능)

src/
├── di/
│   └── DIContainer.ts             # 의존성 주입 컨테이너
│
├── core/
│   ├── constants.ts               # 전역 상수
│   ├── utils/
│   │   └── formatters.ts          # 공통 포맷팅 함수
│   └── validators/
│       └── paymentValidator.ts    # 검증 유틸
│
├── infrastructure/
│   ├── http/
│   │   ├── httpClient.ts          # HTTP 클라이언트 추상화
│   │   └── axiosHttpClient.ts     # Axios 구현체
│   └── external/
│       └── analytics.ts            # 외부 라이브러리
│
├── data/
│   ├── datasources/
│   │   ├── remote/                # 서버 API 호출
│   │   │   ├── tossPaymentsDataSource.ts
│   │   │   └── stripeDataSource.ts
│   │   └── local/                 # 브라우저 저장소 (localStorage, sessionStorage)
│   │       ├── orderCacheDataSource.ts
│   │       ├── settingsDataSource.ts
│   │       └── cartDataSource.ts
│   ├── repositories/
│   │   └── PaymentRepositoryImpl.ts
│   ├── dto/
│   │   ├── tossPaymentDto.ts      # openapi-typescript로 자동 생성
│   │   └── stripePaymentDto.ts    # openapi-typescript로 자동 생성
│   └── mappers/
│       ├── tossPaymentMapper.ts
│       └── stripePaymentMapper.ts
│
├── domain/
│   ├── entities/
│   ├── repositories/
│   └── useCases/
│
└── presentation/
    ├── hooks/
    ├── components/
    └── adapters/

apps/web/src/
├── domains/                    # 도메인별 완전 독립
│   ├── auth/                   # 인증 도메인
│   │   ├── di/
│   │   │   └── container.ts
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   ├── repositories/
│   │   │   └── useCases/
│   │   ├── data/
│   │   │   ├── datasources/
│   │   │   │   ├── remote/
│   │   │   │   │   └── authDataSource.ts
│   │   │   │   └── local/
│   │   │   │       └── tokenDataSource.ts
│   │   │   ├── repositories/
│   │   │   ├── dto/
│   │   │   └── mappers/
│   │   └── presentation/
│   │       ├── hooks/
│   │       └── components/
│   │
│   ├── payment/                # 결제 도메인
│   │   ├── di/
│   │   ├── domain/
│   │   ├── data/
│   │   └── presentation/
│   │
│   ├── user/                   # 사용자 도메인
│   │   ├── di/
│   │   ├── domain/
│   │   ├── data/
│   │   └── presentation/
│   │
│   └── [other-domains]/
│
└── core/                       # 모든 도메인이 공유
    ├── infrastructure/         # HTTP, Storage 추상화
    │   ├── http/
    │   ├── storage/
    │   └── logging/
    ├── shared/                 # 도메인 독립적 공통 코드
    │   ├── constants.ts
    │   ├── utils/
    │   └── validators/
    └── ui/                     # 공통 UI 컴포넌트
        └── components/
            ├── Button.tsx
            └── Input.tsx

// core/constants.ts
export const MIN_PAYMENT_AMOUNT = 1_000; // 최소 결제 금액
export const MAX_PAYMENT_AMOUNT = 1_000_000; // 최대 결제 금액
export const CURRENCY_UNIT = "원"; // 통화 단위ts

// core/validators/paymentValidator.ts
import { MIN_PAYMENT_AMOUNT, MAX_PAYMENT_AMOUNT } from "../constants";

export const validatePaymentAmount = (amount: number): void => {
  if (amount < MIN_PAYMENT_AMOUNT) {
    throw new Error(`최소 결제 금액은 ${MIN_PAYMENT_AMOUNT}원입니다`);
  }
  if (amount > MAX_PAYMENT_AMOUNT) {
    throw new Error(`최대 결제 금액은 ${MAX_PAYMENT_AMOUNT}원입니다`);
  }
};ts

// core/utils/formatters.ts
export const formatCurrency = (amount: number): string => {
  return amount.toLocaleString("ko-KR");
};

export const formatPayment = (payment: number): string => {
  return `${formatCurrency(payment)}원`;
};ts

// infrastructure/http/httpClient.ts
export interface HttpClient {
  get<T>(url: string): Promise<T>;
  post<T>(url: string, data: unknown): Promise<T>;
  put<T>(url: string, data: unknown): Promise<T>;
  delete<T>(url: string): Promise<T>;
}ts

// infrastructure/http/axiosHttpClient.ts
import axios from "axios";
import type { HttpClient } from "./httpClient";

export class AxiosHttpClient implements HttpClient {
  async get<T>(url: string): Promise<T> {
    const response = await axios.get(url);
    return response.data;
  }

  async post<T>(url: string, data: unknown): Promise<T> {
    const response = await axios.post(url, data);
    return response.data;
  }

  // put, delete도 유사하게 구현
}ts

// infrastructure/http/fetchHttpClient.ts
import type { HttpClient } from "./httpClient";

export class FetchHttpClient implements HttpClient {
  async get<T>(url: string): Promise<T> {
    const response = await fetch(url);
    return response.json();
  }

  async post<T>(url: string, data: unknown): Promise<T> {
    const response = await fetch(url, {
      method: "POST",
      body: JSON.stringify(data),
      headers: { "Content-Type": "application/json" },
    });
    return response.json();
  }

  // put, delete도 유사하게 구현
}ts

// data/repositories/PaymentRepositoryImpl.ts
import type {
  PaymentRepository,
  ConfirmPaymentParams,
} from "@/domain/repositories/PaymentRepository";
import type { IPaymentDataSource } from "@/data/datasources/remote/IPaymentDataSource";
import type { Payment, PaymentGateway } from "@/domain/entities/Payment";
import { mapTossPaymentDtoToDomain } from "@/data/mappers/tossPaymentMapper";
import { mapStripePaymentDtoToDomain } from "@/data/mappers/stripePaymentMapper";

export class PaymentRepositoryImpl implements PaymentRepository {
  constructor(
    private tossDataSource: IPaymentDataSource,
    private stripeDataSource: IPaymentDataSource
  ) {}

  // 게이트웨이별 DataSource와 Mapper를 반환하는 헬퍼 메서드
  private getGatewayContext(gateway: PaymentGateway) {
    switch (gateway) {
      case "toss":
        return {
          dataSource: this.tossDataSource,
          mapper: mapTossPaymentDtoToDomain,
        };
      case "stripe":
        return {
          dataSource: this.stripeDataSource,
          mapper: mapStripePaymentDtoToDomain,
        };
      default:
        throw new Error(`지원하지 않는 결제 게이트웨이입니다: ${gateway}`);
    }
  }

  async confirmPayment(
    params: ConfirmPaymentParams,
    gateway: PaymentGateway
  ): Promise<Payment> {
    // 1. 게이트웨이에 맞는 DataSource와 Mapper 선택
    const { dataSource, mapper } = this.getGatewayContext(gateway);

    // 2. DataSource로 DTO 가져오기
    const paymentDto = await dataSource.confirmPayment(
      params.orderId,
      params.paymentKey,
      params.amount
    );

    // 3. Mapper로 Entity 변환
    return mapper(paymentDto);
  }

  async getPayment(
    paymentId: string,
    gateway: PaymentGateway
  ): Promise<Payment> {
    const { dataSource, mapper } = this.getGatewayContext(gateway);
    const paymentDto = await dataSource.getPayment(paymentId);
    return mapper(paymentDto);
  }

  async cancelPayment(
    paymentId: string,
    gateway: PaymentGateway,
    reason?: string
  ): Promise<Payment> {
    const { dataSource, mapper } = this.getGatewayContext(gateway);
    const paymentDto = await dataSource.cancelPayment(paymentId, reason);
    return mapper(paymentDto);
  }
}ts

// ❌ 나쁜 예시: Repository가 모든 것을 함
class PaymentRepositoryImpl {
  constructor(private httpClient: HttpClient) {}

  async confirmPayment(
    params: ConfirmPaymentParams,
    gateway: PaymentGateway
  ): Promise<Payment> {
    // ❌ API 엔드포인트를 직접 알아야 함
    const endpoint =
      gateway === "toss"
        ? "https://api.tosspayments.com/v1/payments/confirm"
        : "https://api.stripe.com/v1/payment_intents/confirm";

    // ❌ HTTP 호출도 직접
    const dto = await this.httpClient.post(endpoint, params);

    // ❌ 변환도 직접 (상태 매핑, 타입 변환 등)
    return new Payment({
      paymentId: dto.paymentKey || dto.id,
      status: dto.status === "DONE" ? "SUCCEEDED" : "PENDING",
      // ...
    });
  }
}ts

// ✅ 좋은 예시: 책임 분리
class PaymentRepositoryImpl {
  constructor(
    private tossDataSource: IPaymentDataSource,
    private stripeDataSource: IPaymentDataSource
  ) {} // HttpClient가 아닌 DataSource 주입

  private getGatewayContext(gateway: PaymentGateway) {
    switch (gateway) {
      case "toss":
        return {
          dataSource: this.tossDataSource,
          mapper: mapTossPaymentDtoToDomain,
        };
      case "stripe":
        return {
          dataSource: this.stripeDataSource,
          mapper: mapStripePaymentDtoToDomain,
        };
      default:
        throw new Error(`지원하지 않는 결제 게이트웨이입니다: ${gateway}`);
    }
  }

  async confirmPayment(
    params: ConfirmPaymentParams,
    gateway: PaymentGateway
  ): Promise<Payment> {
    const { dataSource, mapper } = this.getGatewayContext(gateway); // 게이트웨이별 선택

    const dto = await dataSource.confirmPayment(
      params.orderId,
      params.paymentKey,
      params.amount
    ); // DataSource가 HTTP 처리
    return mapper(dto); // Mapper가 변환 처리
  }
}ts

// data/datasources/remote/IPaymentDataSource.ts
import type { TossPaymentDto } from "@/data/dto/tossPaymentDto";
import type { StripePaymentDto } from "@/data/dto/stripePaymentDto";

export interface IPaymentDataSource {
  confirmPayment(
    orderId: string,
    paymentKey: string,
    amount: number
  ): Promise<TossPaymentDto | StripePaymentDto>;
  getPayment(paymentId: string): Promise<TossPaymentDto | StripePaymentDto>;
  cancelPayment(
    paymentId: string,
    reason?: string
  ): Promise<TossPaymentDto | StripePaymentDto>;
}ts

// data/datasources/remote/tossPaymentsDataSource.ts
import type { HttpClient } from "@/infrastructure/http/HttpClient";
import type { TossPaymentDto } from "@/data/dto/tossPaymentDto";
import type { IPaymentDataSource } from "./IPaymentDataSource";

export class TossPaymentsDataSource implements IPaymentDataSource {
  constructor(private httpClient: HttpClient) {}

  async confirmPayment(
    orderId: string,
    paymentKey: string,
    amount: number
  ): Promise<TossPaymentDto> {
    // 백엔드 API 호출
    return this.httpClient.post<TossPaymentDto>("/api/payments/toss/confirm", {
      paymentKey,
      orderId,
      amount,
    });
  }

  async getPayment(paymentKey: string): Promise<TossPaymentDto> {
    return this.httpClient.get<TossPaymentDto>(
      `/api/payments/toss/${paymentKey}`
    );
  }

  async cancelPayment(
    paymentKey: string,
    cancelReason?: string
  ): Promise<TossPaymentDto> {
    return this.httpClient.post<TossPaymentDto>(
      `/api/payments/toss/${paymentKey}/cancel`,
      {
        cancelReason,
      }
    );
  }
}ts

// data/datasources/remote/stripeDataSource.ts
import type { HttpClient } from "@/infrastructure/http/HttpClient";
import type { StripePaymentDto } from "@/data/dto/stripePaymentDto";
import type { IPaymentDataSource } from "./IPaymentDataSource";

export class StripeDataSource implements IPaymentDataSource {
  constructor(private httpClient: HttpClient) {}

  async confirmPayment(
    orderId: string,
    paymentIntentId: string,
    amount: number
  ): Promise<StripePaymentDto> {
    // 백엔드 API 호출
    return this.httpClient.post<StripePaymentDto>(
      "/api/payments/stripe/confirm",
      {
        paymentIntentId,
        orderId,
        amount,
      }
    );
  }

  async getPayment(paymentIntentId: string): Promise<StripePaymentDto> {
    return this.httpClient.get<StripePaymentDto>(
      `/api/payments/stripe/${paymentIntentId}`
    );
  }

  async cancelPayment(
    paymentIntentId: string,
    cancellationReason?: string
  ): Promise<StripePaymentDto> {
    return this.httpClient.post<StripePaymentDto>(
      `/api/payments/stripe/${paymentIntentId}/cancel`,
      {
        cancellationReason,
      }
    );
  }
}ts

// data/dto/tossPaymentDto.ts - 토스 페이먼츠 응답
export interface TossPaymentDto {
  paymentKey: string; // 토스에서 발급한 결제 고유 키
  orderId: string; // 주문 ID
  orderName: string; // 주문명
  status: "READY" | "IN_PROGRESS" | "DONE" | "CANCELED" | "ABORTED"; // 결제 상태
  method: "카드" | "가상계좌" | "간편결제" | "계좌이체"; // 결제 수단
  totalAmount: number; // 총 결제 금액 (원 단위)
  balanceAmount: number; // 취소 가능 금액
  currency: "KRW"; // 통화
  requestedAt: string; // 결제 요청 시각 (ISO 8601)
  approvedAt: string; // 결제 승인 시각 (ISO 8601)
  receipt?: {
    url: string; // 영수증 URL
  };
}

// data/dto/stripePaymentDto.ts - Stripe 응답
export interface StripePaymentDto {
  id: string; // Stripe에서 발급한 결제 ID
  amount: number; // 결제 금액 (센트 단위! 주의)
  currency: string; // 통화 (usd, krw 등)
  status: "requires_payment_method" | "processing" | "succeeded" | "canceled"; // 결제 상태
  payment_method: string | null; // 결제 수단 ID
  metadata: {
    orderId: string; // 주문 ID (메타데이터에 저장)
  };
  created: number; // 생성 시각 (Unix timestamp, 초 단위)
  canceled_at: number | null; // 취소 시각 (Unix timestamp)
  charges?: {
    data: Array<{
      receipt_url: string; // 영수증 URL
    }>;
  };
}ts

// data/dto/tossPaymentDto.ts (packages/types에서 re-export)
export type { TossPaymentDto } from "@/packages/types/generated/payment";

// data/dto/stripePaymentDto.ts
export type { StripePaymentDto } from "@/packages/types/generated/payment";ts

// OpenAPI가 없는 환경에서 명세 기반 DTO 정의
// data/dto/paymentDto.ts
export interface PaymentDto {
  paymentKey: string; // 노션 명세 v2.1 참조
  orderId: string;
  totalAmount: number;
  status: "DONE" | "CANCELED";
}ts

// data/dto/tossPaymentDto.ts
import { z } from "zod";

// Zod 스키마 정의
export const TossPaymentDtoSchema = z.object({
  paymentKey: z.string(),
  orderId: z.string(),
  status: z.enum(["READY", "IN_PROGRESS", "DONE", "CANCELED", "ABORTED"]),
  totalAmount: z.number().positive(),
  approvedAt: z.string().datetime(),
});

// 타입 추론
export type TossPaymentDto = z.infer<typeof TossPaymentDtoSchema>;

// data/datasources/remote/tossPaymentsDataSource.ts
import { TossPaymentDtoSchema } from "@/data/dto/tossPaymentDto";

export class TossPaymentsDataSource implements IPaymentDataSource {
  async confirmPayment(
    orderId: string,
    paymentKey: string,
    amount: number
  ): Promise<TossPaymentDto> {
    const response = await this.httpClient.post("/api/payments/toss/confirm", {
      paymentKey,
      orderId,
      amount,
    });

    // 런타임 검증 - 잘못된 데이터면 즉시 에러 발생
    return TossPaymentDtoSchema.parse(response);
  }
}ts

// data/mappers/tossPaymentMapper.ts
import { z } from "zod";
import {
  Payment,
  PaymentStatus,
  PaymentMethod,
} from "@/domain/entities/Payment";
import type { TossPaymentDto } from "@/data/dto/tossPaymentDto";

const tossPaymentDtoSchema = z.object({
  paymentKey: z.string(),
  orderId: z.string(),
  orderName: z.string(),
  status: z.enum(["READY", "IN_PROGRESS", "DONE", "CANCELED", "ABORTED"]),
  method: z.enum(["카드", "가상계좌", "간편결제", "계좌이체"]),
  totalAmount: z.number(),
  currency: z.literal("KRW"),
  requestedAt: z.string(),
  approvedAt: z.string().optional(),
  receipt: z.object({ url: z.string() }).optional(),
});

// 토스 상태 → 통합 상태로 매핑
function mapTossStatus(status: TossPaymentDto["status"]): PaymentStatus {
  const statusMap: Record<TossPaymentDto["status"], PaymentStatus> = {
    READY: "PENDING",
    IN_PROGRESS: "PROCESSING",
    DONE: "SUCCEEDED",
    CANCELED: "CANCELED",
    ABORTED: "FAILED",
  };
  return statusMap[status];
}

// 토스 결제수단 → 통합 결제수단으로 매핑
function mapTossMethod(method: TossPaymentDto["method"]): PaymentMethod {
  const methodMap: Record<TossPaymentDto["method"], PaymentMethod> = {
    카드: "CARD",
    가상계좌: "VIRTUAL_ACCOUNT",
    간편결제: "EASY_PAY",
    계좌이체: "TRANSFER",
  };
  return methodMap[method];
}

export function mapTossPaymentDtoToDomain(dto: TossPaymentDto): Payment {
  const validated = tossPaymentDtoSchema.parse(dto);

  return new Payment({
    paymentId: `toss_${validated.paymentKey}`, // 내부 ID 생성
    orderId: validated.orderId,
    gateway: "toss",
    gatewayPaymentId: validated.paymentKey,
    amount: validated.totalAmount, // 원 단위 그대로
    currency: validated.currency,
    status: mapTossStatus(validated.status),
    method: mapTossMethod(validated.method),
    requestedAt: new Date(validated.requestedAt), // ISO 8601 → Date
    approvedAt: validated.approvedAt
      ? new Date(validated.approvedAt)
      : undefined,
    receiptUrl: validated.receipt?.url,
  });
}ts

// data/mappers/stripePaymentMapper.ts
import { z } from "zod";
import { Payment, PaymentStatus } from "@/domain/entities/Payment";
import type { StripePaymentDto } from "@/data/dto/stripePaymentDto";

const stripePaymentDtoSchema = z.object({
  id: z.string(),
  amount: z.number(),
  currency: z.string(),
  status: z.enum([
    "requires_payment_method",
    "processing",
    "succeeded",
    "canceled",
  ]),
  payment_method: z.string().nullable(),
  metadata: z.object({
    orderId: z.string(),
  }),
  created: z.number(),
  canceled_at: z.number().nullable(),
  charges: z
    .object({
      data: z.array(z.object({ receipt_url: z.string() })),
    })
    .optional(),
});

// Stripe 상태 → 통합 상태로 매핑
function mapStripeStatus(status: StripePaymentDto["status"]): PaymentStatus {
  const statusMap: Record<StripePaymentDto["status"], PaymentStatus> = {
    requires_payment_method: "PENDING",
    processing: "PROCESSING",
    succeeded: "SUCCEEDED",
    canceled: "CANCELED",
  };
  return statusMap[status];
}

export function mapStripePaymentDtoToDomain(dto: StripePaymentDto): Payment {
  const validated = stripePaymentDtoSchema.parse(dto);

  return new Payment({
    paymentId: `stripe_${validated.id}`, // 내부 ID 생성
    orderId: validated.metadata.orderId, // metadata에서 추출
    gateway: "stripe",
    gatewayPaymentId: validated.id,
    amount: validated.amount, // 센트 단위 그대로 (currency로 구분)
    currency: validated.currency.toUpperCase(),
    status: mapStripeStatus(validated.status),
    method: validated.payment_method ? "CARD" : undefined, // Stripe는 카드 결제만 지원
    requestedAt: new Date(validated.created * 1000), // Unix timestamp → Date (밀리초 변환)
    approvedAt:
      validated.status === "succeeded"
        ? new Date(validated.created * 1000)
        : undefined,
    canceledAt: validated.canceled_at
      ? new Date(validated.canceled_at * 1000)
      : undefined,
    receiptUrl: validated.charges?.data[0]?.receipt_url, // charges 배열에서 추출
  });
}ts

// ✅ TossPaymentMapper 한 곳만 수정
export function mapTossPaymentDtoToDomain(dto: TossPaymentDto): Payment {
  return new Payment({
-   gatewayPaymentId: validated.paymentKey,  // 기존
+   gatewayPaymentId: validated.paymentId,   // 변경
    // ...
  });
}ts

// ✅ StripePaymentMapper의 상태 매핑만 수정
function mapStripeStatus(status: StripePaymentDto["status"]): PaymentStatus {
  const statusMap = {
-   succeeded: "SUCCEEDED",        // 기존
+   payment_successful: "SUCCEEDED", // 변경
    // ...
  };
}ts

// 백엔드: Entity가 상태를 직접 변경
class Payment {
  private _status: PaymentStatus;

  approve() {
    this._status = "SUCCEEDED"; // ✅ Entity가 상태 변경
    this.save(); // DB에 저장
  }
}ts

// 프론트엔드: Entity는 검증만
class Payment {
  private readonly _status: PaymentStatus;

  canCancel(): boolean {
    return this._status === "PENDING"; // ✅ 검증만
  }
}ts

// ❌ Entity가 상태를 직접 변경하면?
class Payment {
  private _status: PaymentStatus;

  confirm() {
    this._status = "SUCCEEDED"; // Entity가 상태 변경
  }
}

// 문제: TanStack Query 캐시와 Entity 상태가 따로 논다!
// - Entity: _status = "SUCCEEDED"
// - TanStack Query 캐시: status = "PENDING"
// 어느 것이 진짜인가?ts

// domain/entities/Order.ts
export type OrderStatus = "PENDING" | "PAID" | "FAILED" | "CANCELED";

interface OrderItem {
  productId: string;
  productName: string;
  quantity: number;
  price: number;
}

interface OrderProps {
  orderId: string;
  orderName: string; // "아메리카노 외 2건" 같은 주문 요약
  userId: string;
  items: OrderItem[];
  totalAmount: number;
  status: OrderStatus;
  createdAt: Date;
  updatedAt: Date;
}

export class Order {
  private readonly _orderId: string;
  private readonly _orderName: string;
  private readonly _userId: string;
  private readonly _items: readonly OrderItem[];
  private readonly _totalAmount: number;
  private readonly _status: OrderStatus;
  private readonly _createdAt: Date;
  private readonly _updatedAt: Date;

  static readonly MIN_ORDER_AMOUNT = 1_000; // 최소 주문 금액
  static readonly MAX_ORDER_AMOUNT = 10_000_000; // 최대 주문 금액

  constructor(props: OrderProps) {
    this._orderId = props.orderId;
    this._orderName = props.orderName;
    this._userId = props.userId;
    this._items = Object.freeze([...props.items]);
    this._totalAmount = props.totalAmount;
    this._status = props.status;
    this._createdAt = props.createdAt;
    this._updatedAt = props.updatedAt;

    // 생성 시점에 필수 검증 수행
    this.validate();
  }

  private validate(): void {
    if (!this._orderId?.trim()) throw new Error("주문 ID는 필수입니다");
    if (!this._orderName?.trim()) throw new Error("주문명은 필수입니다");
    if (!this._userId?.trim()) throw new Error("사용자 ID는 필수입니다");
    if (this._items.length === 0) throw new Error("주문 상품이 없습니다");
    if (this._totalAmount < 0)
      throw new Error("주문 금액은 음수일 수 없습니다");
  }

  get orderId() {
    return this._orderId;
  }
  get orderName() {
    return this._orderName;
  }
  get userId() {
    return this._userId;
  }
  get items() {
    return this._items;
  }
  get totalAmount() {
    return this._totalAmount;
  }
  get status() {
    return this._status;
  }
  get createdAt() {
    return this._createdAt;
  }
  get updatedAt() {
    return this._updatedAt;
  }

  // 비즈니스 규칙: 주문 금액 검증
  static validateOrderAmount(amount: number): void {
    if (amount < this.MIN_ORDER_AMOUNT) {
      throw new Error(`최소 주문 금액은 ${this.MIN_ORDER_AMOUNT}원입니다`);
    }
    if (amount > this.MAX_ORDER_AMOUNT) {
      throw new Error(`최대 주문 금액은 ${this.MAX_ORDER_AMOUNT}원입니다`);
    }
  }

  // 비즈니스 규칙: 결제 가능 여부 확인
  canProcessPayment(): boolean {
    return this._status === "PENDING" && this._totalAmount > 0;
  }

  // 비즈니스 규칙: 취소 가능 여부 확인
  canCancel(): boolean {
    return this._status === "PENDING" || this._status === "PAID";
  }
}ts

class Order {
  // 비즈니스 규칙: 결제 가능 여부
  canProcessPayment(): boolean {
    return this._status === "PENDING" && this._totalAmount > 0;
  }

  // 비즈니스 규칙: 취소 가능 여부
  canCancel(): boolean {
    return this._status === "PENDING" || this._status === "PAID";
  }

  // 비즈니스 규칙: 최소 수량 충족 여부
  hasMinimumQuantity(minQty: number): boolean {
    const total = this.items.reduce((sum, item) => sum + item.quantity, 0);
    return total >= minQty;
  }
}ts

class Order {
  // ❌ 계산 메서드 - Presentation Layer에서 처리해야 함
  getTotalQuantity(): number {
    return this.items.reduce((sum, item) => sum + item.quantity, 0);
  }

  // ❌ 계산 메서드 - UseCase에서 처리해야 함
  calculateTax(): number {
    return this.totalAmount * 0.1;
  }

  // ❌ 포매팅 메서드 - Presentation Layer에서 처리해야 함
  formatOrderName(): string {
    return `${this.orderName} (${this.items.length}건)`;
  }
}ts

// domain/entities/Payment.ts
export type PaymentGateway = "toss" | "stripe";
export type PaymentStatus =
  | "PENDING"
  | "PROCESSING"
  | "SUCCEEDED"
  | "FAILED"
  | "CANCELED";
export type PaymentMethod =
  | "CARD"
  | "VIRTUAL_ACCOUNT"
  | "EASY_PAY"
  | "TRANSFER";

interface PaymentProps {
  paymentId: string; // 결제 고유 ID
  orderId: string; // 연결된 주문 ID
  gateway: PaymentGateway; // 결제 게이트웨이 (toss 또는 stripe)
  gatewayPaymentId: string; // 게이트웨이에서 발급한 결제 ID (토스의 paymentKey, Stripe의 id)
  amount: number; // 결제 금액 (원 단위로 정규화)
  currency: string; // 통화 (KRW, USD 등)
  status: PaymentStatus; // 결제 상태
  method?: PaymentMethod; // 결제 수단
  requestedAt: Date; // 결제 요청 시각
  approvedAt?: Date; // 결제 승인 시각
  canceledAt?: Date; // 결제 취소 시각
  receiptUrl?: string; // 영수증 URL
}

export class Payment {
  private readonly _paymentId: string;
  private readonly _orderId: string;
  private readonly _gateway: PaymentGateway;
  private readonly _gatewayPaymentId: string;
  private readonly _amount: number;
  private readonly _currency: string;
  private readonly _status: PaymentStatus;
  private readonly _method?: PaymentMethod;
  private readonly _requestedAt: Date;
  private readonly _approvedAt?: Date;
  private readonly _canceledAt?: Date;
  private readonly _receiptUrl?: string;

  constructor(props: PaymentProps) {
    this._paymentId = props.paymentId;
    this._orderId = props.orderId;
    this._gateway = props.gateway;
    this._gatewayPaymentId = props.gatewayPaymentId;
    this._amount = props.amount;
    this._currency = props.currency;
    this._status = props.status;
    this._method = props.method;
    this._requestedAt = props.requestedAt;
    this._approvedAt = props.approvedAt;
    this._canceledAt = props.canceledAt;
    this._receiptUrl = props.receiptUrl;

    this.validate();
  }

  private validate(): void {
    if (!this._paymentId?.trim()) throw new Error("결제 ID는 필수입니다");
    if (!this._orderId?.trim()) throw new Error("주문 ID는 필수입니다");
    if (this._amount < 0) throw new Error("결제 금액은 음수일 수 없습니다");
  }

  get paymentId() {
    return this._paymentId;
  }
  get orderId() {
    return this._orderId;
  }
  get gateway() {
    return this._gateway;
  }
  get gatewayPaymentId() {
    return this._gatewayPaymentId;
  }
  get amount() {
    return this._amount;
  }
  get currency() {
    return this._currency;
  }
  get status() {
    return this._status;
  }
  get method() {
    return this._method;
  }
  get requestedAt() {
    return this._requestedAt;
  }
  get approvedAt() {
    return this._approvedAt;
  }
  get canceledAt() {
    return this._canceledAt;
  }
  get receiptUrl() {
    return this._receiptUrl;
  }

  // 비즈니스 규칙: 결제 성공 여부
  isSucceeded(): boolean {
    return this._status === "SUCCEEDED";
  }

  // 비즈니스 규칙: 결제 취소 가능 여부
  canCancel(): boolean {
    return this._status === "SUCCEEDED" || this._status === "PENDING";
  }

  // 비즈니스 규칙: 결제 재시도 가능 여부
  canRetry(): boolean {
    return this._status === "FAILED";
  }
}ts

// domain/entities/Order.ts
- static readonly MIN_ORDER_AMOUNT = 1_000;
+ static readonly MIN_ORDER_AMOUNT = 2_000;diff

// domain/repositories/PaymentRepository.ts
import type { Payment } from "@/domain/entities/Payment";
import type { PaymentGateway } from "@/domain/entities/Payment";

export interface ConfirmPaymentParams {
  orderId: string;
  paymentKey: string; // 토스 결제 승인용
  amount: number;
}

export interface PaymentRepository {
  confirmPayment(
    params: ConfirmPaymentParams,
    gateway: PaymentGateway
  ): Promise<Payment>;
  getPayment(paymentId: string, gateway: PaymentGateway): Promise<Payment>;
  cancelPayment(
    paymentId: string,
    gateway: PaymentGateway,
    reason?: string
  ): Promise<Payment>;
}ts

// domain/useCases/confirmPayment.ts
import { Order } from "@/domain/entities/Order";
import { Payment, PaymentGateway } from "@/domain/entities/Payment";
import type {
  PaymentRepository,
  ConfirmPaymentParams,
} from "@/domain/repositories/PaymentRepository";

export class ConfirmPaymentUseCase {
  constructor(private paymentRepository: PaymentRepository) {}

  async execute(
    order: Order,
    params: ConfirmPaymentParams,
    gateway: PaymentGateway
  ): Promise<Payment> {
    // 1. 입력값 검증
    Order.validateOrderAmount(params.amount);

    if (!order.canProcessPayment()) {
      throw new Error("결제할 수 없는 주문 상태입니다");
    }

    if (order.totalAmount !== params.amount) {
      throw new Error("주문 금액과 결제 금액이 일치하지 않습니다");
    }

    // 2. Repository 호출 (게이트웨이에 결제 승인 요청)
    const payment = await this.paymentRepository.confirmPayment(
      params,
      gateway
    );

    // 3. 결제 성공 확인
    if (!payment.isSucceeded()) {
      throw new Error("결제 승인에 실패했습니다");
    }

    return payment;
  }
}ts

// domain/useCases/cancelPayment.ts
import { Payment, PaymentGateway } from "@/domain/entities/Payment";
import type { PaymentRepository } from "@/domain/repositories/PaymentRepository";

export class CancelPaymentUseCase {
  constructor(private paymentRepository: PaymentRepository) {}

  async execute(
    payment: Payment,
    gateway: PaymentGateway,
    cancelReason?: string
  ): Promise<Payment> {
    // 1. 취소 가능 여부 검증
    if (!payment.canCancel()) {
      throw new Error("취소할 수 없는 결제 상태입니다");
    }

    // 2. Repository 호출 (게이트웨이에 취소 요청)
    const canceledPayment = await this.paymentRepository.cancelPayment(
      payment.paymentId,
      gateway,
      cancelReason
    );

    // 3. 취소 성공 확인
    if (canceledPayment.status !== "CANCELED") {
      throw new Error("결제 취소에 실패했습니다");
    }

    return canceledPayment;
  }
}ts

// di/DIContainer.ts
import { AxiosHttpClient } from "@/infrastructure/http/AxiosHttpClient";
import { TossPaymentsDataSource } from "@/data/datasources/remote/tossPaymentsDataSource";
import { StripeDataSource } from "@/data/datasources/remote/stripeDataSource";
import { PaymentRepositoryImpl } from "@/data/repositories/PaymentRepositoryImpl";
import { ConfirmPaymentUseCase } from "@/domain/useCases/confirmPayment";
import { CancelPaymentUseCase } from "@/domain/useCases/cancelPayment";
import type { PaymentRepository } from "@/domain/repositories/PaymentRepository";
import type { HttpClient } from "@/infrastructure/http/HttpClient";

class DIContainer {
  private static _httpClient: HttpClient;
  private static _tossDataSource: TossPaymentsDataSource;
  private static _stripeDataSource: StripeDataSource;
  private static _paymentRepository: PaymentRepository;

  static get httpClient() {
    return (this._httpClient ??= new AxiosHttpClient({
      timeout: 10_000,
    }));
  }

  static get tossDataSource() {
    return (this._tossDataSource ??= new TossPaymentsDataSource(
      this.httpClient
    ));
  }

  static get stripeDataSource() {
    return (this._stripeDataSource ??= new StripeDataSource(this.httpClient));
  }

  static get paymentRepository() {
    return (this._paymentRepository ??= new PaymentRepositoryImpl(
      this.tossDataSource,
      this.stripeDataSource
    ));
  }

  // UseCases (매번 새로 생성)
  static get confirmPaymentUseCase() {
    return new ConfirmPaymentUseCase(this.paymentRepository);
  }

  static get cancelPaymentUseCase() {
    return new CancelPaymentUseCase(this.paymentRepository);
  }

  // 테스트용
  static setMockRepositories(paymentRepo: PaymentRepository) {
    this._paymentRepository = paymentRepo;
  }
}

export default DIContainer;ts

// ❌ 안티패턴: 컴포넌트마다 인스턴스 생성
function useConfirmPayment() {
  const httpClient = new AxiosHttpClient({ ... });  // 인스턴스 1
  const tossDataSource = new TossPaymentsDataSource(httpClient);
  const stripeDataSource = new StripeDataSource(httpClient);
  const repository = new PaymentRepositoryImpl(tossDataSource, stripeDataSource);
  const useCase = new ConfirmPaymentUseCase(repository);
  // ...
}

function useCancelPayment() {
  const httpClient = new AxiosHttpClient({ ... });  // 인스턴스 2 (중복!)
  const tossDataSource = new TossPaymentsDataSource(httpClient);  // 중복!
  const stripeDataSource = new StripeDataSource(httpClient);  // 중복!
  const repository = new PaymentRepositoryImpl(tossDataSource, stripeDataSource);
  const useCase = new CancelPaymentUseCase(repository);
  // ...
}

// 문제: HttpClient, DataSource가 Hook마다 생성됨
// - 10개 Hook → HttpClient 10개, TossDataSource 10개, StripeDataSource 10개ts

// ✅ DI Container: 싱글톤으로 1번만 생성
static get httpClient() {
  return (this._httpClient ??= new AxiosHttpClient({ ... }));
  // _httpClient가 없으면 생성, 있으면 기존 것 재사용
}ts

// di/DIContainer.ts
class DIContainer {
  private static _httpClient: HttpClient;
  private static _tossDataSource: TossPaymentsDataSource;
  private static _stripeDataSource: StripeDataSource;
  private static _paymentRepository: PaymentRepository;

  static get httpClient() {
    return (this._httpClient ??= new AxiosHttpClient({
      baseURL: import.meta.env.VITE_API_URL,
      timeout: 10_000,
    }));
  }

  static get tossDataSource() {
    return (this._tossDataSource ??= new TossPaymentsDataSource(
      this.httpClient
    ));
  }

  static get stripeDataSource() {
    return (this._stripeDataSource ??= new StripeDataSource(this.httpClient));
  }

  static get paymentRepository() {
    return (this._paymentRepository ??= new PaymentRepositoryImpl(
      this.tossDataSource,
      this.stripeDataSource
    ));
  }

  // 모든 의존성을 수동으로 작성해야 함...
}ts

// di/container.ts
import { createContainer, asClass } from "awilix";
import { AxiosHttpClient } from "@/infrastructure/http/axiosHttpClient";
import { TossPaymentsDataSource } from "@/data/datasources/remote/tossPaymentsDataSource";
import { StripeDataSource } from "@/data/datasources/remote/stripeDataSource";
import { PaymentRepositoryImpl } from "@/data/repositories/PaymentRepositoryImpl";
import { ConfirmPaymentUseCase } from "@/domain/useCases/confirmPayment";
import { CancelPaymentUseCase } from "@/domain/useCases/cancelPayment";

const container = createContainer();

container.register({
  // Infrastructure
  httpClient: asClass(AxiosHttpClient).singleton(),

  // DataSources
  tossDataSource: asClass(TossPaymentsDataSource).singleton(),
  stripeDataSource: asClass(StripeDataSource).singleton(),

  // Repositories
  paymentRepository: asClass(PaymentRepositoryImpl).singleton(),

  // UseCases (매번 새로 생성)
  confirmPaymentUseCase: asClass(ConfirmPaymentUseCase).scoped(),
  cancelPaymentUseCase: asClass(CancelPaymentUseCase).scoped(),
});

export default container;ts

// 사용: presentation/hooks/useConfirmPayment.ts
import container from "@/di/container";

export function useConfirmPayment() {
  return useMutation<Payment, Error, ConfirmPaymentParams>({
    mutationFn: async ({ order, paymentKey, gateway }) => {
      // Awilix가 자동으로 의존성 주입
      const confirmPaymentUseCase = container.resolve("confirmPaymentUseCase");
      return await confirmPaymentUseCase.execute(
        order,
        { orderId: order.orderId, paymentKey, amount: order.totalAmount },
        gateway
      );
    },
  });
}ts

// presentation/hooks/useConfirmPayment.ts
import { useMutation } from "@tanstack/react-query";
import DIContainer from "@/di/DIContainer";
import type { Order } from "@/domain/entities/Order";
import type { Payment, PaymentGateway } from "@/domain/entities/Payment";

interface ConfirmPaymentParams {
  order: Order;
  paymentKey: string;
  gateway: PaymentGateway;
}

export function useConfirmPayment() {
  return useMutation<Payment, Error, ConfirmPaymentParams>({
    mutationFn: async ({ order, paymentKey, gateway }) => {
      // DI Container에서 UseCase를 가져온다
      const confirmPaymentUseCase = DIContainer.confirmPaymentUseCase;

      return await confirmPaymentUseCase.execute(
        order,
        {
          orderId: order.orderId,
          paymentKey,
          amount: order.totalAmount,
        },
        gateway
      );
    },
  });
}ts

// presentation/components/CheckoutButton.tsx
import { useConfirmPayment } from "@/presentation/hooks/useConfirmPayment";
import type { Order } from "@/domain/entities/Order";
import type { PaymentGateway } from "@/domain/entities/Payment";

interface CheckoutButtonProps {
  order: Order;
  paymentKey: string;
  gateway: PaymentGateway;
}

export function CheckoutButton({
  order,
  paymentKey,
  gateway,
}: CheckoutButtonProps) {
  const { mutate, isPending, error } = useConfirmPayment();

  const handleConfirm = () => {
    mutate(
      { order, paymentKey, gateway },
      {
        onSuccess: (payment) => {
          alert(`결제 승인 완료! 주문번호: ${payment.orderId}`);
        },
      }
    );
  };

  return (
    <div>
      <button
        onClick={handleConfirm}
        disabled={isPending || !order.canProcessPayment()}
      >
        {isPending
          ? "결제 승인 중..."
          : `${gateway === "toss" ? "토스" : "Stripe"} 결제 승인`}
      </button>
      {error && <p style={{ color: "red" }}>{error.message}</p>}
    </div>
  );
}ts

CheckoutButton (Component)
  → useConfirmPayment (Hook)
    → DIContainer.confirmPaymentUseCase (DI Container)
      → ConfirmPaymentUseCase (UseCase)
        → PaymentRepository (Repository)
          → TossDataSource / StripeDataSource (DataSource)
            → HttpClient (Infrastructure)

// ❌ 나쁜 예시: 컴포넌트 내부에서 생성
function ConfirmButton({ order, paymentKey, gateway }: Props) {
  // 컴포넌트 안에서 직접 생성
  const httpClient = new AxiosHttpClient();
  const tossDataSource = new TossPaymentsDataSource(httpClient);
  const stripeDataSource = new StripeDataSource(httpClient);
  const paymentRepo = new PaymentRepositoryImpl(
    tossDataSource,
    stripeDataSource
  );
  const useCase = new ConfirmPaymentUseCase(paymentRepo);

  const handleConfirm = async () => {
    await useCase.execute(
      order,
      { orderId: order.orderId, paymentKey, amount: order.totalAmount },
      gateway
    );
  };
  // ...
}

// 문제점:
// 1. 실제 토스/Stripe API를 호출함 (테스트가 느리고 불안정)
// 2. Mock으로 바꿀 방법이 없음
// 3. 네트워크 없으면 테스트 실패ts