create-entity-app-server 0.0.3

package/src/app/plugins/pg/handlers.ts

@@ -0,0 +1,240 @@
+/**
+ * PG 결제 핸들러
+ *
+ * POST   /v1/pg/orders              → 주문 생성
+ * GET    /v1/pg/orders/:orderId     → 주문 조회
+ * POST   /v1/pg/confirm             → 결제 승인
+ * POST   /v1/pg/orders/:orderId/cancel → 결제 취소
+ * POST   /v1/pg/orders/:orderId/sync   → 상태 동기화
+ * POST   /v1/pg/webhook              → 웹훅 수신
+ * GET    /v1/pg/config               → 클라이언트 설정
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail } from "@gateway/api";
+import { PgNotFoundError, PgConflictError, PgError } from "./types/index.ts";
+
+/** pg 서비스 사용 가능 여부를 확인한다 */
+const ensureSvc = (req: FastifyRequest, reply: FastifyReply) => {
+    const svc = (req.server as unknown as Record<string, unknown>).pgService as
+        | import("./service.ts").PgService
+        | null
+        | undefined;
+    if (!svc) {
+        reply.status(503).send(fail("PG service not available"));
+        return null;
+    }
+    return svc;
+};
+
+/** PG 에러 응답 헬퍼 */
+function pgErrorResponse(reply: FastifyReply, err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (err instanceof PgNotFoundError) {
+        return reply.status(404).send(fail(msg));
+    }
+    if (err instanceof PgConflictError) {
+        return reply.status(409).send(fail(msg));
+    }
+    if (err instanceof PgError) {
+        return reply.status(502).send(fail(msg));
+    }
+    return reply.status(400).send(fail(msg));
+}
+
+// ─── 주문 생성 ───────────────────────────────────────────────────────────────
+/** 새 주문을 생성한다 */
+export async function createOrder(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    try {
+        const body = request.body as {
+            amount?: number;
+            order_name?: string;
+            currency?: string;
+            customer_name?: string;
+            customer_email?: string;
+            provider?: string;
+            metadata?: Record<string, unknown>;
+        };
+
+        const result = await svc.createOrder({
+            amount: body.amount ?? 0,
+            orderName: body.order_name ?? "",
+            currency: body.currency,
+            customerName: body.customer_name,
+            customerEmail: body.customer_email,
+            provider: body.provider,
+            metadata: body.metadata,
+        });
+
+        return reply.status(201).send(ok(result));
+    } catch (err) {
+        return pgErrorResponse(reply, err);
+    }
+}
+
+// ─── 주문 조회 ───────────────────────────────────────────────────────────────
+/** 주문 정보를 조회한다 */
+export async function getOrder(request: FastifyRequest, reply: FastifyReply) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    try {
+        const { orderId } = request.params as { orderId: string };
+        if (!orderId) {
+            return reply.status(400).send(fail("orderId is required"));
+        }
+        const result = await svc.getOrder(orderId);
+        return ok(result);
+    } catch (err) {
+        return pgErrorResponse(reply, err);
+    }
+}
+
+// ─── 결제 승인 ───────────────────────────────────────────────────────────────
+/** 결제를 승인한다 */
+export async function confirmPayment(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    try {
+        const body = request.body as {
+            payment_key?: string;
+            order_id?: string;
+            amount?: number;
+        };
+
+        if (!body.payment_key || !body.order_id || !body.amount) {
+            return reply
+                .status(400)
+                .send(fail("payment_key, order_id, and amount are required"));
+        }
+
+        const result = await svc.confirmPayment(
+            body.payment_key,
+            body.order_id,
+            body.amount,
+        );
+        return ok(result);
+    } catch (err) {
+        return pgErrorResponse(reply, err);
+    }
+}
+
+// ─── 결제 취소 ───────────────────────────────────────────────────────────────
+/** 결제를 취소한다 */
+export async function cancelPayment(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    try {
+        const { orderId } = request.params as { orderId: string };
+        if (!orderId) {
+            return reply.status(400).send(fail("orderId is required"));
+        }
+
+        const body = request.body as {
+            cancel_reason?: string;
+            cancel_amount?: number;
+            refund_account?: {
+                bank: string;
+                account_number: string;
+                holder_name: string;
+            };
+        };
+
+        if (!body.cancel_reason) {
+            return reply.status(400).send(fail("cancel_reason is required"));
+        }
+
+        const result = await svc.cancelPayment(
+            orderId,
+            body.cancel_reason,
+            body.cancel_amount,
+            body.refund_account
+                ? {
+                      bank: body.refund_account.bank,
+                      accountNumber: body.refund_account.account_number,
+                      holderName: body.refund_account.holder_name,
+                  }
+                : undefined,
+        );
+        return ok(result);
+    } catch (err) {
+        return pgErrorResponse(reply, err);
+    }
+}
+
+// ─── 상태 동기화 ─────────────────────────────────────────────────────────────
+/** PG사에서 결제 정보를 재조회하여 상태를 동기화한다 */
+export async function syncPaymentStatus(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    try {
+        const { orderId } = request.params as { orderId: string };
+        if (!orderId) {
+            return reply.status(400).send(fail("orderId is required"));
+        }
+        const result = await svc.syncStatus(orderId);
+        return ok(result);
+    } catch (err) {
+        return pgErrorResponse(reply, err);
+    }
+}
+
+// ─── 웹훅 수신 ───────────────────────────────────────────────────────────────
+/** PG사 웹훅을 수신한다 */
+export async function handleWebhook(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    try {
+        const payload = Buffer.from(JSON.stringify(request.body));
+        const signature =
+            (request.headers["x-webhook-signature"] as string) ?? "";
+
+        // 웹훅은 실패해도 200 반환 (PG사 재전송 방지)
+        try {
+            await svc.handleWebhook(payload, signature);
+        } catch (err) {
+            request.log.warn({ err }, "pg: webhook processing failed");
+        }
+
+        return ok(null);
+    } catch {
+        // 항상 200 반환
+        return ok(null);
+    }
+}
+
+// ─── 클라이언트 설정 ─────────────────────────────────────────────────────────
+/** 클라이언트 SDK 설정을 반환한다 */
+export async function getClientConfig(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const svc = ensureSvc(request, reply);
+    if (!svc) return;
+
+    const provider = (request.query as { provider?: string }).provider;
+    const config = svc.getClientConfig(provider);
+    return ok(config);
+}

