경계와 인터페이스

// 패키지·파일 경계
import { PaymentSummary } from '@/widgets/payment-summary/ui/PaymentSummary'
 
function CheckoutPage({ orderId }: { orderId: string }) {
  // 훅 호출 경계
  const { data: order } = useOrder(orderId)
  // 함수 호출 경계
  const total = calcOrderTotal(order.items)
  // 컴포넌트 경계
  return <PaymentSummary order={order} total={total} />
}

// 함수의 매개변수와 반환 타입
function calcOrderTotal(items: OrderItem[]): Money
 
// 훅의 인자와 반환 타입
function usePaymentMethods(userId: string): { methods: PaymentMethod[]; isLoading: boolean }
 
// JSX의 구조화된 형식
type PaymentSummaryProps = { order: Order; total: Money }
 
// Context Provider의 props 타입
type PaymentGatewayProviderProps = { gateway: PaymentGateway; children: ReactNode }

function CheckoutPage({ order }: { order: Order }) {
  const payable = order.total + Math.round(order.total * 0.1)
  return <button onClick={() => capture(order.payment.id, payable)}>{payable}원 결제</button>
}

// apps/checkout/CheckoutPage.tsx
const total = order.items.reduce((sum, i) => sum + i.price * i.qty, 0)
const discount = order.coupon ? Math.floor(total * order.coupon.rate) : 0
const payable = total - discount + Math.round((total - discount) * 0.1)
 
// apps/admin/RepaymentModal.tsx — 복사한 뒤 따로 자랐다
const total = order.items.reduce((sum, i) => sum + i.price * i.qty, 0)
const discount = order.coupon ? Math.floor(total * order.coupon.rate) : 0
// 여기에만 추가된 검사
const isCouponValid = new Date(order.coupon?.expiresAt ?? 0) > new Date()
// 세금 기준액이 다르다
const payable = total - (isCouponValid ? discount : 0) + Math.round(total * 0.1)

export function getPaymentView(dto: PaymentDto, isAdmin: boolean, locale: string) {
  const status = dto.status === 'CAPTURED' && dto.refundedAmount ? 'PARTIAL_REFUND' : dto.status
  const label = isAdmin ? ADMIN_LABEL[status] : (USER_LABEL[status] ?? dto.statusText)
 
  return {
    label: locale === 'ko' ? label : translate(label, locale),
    amount: formatCurrency(Number(dto.amount), dto.currency),
    gatewayCode: isAdmin ? dto.gatewayResultCode : undefined,
    // 환불 정책
    canRefund: isAdmin && dto.status === 'CAPTURED' && !dto.settledAt,
  }
}

vi.mock('@/lib/session', () => ({ useSession: () => ({ user: { role: 'ADMIN' } }) }))
vi.mock('@/lib/featureFlag', () => ({ useFlag: () => true }))
vi.mock('@/lib/analytics')
 
it('부분 환불이면 배지를 보여준다', async () => {
  server.use(http.get('/api/orders/:id', () => HttpResponse.json(orderFixture)))
  render(<CheckoutPage orderId="o1" />)
  expect(await screen.findByText('부분 환불')).toBeInTheDocument()
})

const onPay = async () => {
  const res = await capture(order.payment.id, payable)
 
  // 감사 로그
  if (session.user.role === 'ADMIN') void logAudit({ orderId: order.id, payable })
  // 전환 지표
  track('payment_captured', { variant: flags.checkoutVariant, payable })
  // 실패 건 재처리
  if (!res.ok) await enqueueSettlementRetry(order.id, res.status)
  // 실패 사유 노출
  if (!res.ok) setError(FAILURE_MESSAGE[res.body?.code] ?? '결제에 실패했습니다')
}

// payment.ts
import { isOrderCompleted } from './order'
 
export function canRefund(payment: Payment) {
  return payment.status === 'captured' && isOrderCompleted(payment.orderId)
}
 
// order.ts
import { isPaymentSettled } from './payment' // 순환
 
export function isOrderCompleted(orderId: string) {
  return isPaymentSettled(orderId)
}

// widgets(변하기 쉬움)가 entities(변하기 어려움)를 의존한다
import { listPayments } from '@/entities/payment/api/listPayments'
 
// 역방향은 금지. entities가 불필요하게 UI를 알게 된다
import { PaymentSummary } from '@/widgets/payment-summary/ui/PaymentSummary'

// entities/payment — 도메인이 필요한 능력만 선언한다
export type PaymentGateway = {
  authorize(req: { orderId: string; amount: Money; idempotencyKey: string }): Promise<AuthorizeResult>
  capture(req: { paymentId: string; amount: Money; idempotencyKey: string }): Promise<CaptureResult>
}
 
export function createPaymentService(gateway: PaymentGateway) {
  return {
    authorize: (order: Order) =>
      gateway.authorize({
        orderId: order.id,
        amount: calcOrderTotal(order.items),
        idempotencyKey: `authorize:${order.id}:${order.revision}`,
      }),
 
    // 승인된 결제만 받는다. 멱등키는 도메인이 만든다.
    capture: (payment: AuthorizedPayment, amount: Money) =>
      gateway.capture({
        paymentId: payment.id,
        amount,
        idempotencyKey: `capture:${payment.id}:${amount.value}`,
      }),
  }
}
 
