commerce 모듈

책임: 수강 신청서 제출, 주문 생성, PG 결제 처리, 결제 완료 후 수강권 활성화, 주문 내역 조회, 환불.

의존:

• identity — 주문자 식별
• catalog — product 가격/정보
• learning — 결제 완료 후 enrollment 생성 (이벤트 발행 대상)
• notification — 결제 완료/실패 알림

관련 DB 테이블:

• payment — 결제 트랜잭션
• pay_event — 결제 상태 변경 이력
• apply — 수강 신청서 (구매 폼 제출 데이터)
• certificate_post — 자격증/아포스티유 등 부가 상품 주문

현재 UI 상태: /products/tesol, /products/tec, /products/tesol-tec 페이지의 EnrollmentFormSection 은 여전히 onSubmit 도 action 도 없는 디자인 목업이고 PG 연동도 없다. 이 모듈 구현 전에 폼 핸들러 + PG SDK 통합이 선행되어야 함.

다만 가격은 product 테이블로 일원화했다. 예전에는 화면마다 가격 문자열이 박혀 있었고 컴포넌트에 기본값까지 있어서, 값을 넘기지 않으면 어느 과정이든 TESOL 가격이 찍힐 수 있었다. 지금은 getProductPricing(code) 로 읽어 반드시 주입하며, 기본값을 없애 누락되면 타입 에러로 잡힌다. 주문할 상품 코드는 data-lecture 로 실어 두었으니 결제 연동 때 쓰면 된다.

이관 검증 중 발견해 바로잡은 마스터 데이터(정본은 원본 products/products_init.php 의 $_PRODUCTS_LIST, 결제 처리 products_record.php 가 쓰던 값):

PG 선택 전제: 토스페이먼츠 / 이니시스 / 카카오페이 중 하나. 이하 엔드포인트는 PG 를 추상화한 형태로 설계.

구현 상태 (2026-08-20)

신청 폼과 주문 생성은 붙였다. 카드 결제는 코드가 다 있고 상점키만 대기 중이다.

금액은 폼을 믿지 않는다. 서버가 product 테이블에서 다시 읽어 주문을 만든다(원본은 세션에 담아 대조했다).

수강권 활성화 정책 — 원본과 다르다

원본은 결제가 tMember 를 전혀 건드리지 않는다. products/·NICEPAY/ 어디에도 회원 플래그를 켜는 코드가 없고, 관리자가 admin/member/mb_proc.php 회원 수정 화면에서 직접 켰다.

지금은 이렇게 정했다:

• 무통장 — 원본과 같다. 입금 확인이 사람 손을 타므로 자동으로 열지 않는다.
• 카드 — 승인이 떨어지면 자동으로 연다. ENTITLEMENT_FIELDS 매핑(src/lib/commerce.ts)에 따라 pay_yn / pay_tec_yn 등을 Y 로 바꾼다. tesoltec 은 둘 다 켠다.

관리자 화면

원본 admin/payment/payment_list.php 에는 조회와 삭제만 있었다. 입금확인·환불은 새로 만든 기능이다.

• /admin/login · /admin/payments (최근 100건, 상태·수단·키워드 필터)
• 입금확인 — 무통장 ready 주문에만 뜬다. 누르면 success + 수강권 활성화.
• 환불 — success 주문에 뜬다. 카드는 NICEPAY 취소(cancel_process.jsp, 성공코드 2001)를 부르고, 무통장은 상태만 정리한다(돈은 사람이 돌려준다). 둘 다 수강권을 회수한다.
• 레거시 카드 결제 417 건은 TID 가 없어 자동 취소가 안 된다. 그때는 저장하지 않았기 때문이다. 화면에서 "NICEPAY 관리자에서 직접 취소해 주세요" 로 안내하고 상태는 건드리지 않는다.