package/src/app/plugins/pg/index.ts

@@ -0,0 +1,98 @@
+/**
+ * PG 결제 Fastify 플러그인
+ *
+ * 설정 로드 → PgClient 인스턴스 생성 → Entity Adapter 주입 →
+ * PgService 시작 → app.pgService 데코레이터 등록
+ */
+
+import { fileURLToPath } from "url";
+import path from "path";
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { ensurePluginEntities } from "@gateway/api";
+import { loadPgConfig } from "./config.ts";
+import { createPgClient } from "./providers/index.ts";
+import { PgService, registerClientKey } from "./service.ts";
+import { PgEntityAdapter } from "./entity-adapter.ts";
+import type { PgClient } from "./types/index.ts";
+
+declare module "fastify" {
+    interface FastifyInstance {
+        pgService: PgService | null;
+    }
+}
+
+/** PG 결제 플러그인을 등록한다 */
+export default fp(
+    async (app: FastifyInstance) => {
+        const config = loadPgConfig();
+
+        if (!config) {
+            app.log.info("PG plugin disabled in config");
+            app.decorate("pgService", null);
+            return;
+        }
+
+        // 필요한 엔티티가 서버에 없으면 자동 생성
+        const pluginDir = path.dirname(fileURLToPath(import.meta.url));
+        await ensurePluginEntities(pluginDir).catch((err) =>
+            app.log.warn(err, "PG: entity setup failed, continuing"),
+        );
+
+        // PgClient 인스턴스 생성
+        const clients = new Map<string, PgClient>();
+
+        for (const [name, provCfg] of Object.entries(config.providers)) {
+            try {
+                const client = createPgClient(provCfg);
+                clients.set(name, client);
+
+                // clientKey 글로벌 등록 (getClientConfig에서 사용)
+                if (provCfg.client_key) {
+                    registerClientKey(name, provCfg.client_key);
+                }
+
+                app.log.info(
+                    `PG provider registered: ${name} (${provCfg.driver})`,
+                );
+            } catch (err) {
+                app.log.error(
+                    err,
+                    `Failed to create pg provider: ${name} (${provCfg.driver})`,
+                );
+            }
+        }
+
+        if (clients.size === 0) {
+            app.log.warn("PG: no valid providers configured, service disabled");
+            app.decorate("pgService", null);
+            return;
+        }
+
+        const service = new PgService({
+            clients,
+            defaultClient: config.default,
+            webhookSecret: config.webhook_secret ?? "",
+            amountLimit: config.amount_limit ?? null,
+            orderIdPrefix: config.order_id_prefix ?? "ORD",
+            successUrl: config.success_url ?? "/payment/success",
+            failUrl: config.fail_url ?? "/payment/fail",
+            webhookUrl: config.webhook_url ?? "/api/v1/pg/webhook",
+            workers: config.workers ?? 2,
+        });
+
+        // Entity Adapter 주입
+        service.setQuerier(new PgEntityAdapter());
+
+        // 서비스 시작
+        await service.start();
+
+        app.decorate("pgService", service);
+
+        // graceful shutdown
+        app.addHook("onClose", async () => {
+            service.stop();
+        });
+    },
+    { name: "pg-plugin" },
+);

package/src/app/plugins/pg/providers/danal.ts