// app — PG SDK를 포트 모양에 맞춘 어댑터로 주입한다
const paymentService = createPaymentService(createTossGateway(tossSdk))

// 오염된 하위 모듈 — 화면 이름으로 분기한다
export function listPayments(params: PaymentListParams, from: 'admin' | 'checkout') {
  if (from === 'admin') {
    return client.get('payments', {
      ...params,
      statuses: ['CAPTURED', 'FAILED', 'REFUNDED'],
      size: 100,
    })
  }
  return client.get('payments', {
    ...params,
    statuses: ['CAPTURED'],
    size: 20,
    // 전역에서 로그인 사용자까지 꺼내 쓴다
    payerId: currentUser.id,
  })
}

// entities/payment — 질의 능력만 제공한다
export type PaymentQuery = {
  status?: PaymentStatus[]
  payerId?: UserId
  period?: DateRange
  page: { size: number; cursor?: string }
}
 
export function listPayments(query: PaymentQuery): Promise<Page<Payment>> {
  return client.get('payments', serializeQuery(query)).then(toPaymentPage)
}

// widgets/settlement-table — 정산 화면이 자기 정책을 조합한다
const settlements = usePaymentList({
  status: ['captured', 'refunded'],
  period: thisMonth(),
  page: { size: 100 },
})
 
// widgets/payment-history — 결제 이력은 본인 것만
const history = usePaymentList({
  payerId: me.id,
  status: ['captured'],
  page: { size: 20 },
})

// 서버 응답 — 상태와 필드의 관계가 타입에 없다
type PaymentResponse = {
  id: string
  status: 'PENDING' | 'AUTHORIZED' | 'CAPTURED' | 'FAILED'
  amount: string // 최소 단위 문자열
  currency: 'KRW' | 'USD'
  authorizedAt?: string
  capturedAmount?: string
  failureCode?: string
}

type Money = { value: number; currency: 'KRW' | 'USD' } // value는 최소 단위 정수
 
type Payment =
  | { id: string; status: 'pending'; amount: Money }
  | { id: string; status: 'authorized'; amount: Money; authorizedAt: Date }
  | { id: string; status: 'captured'; amount: Money; captured: Money }
  | { id: string; status: 'failed'; amount: Money; failureCode: PaymentFailureCode }
 
type AuthorizedPayment = Extract<Payment, { status: 'authorized' }>
 
const responseSchema = z.object({ /* PaymentResponse와 같은 형태 */ })
 
const PaymentSchema = responseSchema.transform((res, ctx): Payment => {
  const amount = toMoney(res.amount, res.currency)
 
  switch (res.status) {
    case 'PENDING':
      return { id: res.id, status: 'pending', amount }
    case 'AUTHORIZED':
      if (!res.authorizedAt) {
        // 계약 위반은 경계에서 끝낸다
        ctx.addIssue({ code: 'custom', message: 'AUTHORIZED 응답에 authorizedAt이 없다' })
        return z.NEVER
      }
      return { id: res.id, status: 'authorized', amount, authorizedAt: new Date(res.authorizedAt) }
    default:
      return toSettledPayment(res, amount) // CAPTURED · FAILED
  }
})

// 변환이 없으면 사용처마다 방어 분기가 붙는다
if (res.status === 'AUTHORIZED' && res.authorizedAt) show(new Date(res.authorizedAt))
 
// 변환 후 — 존재가 타입으로 보장된다
if (payment.status === 'authorized') show(payment.authorizedAt)

// entities/payment/api/getPayment.ts
 
const PaymentSchema = /* ... */ // 스키마와 파서는 내보내지 않는다
 
export function getPayment(id: string): Promise<Payment> {
  return client.get(`payments/${id}`).then((res) => PaymentSchema.parse(res))
}

// entities/payment — 읽기만
export function usePaymentList(query: PaymentQuery) {
  return useQuery({ queryKey: paymentKeys.list(query), queryFn: () => listPayments(query) })
}
 
// features/payment-capture — 쓰기만. 캐시 무효화가 여기서 끝난다.
export function useCapturePayment(payment: AuthorizedPayment) {
  const paymentService = usePaymentService() // app에서 주입한 인스턴스
  const queryClient = useQueryClient()
 
  return useMutation({
    mutationFn: (amount: Money) => paymentService.capture(payment, amount),
    retry: 3, // 멱등키가 도메인에 있으므로 같은 키로 재시도된다
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: paymentKeys.detail(payment.id) })
      queryClient.invalidateQueries({ queryKey: paymentKeys.list() })
    },
  })
}

// dependency-cruiser — 레이어 순서 하나에서 규칙을 만든다
const layers = ['app', 'widgets', 'features', 'entities', 'shared']
 
forbidden: [
  ...layers.slice(1).map((layer, i) => ({
    name: `no-upward-import:${layer}`,
    from: { path: `^src/${layer}/` },
    to: { path: `^src/(${layers.slice(0, i + 1).join('|')})/` }, // 자기보다 위 레이어
  })),
  {
    name: 'no-sibling-import',
    from: { path: '^src/[^/]+/(?<slice>[^/]+)/' },
    to: { path: '^src/[^/]+/(?<slice>[^/]+)/', pathNot: '^src/[^/]+/$<slice>/' },
  },
  { name: 'no-circular', severity: 'error', from: {}, to: { circular: true } },
]