create-entity-app-server 0.0.3

package/src/app/plugins/pg/docs/README.md

@@ -0,0 +1,176 @@
+# 결제(PG) 플러그인
+
+토스페이먼츠, 페이레터(Payletter)를 통한 결제 처리 플러그인입니다. 주문 생성부터 결제 승인, 취소, 웹훅 처리까지 지원합니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [환경변수](#환경변수)
+- [API](#api)
+- [결제 흐름](#결제-흐름)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+| 항목            | 내용                                  |
+| --------------- | ------------------------------------- |
+| 지원 프로바이더 | 토스페이먼츠(V2), 페이레터(Payletter) |
+| 금액 제한       | 최소 100원, 최대 10,000,000원         |
+| 주문 ID         | `ORD` 접두사 자동 생성                |
+| 웹훅            | PG사 결제 결과 웹훅 자동 처리         |
+
+> 기본 비활성화(`enabled: false`)입니다. PG사 계약 및 API 키 발급 후 활성화하세요.
+
+---
+
+## 설정
+
+`config.json`:
+
+```json
+{
+    "enabled": false,
+    "default": "toss_payments",
+    "webhook_secret": "",
+    "order_id_prefix": "ORD",
+    "success_url": "/payment/success",
+    "fail_url": "/payment/fail",
+    "webhook_url": "/api/v1/pg/webhook",
+    "amount_limit": { "min": 100, "max": 10000000 },
+    "workers": 2,
+    "providers": {
+        "toss_payments": {
+            "driver": "toss_payments",
+            "client_key": "${TOSS_CLIENT_KEY}",
+            "secret_key": "${TOSS_SECRET_KEY}",
+            "api_url": "https://api.tosspayments.com",
+            "api_version": "2024-06-01"
+        },
+        "payletter": {
+            "driver": "payletter",
+            "client_id": "${PAYLETTER_CLIENT_ID}",
+            "api_key": "${PAYLETTER_API_KEY}",
+            "api_key_search": "${PAYLETTER_API_KEY_SEARCH}",
+            "api_url": "https://pgapi.payletter.com"
+        }
+    }
+}
+```
+
+### 설정 항목
+
+| 항목               | 기본값             | 설명                        |
+| ------------------ | ------------------ | --------------------------- |
+| `enabled`          | `false`            | 플러그인 활성화             |
+| `default`          | `toss_payments`    | 사용할 프로바이더 키        |
+| `webhook_secret`   | `""`               | 웹훅 서명 검증 비밀키       |
+| `order_id_prefix`  | `ORD`              | 주문 ID 앞에 붙는 접두사    |
+| `success_url`      | `/payment/success` | 결제 성공 후 리다이렉트 URL |
+| `fail_url`         | `/payment/fail`    | 결제 실패 후 리다이렉트 URL |
+| `amount_limit.min` | `100`              | 최소 결제 금액 (원)         |
+| `amount_limit.max` | `10000000`         | 최대 결제 금액 (원)         |
+| `workers`          | `2`                | 웹훅 처리 워커 수           |
+
+---
+
+## 환경변수
+
+```env
+# 토스페이먼츠
+TOSS_CLIENT_KEY=test_ck_...   # 또는 live_ck_...
+TOSS_SECRET_KEY=test_sk_...   # 또는 live_sk_...
+
+# 페이레터
+PAYLETTER_CLIENT_ID=...
+PAYLETTER_API_KEY=...
+PAYLETTER_API_KEY_SEARCH=...
+```
+
+---
+
+## API
+
+기본 경로: `/api/v1/pg`
+
+| 메서드 | 경로                      | 인증        | 설명                            |
+| ------ | ------------------------- | ----------- | ------------------------------- |
+| `GET`  | `/config`                 |             | 클라이언트 SDK 설정 조회 (공개) |
+| `POST` | `/orders`                 | 로그인 필요 | 주문 생성                       |
+| `GET`  | `/orders/:orderId`        | 로그인 필요 | 주문 조회                       |
+| `POST` | `/confirm`                | 로그인 필요 | 결제 승인 (PG → 서버 확인)      |
+| `POST` | `/orders/:orderId/cancel` | 로그인 필요 | 결제 취소                       |
+| `POST` | `/orders/:orderId/sync`   | 로그인 필요 | PG사 상태 동기화 (관리자)       |
+| `POST` | `/webhook`                |             | PG사 웹훅 수신                  |
+
+### GET /config 응답 예시
+
+```json
+{
+    "ok": true,
+    "data": {
+        "provider": "toss_payments",
+        "client_key": "test_ck_...",
+        "success_url": "/payment/success",
+        "fail_url": "/payment/fail"
+    }
+}
+```
+
+### POST /orders 요청 바디
+
+```json
+{
+    "amount": 29900,
+    "order_name": "프리미엄 플랜 1개월",
+    "customer_name": "홍길동",
+    "customer_email": "hong@example.com",
+    "provider": "toss_payments"
+}
+```
+
+### POST /confirm 요청 바디 (토스페이먼츠)
+
+```json
+{
+    "payment_key": "...",
+    "order_id": "ORD-...",
+    "amount": 29900
+}
+```
+
+### 주문 상태 값
+
+| 상태        | 설명                  |
+| ----------- | --------------------- |
+| `created`   | 주문 생성됨 (결제 전) |
+| `pending`   | 결제 진행 중          |
+| `paid`      | 결제 완료             |
+| `cancelled` | 취소됨                |
+| `failed`    | 결제 실패             |
+
+---
+
+## 결제 흐름
+
+```
+1. GET  /api/v1/pg/config              → { client_key }
+2. POST /api/v1/pg/orders              → { order_id }
+3. 클라이언트 → 토스페이먼츠 위젯/SDK
+4. 결제 완료 → GET /payment/success?paymentKey=...&orderId=...
+5. POST /api/v1/pg/confirm             body: { payment_key, order_id, amount }
+6. 서버 → PG사 최종 승인 확인 완료 → { status: "paid" }
+```
+
+---
+
+## 운영 팁
+
+- 테스트 환경에서는 `test_ck_...` / `test_sk_...` 키 사용
+- `webhook_secret` 설정 권장 — PG사 웹훅 서명 검증으로 위변조 방지
+- 실 결제 전 반드시 `success_url`, `fail_url`을 실제 서비스 URL로 변경
+- 결제 금액은 클라이언트와 서버 모두에서 검증 (프론트 금액 조작 방지)

package/src/app/plugins/pg/entities/pg_cancel.json

@@ -0,0 +1,60 @@
+{
+    "name": "pg_cancel",
+    "description": "PG 결제 취소 이력 엔티티. 부분/전액 취소를 기록합니다. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "read_only": true,
+    "fields": {
+        "order_seq": {
+            "index": true,
+            "type": "integer",
+            "required": true,
+            "comment": "pg_order.seq 참조"
+        },
+        "order_id": {
+            "index": true,
+            "type": "string",
+            "required": true,
+            "comment": "주문번호 (조회 편의)"
+        },
+        "cancel_amount": {
+            "index": true,
+            "type": "integer",
+            "required": true,
+            "comment": "취소 금액"
+        },
+        "cancel_reason": {
+            "index": true,
+            "type": "string",
+            "required": true,
+            "comment": "취소 사유 (최대 200자)"
+        },
+        "cancel_status": {
+            "index": true,
+            "type": [
+                "done",
+                "failed"
+            ],
+            "default": "done",
+            "comment": "취소 처리 상태"
+        },
+        "transaction_key": {
+            "index": true,
+            "type": "string",
+            "comment": "PG사 취소 거래 키"
+        },
+        "canceled_time": {
+            "comment": "취소 시각 (ISO 8601)"
+        },
+        "refundable_amount": {
+            "comment": "취소 후 환불 가능 잔액"
+        },
+        "tax_free_amount": {
+            "comment": "취소된 금액 중 면세 금액"
+        },
+        "receipt_key": {
+            "comment": "현금영수증 키 (해당 시)"
+        },
+        "refund_account": {
+            "comment": "환불 계좌 정보 JSON (가상계좌 취소 시)"
+        }
+    }
+}

package/src/app/plugins/pg/entities/pg_order.json

@@ -0,0 +1,115 @@
+{
+    "name": "pg_order",
+    "description": "PG 결제 주문 엔티티. 결제 요청/승인/취소 상태를 추적합니다. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "fields": {
+        "order_id": {
+            "index": true,
+            "type": "string",
+            "required": true,
+            "unique": true,
+            "comment": "고유 주문번호 (6~64자, [a-zA-Z0-9_-])"
+        },
+        "status": {
+            "index": true,
+            "type": [
+                "created",
+                "ready",
+                "in_progress",
+                "waiting",
+                "done",
+                "canceled",
+                "partial_canceled",
+                "aborted",
+                "expired"
+            ],
+            "default": "created",
+            "comment": "결제 상태"
+        },
+        "payment_key": {
+            "index": true,
+            "type": "string",
+            "comment": "PG사 결제 키 (승인 후 할당)"
+        },
+        "provider": {
+            "index": true,
+            "type": "string",
+            "required": true,
+            "comment": "PG 프로바이더 키 (toss_payments, kcp, inicis 등)"
+        },
+        "method": {
+            "index": true,
+            "type": "string",
+            "comment": "결제수단 (card, virtual_account, transfer, phone, easy_pay)"
+        },
+        "amount": {
+            "index": true,
+            "type": "integer",
+            "required": true,
+            "comment": "총 결제 금액 (원)"
+        },
+        "balance_amount": {
+            "index": true,
+            "type": "integer",
+            "comment": "취소 가능 잔액"
+        },
+        "currency": {
+            "index": true,
+            "type": "string",
+            "default": "KRW",
+            "comment": "통화 코드 (ISO 4217)"
+        },
+        "account_seq": {
+            "index": true,
+            "type": "integer",
+            "comment": "구매자 계정 seq (로그인 사용자)"
+        },
+        "customer_name": {
+            "index": true,
+            "hash": true,
+            "type": "string",
+            "comment": "구매자명"
+        },
+        "customer_email": {
+            "index": true,
+            "hash": true,
+            "type": "string",
+            "comment": "구매자 이메일"
+        },
+        "order_name": {
+            "comment": "주문 상품명 (예: '토스 티셔츠 외 2건')"
+        },
+        "requested_time": {
+            "comment": "결제 요청 시각 (ISO 8601)"
+        },
+        "approved_time": {
+            "comment": "결제 승인 시각 (ISO 8601)"
+        },
+        "card_info": {
+            "comment": "카드 결제 정보 JSON (마스킹된 카드번호, 카드타입 등)"
+        },
+        "virtual_account_info": {
+            "comment": "가상계좌 정보 JSON (계좌번호, 은행, 입금기한)"
+        },
+        "easy_pay_info": {
+            "comment": "간편결제 정보 JSON (provider, amount, discountAmount)"
+        },
+        "receipt_url": {
+            "comment": "영수증 URL"
+        },
+        "checkout_url": {
+            "comment": "결제창 URL"
+        },
+        "failure_code": {
+            "comment": "실패 에러 코드"
+        },
+        "failure_message": {
+            "comment": "실패 에러 메시지"
+        },
+        "metadata": {
+            "comment": "상점 커스텀 데이터 JSON (최대 5개 key-value)"
+        },
+        "pg_raw_response": {
+            "comment": "PG사 원본 응답 JSON (디버깅용)"
+        }
+    }
+}

package/src/app/plugins/pg/entities/pg_webhook_log.json

@@ -0,0 +1,52 @@
+{
+    "name": "pg_webhook_log",
+    "description": "PG 웹훅 수신 이력. 모든 수신 이벤트를 기록합니다. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "hard_delete": true,
+    "read_only": true,
+    "compress": true,
+    "fields": {
+        "event_type": {
+            "index": true,
+            "type": "string",
+            "required": true,
+            "comment": "웹훅 이벤트 타입 (payment.done, payment.canceled 등)"
+        },
+        "order_id": {
+            "index": true,
+            "type": "string",
+            "comment": "관련 주문번호"
+        },
+        "payment_key": {
+            "index": true,
+            "type": "string",
+            "comment": "관련 결제 키"
+        },
+        "status": {
+            "index": true,
+            "type": [
+                "received",
+                "processed",
+                "failed"
+            ],
+            "default": "received",
+            "comment": "웹훅 처리 상태"
+        },
+        "provider": {
+            "index": true,
+            "type": "string",
+            "comment": "PG 프로바이더 키"
+        },
+        "payload": {
+            "comment": "수신한 웹훅 원본 JSON"
+        },
+        "processed_time": {
+            "comment": "처리 완료 시각"
+        },
+        "error_message": {
+            "comment": "처리 실패 시 에러 메시지"
+        },
+        "signature": {
+            "comment": "웹훅 서명값 (검증용)"
+        }
+    }
+}

package/src/app/plugins/pg/entity-adapter.ts

@@ -0,0 +1,144 @@
+/**
+ * PG 결제 Entity Adapter
+ *
+ * entity-server-client를 통해 DB entity CRUD를 PgQuerier 인터페이스로 어댑팅
+ *
+ * 엔티티:
+ *   - pg_order       : 결제 주문
+ *   - pg_cancel      : 결제 취소 이력
+ *   - pg_webhook_log : 웹훅 수신 이력
+ */
+
+import { EntityServerClient } from "entity-server-client";
+import type { PgQuerier } from "./types/index.ts";
+
+const entityServer = new EntityServerClient();
+
+function toNumber(v: unknown): number {
+    if (v == null) return 0;
+    const n = Number(v);
+    return Number.isNaN(n) ? 0 : n;
+}
+
+export class PgEntityAdapter implements PgQuerier {
+    async createOrder(data: Record<string, unknown>): Promise<number> {
+        const resp = await entityServer.submit("pg_order", data);
+        return ((resp as Record<string, unknown>).seq as number) ?? 0;
+    }
+
+    async getOrderById(
+        orderId: string,
+    ): Promise<Record<string, unknown> | null> {
+        try {
+            const resp = await entityServer.list("pg_order", {
+                order_id: orderId,
+                limit: 1,
+            } as never);
+            const items =
+                ((
+                    (resp as Record<string, unknown>).data as Record<
+                        string,
+                        unknown
+                    >
+                )?.items as Record<string, unknown>[]) ?? [];
+            return items[0] ?? null;
+        } catch {
+            return null;
+        }
+    }
+
+    async getOrderBySeq(seq: number): Promise<Record<string, unknown> | null> {
+        try {
+            const resp = await entityServer.get("pg_order", seq);
+            return (
+                ((resp as Record<string, unknown>).data as Record<
+                    string,
+                    unknown
+                >) ?? null
+            );
+        } catch {
+            return null;
+        }
+    }
+
+    async updateOrder(
+        seq: number,
+        expectedStatus: string,
+        patch: Record<string, unknown>,
+    ): Promise<boolean> {
+        let txId: string | undefined;
+        try {
+            // 트랜잭션으로 read-check-write 원자성 보장
+            txId = await entityServer.transStart();
+            const current = await this.getOrderBySeq(seq);
+            if (!current || current.status !== expectedStatus) {
+                await entityServer.transRollback(txId);
+                return false;
+            }
+            await entityServer.submit(
+                "pg_order",
+                { seq, ...patch },
+                { transactionId: txId },
+            );
+            await entityServer.transCommit(txId);
+            return true;
+        } catch {
+            if (txId) {
+                try {
+                    await entityServer.transRollback(txId);
+                } catch {
+                    /* ignore */
+                }
+            }
+            return false;
+        }
+    }
+
+    async updateOrderDirect(
+        seq: number,
+        patch: Record<string, unknown>,
+    ): Promise<void> {
+        await entityServer.submit("pg_order", { seq, ...patch });
+    }
+
+    async createCancel(data: Record<string, unknown>): Promise<number> {
+        const resp = await entityServer.submit("pg_cancel", data);
+        return toNumber((resp as Record<string, unknown>).seq);
+    }
+
+    async createWebhookLog(data: Record<string, unknown>): Promise<number> {
+        const resp = await entityServer.submit("pg_webhook_log", data);
+        return toNumber((resp as Record<string, unknown>).seq);
+    }
+
+    async updateWebhookLog(
+        seq: number,
+        patch: Record<string, unknown>,
+    ): Promise<void> {
+        await entityServer.submit("pg_webhook_log", { seq, ...patch });
+    }
+
+    async findWebhookLog(
+        paymentKey: string,
+        eventType: string,
+    ): Promise<Record<string, unknown> | null> {
+        try {
+            const resp = await entityServer.list("pg_webhook_log", {
+                payment_key: paymentKey,
+                event_type: eventType,
+                status: "processed",
+                limit: 1,
+            } as never);
+            const items =
+                ((
+                    (resp as Record<string, unknown>).data as Record<
+                        string,
+                        unknown
+                    >
+                )?.items as Record<string, unknown>[]) ?? [];
+            return items[0] ?? null;
+        } catch {
+            return null;
+        }
+    }
+}