@@ -0,0 +1,178 @@
+/**
+ * 다날(Danal ONE API) 결제 클라이언트
+ *
+ * 공식 API 문서: https://developers.danalpay.com/reference/server/confirm
+ * Base URL: https://one-api.danalpay.com
+ * 인증: HTTP Basic Auth — "Basic " + base64(secretKey + ":")
+ * 지원 결제수단: CARD, MOBILE, TRANSFER, VACCOUNT 등
+ */
+
+import type {
+    PgClient,
+    PgProviderConfig,
+    ConfirmRequest,
+    CancelRequest,
+    PaymentResult,
+    CancelResult,
+    FailureInfo,
+} from "../types/index.ts";
+
+export class DanalClient implements PgClient {
+    private readonly _name: string;
+    private readonly apiUrl: string;
+    private readonly merchantId: string;
+    private readonly authHeader: string;
+
+    constructor(cfg: PgProviderConfig) {
+        if (!cfg.cp_id) throw new Error("danal: cp_id is required");
+        if (!cfg.secret_key) throw new Error("danal: secret_key is required");
+
+        this._name = cfg.driver;
+        this.apiUrl = cfg.api_url || "https://one-api.danalpay.com";
+        this.merchantId = cfg.cp_id;
+        this.authHeader =
+            "Basic " + Buffer.from(cfg.secret_key + ":").toString("base64");
+    }
+
+    name(): string {
+        return this._name;
+    }
+
+    private headers(): Record<string, string> {
+        return {
+            Authorization: this.authHeader,
+            "Content-Type": "application/json",
+        };
+    }
+
+    /**
+     * 결제 승인
+     *
+     * POST /payments/confirm
+     * 필수 파라미터: method, transactionId, merchantId, amount(문자열), orderId
+     */
+    async confirmPayment(
+        _ctx: AbortSignal | null,
+        req: ConfirmRequest,
+    ): Promise<PaymentResult> {
+        const method = req.method || "CARD";
+        const resp = await fetch(`${this.apiUrl}/payments/confirm`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({
+                method,
+                transactionId: req.paymentKey,
+                merchantId: this.merchantId,
+                amount: String(req.amount),
+                orderId: req.orderId,
+            }),
+            signal: _ctx ?? AbortSignal.timeout(60_000),
+        });
+        return this.doRequest(resp);
+    }
+
+    /**
+     * 결제 취소
+     *
+     * POST /payments/cancel
+     * 전액 취소: cancelType "C", amount = originalAmount
+     * 부분 취소: cancelType "P", amount = cancelAmount
+     */
+    async cancelPayment(
+        _ctx: AbortSignal | null,
+        req: CancelRequest,
+    ): Promise<CancelResult> {
+        const method = req.method || "CARD";
+        let cancelType = "C";
+        let amount: number;
+
+        if (req.cancelAmount == null) {
+            cancelType = "C";
+            amount = req.originalAmount ?? 0;
+        } else {
+            cancelType = "P";
+            amount = req.cancelAmount;
+        }
+
+        const resp = await fetch(`${this.apiUrl}/payments/cancel`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({
+                method,
+                transactionId: req.paymentKey,
+                merchantId: this.merchantId,
+                amount: String(amount),
+                cancelType,
+                cancelReason: req.cancelReason,
+            }),
+            signal: _ctx ?? AbortSignal.timeout(60_000),
+        });
+        const result = await this.doRequest(resp);
+        return { ...result };
+    }
+
+    /**
+     * 결제 조회 — 다날 ONE API에는 공개된 조회 엔드포인트가 없습니다.
+     */
+    async getPayment(
+        _ctx: AbortSignal | null,
+        _paymentKey: string,
+    ): Promise<PaymentResult> {
+        throw new Error(
+            "danal: 결제 조회 API는 공개 문서에 제공되지 않습니다. " +
+                "다날 기술지원팀(developer@danal.co.kr)에 문의하여 inquiry 엔드포인트를 확인하세요",
+        );
+    }
+
+    /**
+     * 웹훅 검증 — 다날은 별도 서명을 공개하지 않으므로 항상 true 반환
+     */
+    async verifyWebhook(
+        _ctx: AbortSignal | null,
+        _payload: Buffer,
+        _signature: string,
+    ): Promise<boolean> {
+        return true;
+    }
+
+    private async doRequest(resp: Response): Promise<PaymentResult> {
+        const text = await resp.text();
+
+        if (resp.status >= 500) {
+            throw new Error(
+                `danal: server error (status ${resp.status}): ${text}`,
+            );
+        }
+
+        const raw = JSON.parse(text) as Record<string, unknown>;
+        const result: PaymentResult = {
+            paymentKey: "",
+            orderId: "",
+            orderName: "",
+            status: "aborted",
+            method: "",
+            totalAmount: 0,
+            balanceAmount: 0,
+            currency: "KRW",
+            type: "PAYMENT",
+            country: "KR",
+            isPartialCancelable: false,
+            _raw: raw,
+        };
+
+        const code = String(raw.code ?? "");
+        const message = String(raw.message ?? "");
+
+        if (code === "SUCCESS") {
+            result.status = "done";
+            if (raw.transactionId)
+                result.paymentKey = String(raw.transactionId);
+            if (raw.orderId) result.orderId = String(raw.orderId);
+        } else {
+            result.status = "aborted";
+            result.failure = { code, message } as FailureInfo;
+        }
+
+        return result;
+    }
+}