관리자 인증은 admin 테이블을 그대로 쓴다. 비밀번호가 MySQL PASSWORD() 해시(* + SHA1(SHA1(pw)))로 넘어와 있어 같은 방식으로 검증하고, 로그인에 성공하면 bcrypt 로 갈아 끼운다(점진적 이전). 세션은 NextAuth 의 admin provider 로 만들고 role='admin' 으로 구분하며, src/proxy.ts 가 /admin/* 을 막는다. 서버 액션은 미들웨어를 거치지 않으므로 액션 안에서도 role 을 다시 확인한다.

결제 상태

ready(대기) → success(완료) → cancel(취소).

무통장 주문은 입금 확인 전까지 ready 다. 원본은 신청 즉시 success 로 넣었지만(확인 UI 가 없었으니), 돈이 들어오지도 않은 주문을 완료로 두는 건 맞지 않다. 레거시 데이터(무통장 success 211 건)는 그대로 두었다.

스키마 보강

환불·입금확인을 위해 payment 에 컬럼을 더했다. 원본에 없던 기능이라 자리도 없었다.

화면

• /products/order/[orderNo] — 주문 완료 (원본 products_complete.php)
• /products/order/[orderNo]/pay — 카드 결제창 호출 (원본 products_record01.php)

예상 API 엔드포인트

수강 신청서 제출

POST /api/commerce/applications

EnrollmentFormSection 의 폼 제출. 결제 전 단계의 신청서 레코드 생성.

• Auth: 필수 (member)
• Body:

  {
    productCode: 'tesol' | 'tec' | 'tesoltec';
    applicant: {
      name: string;
      phone: string;
      email: string;
      engName?: string;     // 자격증 영문 이름
      address?: string;
      birthDate?: string;
    };
    paymentMethod: 'card' | 'bank' | 'kakaopay';
    agreements: {
      terms: boolean;
      privacy: boolean;
      marketing?: boolean;
    };
  }
  

• Response: { applicationId: number, orderId: number }
• 사이드이펙트: apply INSERT, payment INSERT (status='pending'), pay_event 에 이력 남김

주문 / 결제

POST /api/commerce/orders

주문 단독 생성 (신청서 없이 바로 결제하는 경우).

• Auth: 필수
• Body: { productCode: string; couponCode?: string }
• Response: { orderId: number, amount: number, paymentToken: string }
• paymentToken: PG 로 넘길 주문 식별자 (보안)

POST /api/commerce/payments/prepare

PG 결제 시작 직전 서명/금액 검증.

• Body: { orderId: number; paymentMethod: string }
• Response: PG SDK 에 넘길 파라미터 (merchantId, amount, signed_hash 등)

POST /api/commerce/payments/confirm

PG 의 결제 성공 콜백 수신 엔드포인트. 가장 중요.

• Auth: PG webhook 서명 검증
• Body: PG 별 상이 (예: 토스페이먼츠의 paymentKey, orderId, amount)
• 처리 순서:
  1. PG 서버에 결제 확정 API 호출 (amount 재검증)
  2. payment.status = 'paid' 업데이트
  3. pay_event INSERT (status 변경 이력)
  4. learning 모듈 내부 호출: POST /api/learning/enrollments 로 수강권 활성화
  5. notification 모듈 내부 호출: "결제 완료" SMS + 이메일 발송
• 멱등성: PG 가 같은 webhook 을 여러 번 보낼 수 있으므로 pg_transaction_id 로 dedup
• Response: { ok: true }

POST /api/commerce/payments/cancel

환불/취소 요청.

• Auth: 필수 (본인 주문만) or admin
• Body: { paymentId: number; reason: string }
• 처리:
  1. PG 취소 API 호출
  2. payment.status = 'cancelled'
  3. lecture_apply 비활성화 (환불 기간 내면 수강권 회수)
  4. notification 환불 안내

주문 조회

GET /api/commerce/orders/me

내 주문 내역.

• Auth: 필수
• Query: ?page=1&size=10&status=paid|pending|cancelled
• Response:

  {
    items: Array<{
      orderId: number;
      productName: string;
      amount: number;
      status: 'pending' | 'paid' | 'cancelled';
      paidAt: string | null;
      method: string;
    }>;
    total: number;
  }
  

GET /api/commerce/orders/[orderId]

주문 상세.

• Auth: 필수 (본인) or admin
• Response: 주문 + 결제 + 신청서 정보 조인

부가 상품 (자격증/아포스티유)

POST /api/commerce/certificates/apostille

아포스티유 공증 신청.

• Auth: 필수
• Body: { courseCode: string; shippingAddress: string; }
• 사이드이펙트: certificate_post INSERT, 결제 플로우로 리다이렉트

POST /api/commerce/certificates/signboard

수료 현판 신청.

관리자용 (낮은 우선순위)

GET /api/commerce/admin/payments

전체 결제 목록 (필터, 통계).

POST /api/commerce/admin/refund

관리자 강제 환불.

GET /api/commerce/admin/revenue?from=...&to=...

매출 집계.

⚠️ 구현 시 주의사항

1. PG webhook 멱등성: 결제 확정 API 는 반드시 멱등하게. pg_transaction_id 로 dedup.
2. 금액 재검증: 클라이언트가 넘긴 금액은 절대 신뢰하지 않고 서버의 product.sale_price 로 재계산.
3. 트랜잭션: payment 확정 → enrollment 활성화는 DB 트랜잭션으로 묶어야 함.
4. 실패 복구: PG 는 성공했는데 enrollment 활성화가 실패하는 경우를 대비한 재시도 큐 필요 (notification 에 수동 개입 알림).
5. 환불 정책: 수강 시작 후 환불 불가, 7일 이내 전액 등 정책을 DB 스키마 or 코드에 명시.