create-entity-app-server 0.0.3

package/src/app/plugins/pg/types/payment.ts

@@ -0,0 +1,145 @@
+export interface ConfirmRequest {
+    paymentKey: string;
+    orderId: string;
+    amount: number;
+    method?: string;
+}
+
+export interface CancelRequest {
+    paymentKey: string;
+    cancelReason: string;
+    cancelAmount?: number;
+    originalAmount?: number;
+    method?: string;
+    currency?: string;
+    taxFreeAmount?: number;
+    refundReceiveAccount?: RefundAccount;
+    idempotencyKey?: string;
+}
+
+export interface RefundAccount {
+    bank: string;
+    accountNumber: string;
+    holderName: string;
+}
+
+export interface PaymentResult {
+    paymentKey: string;
+    orderId: string;
+    orderName: string;
+    status: string;
+    method: string;
+    totalAmount: number;
+    balanceAmount: number;
+    currency: string;
+    requestedAt?: string;
+    approvedAt?: string;
+    type: string;
+    country: string;
+    isPartialCancelable: boolean;
+    card?: CardInfo;
+    virtualAccount?: VirtualAccountInfo;
+    easyPay?: EasyPayInfo;
+    receipt?: ReceiptInfo;
+    failure?: FailureInfo;
+    cancels?: CancelInfo[];
+    _raw?: Record<string, unknown>;
+}
+
+export interface CardInfo {
+    issuerCode: string;
+    acquirerCode: string;
+    number: string;
+    installmentPlanMonths: number;
+    cardType: string;
+    ownerType: string;
+    approveNo: string;
+    amount: number;
+    isInterestFree: boolean;
+}
+
+export interface VirtualAccountInfo {
+    accountNumber: string;
+    accountType: string;
+    bankCode: string;
+    customerName: string;
+    dueDate: string;
+    expired: boolean;
+    settlementStatus: string;
+    refundStatus: string;
+}
+
+export interface EasyPayInfo {
+    provider: string;
+    amount: number;
+    discountAmount: number;
+}
+
+export interface ReceiptInfo {
+    url: string;
+}
+
+export interface FailureInfo {
+    code: string;
+    message: string;
+}
+
+export interface CancelInfo {
+    transactionKey: string;
+    cancelReason: string;
+    cancelAmount: number;
+    canceledAt: string;
+    cancelStatus: string;
+    refundableAmount: number;
+}
+
+export interface CancelResult extends PaymentResult {
+    latestCancel?: CancelInfo;
+}
+
+export interface OrderRequest {
+    amount: number;
+    orderName: string;
+    currency?: string;
+    customerName?: string;
+    customerEmail?: string;
+    provider?: string;
+    accountSeq?: number;
+    metadata?: Record<string, unknown>;
+}
+
+export interface OrderResponse {
+    seq: number;
+    orderId: string;
+    amount: number;
+    orderName: string;
+    currency: string;
+    status: string;
+    clientKey?: string;
+    successUrl: string;
+    failUrl: string;
+}
+
+export interface ClientConfig {
+    driver: string;
+    clientKey: string;
+    apiVersion?: string;
+}
+
+export const ORDER_STATUS = {
+    CREATED: "created",
+    READY: "ready",
+    IN_PROGRESS: "in_progress",
+    WAITING: "waiting",
+    DONE: "done",
+    CANCELED: "canceled",
+    PARTIAL_CANCELED: "partial_canceled",
+    ABORTED: "aborted",
+    EXPIRED: "expired",
+} as const;
+
+export const WEBHOOK_STATUS = {
+    RECEIVED: "received",
+    PROCESSED: "processed",
+    FAILED: "failed",
+} as const;

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

@@ -0,0 +1,32 @@
+# Providers (공유 인증 헬퍼)
+
+외부 API 인증에 필요한 공유 유틸리티 모음입니다.
+
+---
+
+## 포함 모듈
+
+### `solapi-auth.ts` — Solapi HMAC 서명 생성
+
+Solapi(구 알리고) SMS·알림톡 API 요청 시 `Authorization` 헤더를 생성합니다.
+
+**인증 방식:** HMAC-SHA256
+
+```
+Authorization: HMAC-SHA256 <api_key>:<timestamp>:<salt>:<signature>
+```
+
+**사용 예시:**
+
+```typescript
+import { buildSolapiAuthorization } from "@/app/plugins/providers/solapi-auth.ts";
+
+const headers = buildSolapiAuthorization(apiKey, apiSecret);
+// headers.authorization, headers.date, headers.salt 사용
+```
+
+---
+
+## 설계 의도
+
+이 폴더는 여러 플러그인(SMS, Alimtalk 등)에서 공통으로 사용하는 외부 서비스 인증 로직을 통합합니다. 새 외부 API 인증 헬퍼가 필요한 경우 이 폴더에 추가하고 관련 플러그인에서 import합니다.

package/src/app/plugins/providers/solapi-auth.ts

@@ -0,0 +1,27 @@
+import { createHmac, randomBytes } from "node:crypto";
+
+export type SolapiAuthHeader = {
+    authorization: string;
+    date: string;
+    salt: string;
+    signature: string;
+};
+
+/** Solapi HMAC-SHA256 Authorization 헤더를 생성한다. */
+export function buildSolapiAuthorization(
+    apiKey: string,
+    apiSecret: string,
+): SolapiAuthHeader {
+    const date = new Date().toISOString();
+    const salt = randomBytes(16).toString("hex");
+    const signature = createHmac("sha256", apiSecret)
+        .update(date + salt)
+        .digest("hex");
+
+    return {
+        authorization: `HMAC-SHA256 apiKey=${apiKey}, date=${date}, salt=${salt}, signature=${signature}`,
+        date,
+        salt,
+        signature,
+    };
+}

package/src/app/plugins/push/config.example.json

@@ -0,0 +1,26 @@
+{
+    "_comment": "FCM (Firebase Cloud Messaging) 및 APNs (Apple Push Notification) 설정 예시",
+    "enabled": true,
+    "default": "main",
+    "workers": 2,
+    "queue_size": 50,
+    "dispatch_interval_sec": 5,
+    "max_retries": 3,
+    "providers": {
+        "main": {
+            "_driver_comment": "FCM: Android, iOS(FCM 경유), Web 통합 발송",
+            "driver": "fcm",
+            "project_id": "my-firebase-project-id",
+            "key_file": "configs/keys/fcm-service-account.json"
+        },
+        "ios": {
+            "_driver_comment": "APNs: iOS 직접 발송 (HTTP/2 JWT 인증)",
+            "driver": "apns",
+            "key_id": "XXXXXXXXXX",
+            "team_id": "XXXXXXXXXX",
+            "bundle_id": "com.example.app",
+            "key_file": "configs/keys/apns-authkey.p8",
+            "production": false
+        }
+    }
+}

package/src/app/plugins/push/config.json

@@ -0,0 +1,18 @@
+{
+    "_comment": "푸시 알림 플러그인 — FCM(Firebase Cloud Messaging) 기반 앱 푸시 발송, 큐·재시도·워커 설정 포함",
+    "enabled": false,
+    "default": "main",
+    "workers": 2,
+    "queue_size": 50,
+    "dispatch_interval_sec": 5,
+    "max_retries": 3,
+    "providers": {
+        "main": {
+            "driver": "fcm",
+            "project_id": "${FCM_PROJECT_ID}",
+            "key_file": "${FCM_KEY_FILE}"
+        }
+    },
+    "deploy": true,
+    "minify": false
+}

package/src/app/plugins/push/config.ts

@@ -0,0 +1,119 @@
+/**
+ * Push 알림 설정 로더
+ *
+ * 플러그인 디렉토리의 config.json을 읽고 환경변수 치환을 수행합니다.
+ * SMS config 로더 패턴에서 포팅
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "@gateway/api";
+import type { PushConfig } from "./types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+/** Push 설정을 로드한다 */
+export function loadPushConfig(): PushConfig | null {
+    if (!existsSync(CONFIG_PATH)) {
+        return null;
+    }
+
+    try {
+        let raw = readFileSync(CONFIG_PATH, "utf-8");
+
+        // 환경변수 치환: ${VAR} → process.env.VAR
+        raw = raw.replace(
+            /\$\{([^}]+)\}/g,
+            (_match, name) => process.env[name] ?? "",
+        );
+
+        const cfg: PushConfig = JSON.parse(raw);
+
+        if (cfg.enabled === false) {
+            logger.info("Push plugin disabled in config");
+            return null;
+        }
+
+        // 기본값 보정
+        if (!cfg.workers || cfg.workers <= 0) cfg.workers = 2;
+        if (!cfg.queue_size || cfg.queue_size <= 0) cfg.queue_size = 50;
+        if (!cfg.dispatch_interval_sec || cfg.dispatch_interval_sec <= 0)
+            cfg.dispatch_interval_sec = 5;
+        if (!cfg.max_retries || cfg.max_retries <= 0) cfg.max_retries = 3;
+
+        // 프로바이더가 1개이고 default 미설정 시 자동 추론
+        if (
+            !cfg.default &&
+            cfg.providers &&
+            Object.keys(cfg.providers).length === 1
+        ) {
+            cfg.default = Object.keys(cfg.providers)[0]!;
+        }
+
+        // 검증
+        if (!cfg.providers || Object.keys(cfg.providers).length === 0) {
+            logger.error("Push config: at least one provider is required");
+            return null;
+        }
+        if (!cfg.default) {
+            logger.error("Push config: default provider must be specified");
+            return null;
+        }
+        if (!(cfg.default in cfg.providers)) {
+            logger.error(
+                `Push config: default provider '${cfg.default}' not found in providers`,
+            );
+            return null;
+        }
+
+        // 드라이버별 필수 필드 검증
+        for (const [name, p] of Object.entries(cfg.providers)) {
+            if (!p.driver) {
+                logger.error(
+                    `Push config: provider '${name}': driver is required`,
+                );
+                return null;
+            }
+            if (p.driver === "fcm") {
+                if (!p.project_id) {
+                    logger.error(
+                        `Push config: provider '${name}' (fcm): project_id is required`,
+                    );
+                    return null;
+                }
+                if (!p.key_file) {
+                    logger.error(
+                        `Push config: provider '${name}' (fcm): key_file is required`,
+                    );
+                    return null;
+                }
+            } else if (p.driver === "apns") {
+                if (!p.key_id || !p.team_id || !p.bundle_id) {
+                    logger.error(
+                        `Push config: provider '${name}' (apns): key_id, team_id, bundle_id are required`,
+                    );
+                    return null;
+                }
+                if (!p.key_file) {
+                    logger.error(
+                        `Push config: provider '${name}' (apns): key_file is required`,
+                    );
+                    return null;
+                }
+            } else {
+                const unknownDriver = (p as { driver: string }).driver;
+                logger.error(
+                    `Push config: provider '${name}': unsupported driver '${unknownDriver}'`,
+                );
+                return null;
+            }
+        }
+
+        return cfg;
+    } catch (err) {
+        logger.error({ err }, "Push config: failed to load config.json");
+        return null;
+    }
+}

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

@@ -0,0 +1,147 @@
+# FCM 푸시 알림 플러그인 (Push)
+
+Firebase Cloud Messaging(FCM)을 통한 모바일 앱 푸시 알림 발송 플러그인입니다. 큐 기반 비동기 발송 및 디바이스 토큰 관리를 지원합니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [환경변수](#환경변수)
+- [API](#api)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+| 항목         | 내용                                 |
+| ------------ | ------------------------------------ |
+| 프로바이더   | FCM (Firebase Cloud Messaging), APNs |
+| 발송 방식    | 큐 기반 비동기 발송 (dispatch loop)  |
+| 브로드캐스트 | 다중 계정 동시 발송 지원             |
+| 토큰 관리    | 만료 토큰 자동 비활성화              |
+
+> 기본 비활성화(`enabled: false`)입니다. Firebase 프로젝트 설정 후 활성화하세요.
+
+---
+
+## 설정
+
+`config.json`:
+
+```json
+{
+    "enabled": false,
+    "default": "main",
+    "workers": 2,
+    "queue_size": 50,
+    "dispatch_interval_sec": 5,
+    "max_retries": 3,
+    "providers": {
+        "main": {
+            "driver": "fcm",
+            "project_id": "${FCM_PROJECT_ID}",
+            "key_file": "${FCM_KEY_FILE}"
+        }
+    }
+}
+```
+
+### 설정 항목
+
+| 항목                        | 기본값  | 설명                              |
+| --------------------------- | ------- | --------------------------------- |
+| `enabled`                   | `false` | 플러그인 활성화                   |
+| `default`                   | `main`  | 사용할 프로바이더 키              |
+| `workers`                   | `2`     | 병렬 발송 워커 수                 |
+| `queue_size`                | `50`    | 최대 메모리 큐 크기               |
+| `dispatch_interval_sec`     | `5`     | 큐 처리 간격(초)                  |
+| `max_retries`               | `3`     | 실패 시 최대 재시도 횟수          |
+| `providers.main.project_id` | —       | Firebase 프로젝트 ID              |
+| `providers.main.key_file`   | —       | Firebase 서비스 계정 키 파일 경로 |
+
+---
+
+## 환경변수
+
+```env
+FCM_PROJECT_ID=firebase-project-id
+FCM_KEY_FILE=/path/to/firebase-service-account.json
+```
+
+### Firebase 서비스 계정 키 발급
+
+1. [Firebase 콘솔](https://console.firebase.google.com) → 프로젝트 설정 → 서비스 계정
+2. "새 비공개 키 생성" → JSON 다운로드
+3. 서버에 파일 저장 후 `FCM_KEY_FILE` 경로 설정
+
+---
+
+## API
+
+기본 경로: `/api/v1/push`
+
+| 메서드   | 경로           | 인증        | 설명                        |
+| -------- | -------------- | ----------- | --------------------------- |
+| `POST`   | `/send`        | 로그인 필요 | 단일 계정 푸시 발송         |
+| `POST`   | `/broadcast`   | 로그인 필요 | 다중 계정 브로드캐스트 발송 |
+| `GET`    | `/status/:seq` |             | 발송 상태 조회              |
+| `POST`   | `/device`      | JWT 선택    | 디바이스 토큰 등록/갱신     |
+| `DELETE` | `/device/:seq` | JWT 선택    | 디바이스 비활성화           |
+
+### POST /send 요청 바디
+
+```json
+{
+    "account_seq": 1,
+    "title": "새 메시지 도착",
+    "body": "홍길동님에게 메시지가 왔습니다.",
+    "data": {
+        "type": "message",
+        "target_seq": 42
+    }
+}
+```
+
+### POST /broadcast 요청 바디
+
+```json
+{
+    "account_seqs": [1, 2, 3],
+    "title": "공지사항",
+    "body": "서비스 점검 안내입니다.",
+    "data": { "type": "notice" }
+}
+```
+
+### POST /device 요청 바디
+
+```json
+{
+    "token": "FCM_디바이스_토큰",
+    "platform": "android",
+    "app_version": "1.2.0"
+}
+```
+
+`platform` 값: `android`, `ios`, `web`
+
+### 발송 상태 값
+
+| 상태         | 설명                |
+| ------------ | ------------------- |
+| `pending`    | 큐 대기 중          |
+| `processing` | 발송 시도 중        |
+| `sent`       | 발송 완료           |
+| `failed`     | 최대 재시도 후 실패 |
+
+---
+
+## 운영 팁
+
+- 만료된 FCM 토큰은 발송 실패 후 자동 비활성화됨 → 클라이언트 앱 업데이트 시 토큰 재등록 필요
+- `broadcast` 발송 시 대상 수에 비례하여 처리 시간 증가 — 대량 발송은 배치로 분리 권장
+- Firebase 서비스 계정 키 파일은 git에 커밋하지 말고 별도 보안 저장소 관리
+- iOS 발송 시 APNs 인증서 설정이 별도 필요 (Firebase 콘솔 → APNs 인증서 업로드)

package/src/app/plugins/push/entities/push_log.json

@@ -0,0 +1,86 @@
+{
+    "name": "push_log",
+    "description": "푸시 알림 발송 이력. 발송 결과 추적 및 재시도 관리용. account_seq(JWT) 또는 device_id(HMAC) 중 하나 존재. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "license_scope": false,
+    "hard_delete": true,
+    "history_ttl": 30,
+    "compress": true,
+    "fields": {
+        "account_seq": {
+            "index": true,
+            "comment": "수신자 account seq (JWT 인증 시. nullable)"
+        },
+        "attempt_time": {
+            "index": true,
+            "comment": "처리 시작(claim) 시각 — 비정상 종료 감지용"
+        },
+        "body": {
+            "comment": "알림 본문"
+        },
+        "device_id": {
+            "index": true,
+            "comment": "대상 디바이스 ID (HMAC 인증 시. nullable)",
+            "type": "varchar(255)"
+        },
+        "device_seq": {
+            "index": true,
+            "comment": "대상 디바이스 seq (account_device.seq)"
+        },
+        "device_token": {
+            "comment": "발송 시점 디바이스 토큰 스냅샷 (FCM registration token 또는 APNs device token)"
+        },
+        "error_message": {
+            "comment": "실패 시 오류 메시지",
+            "type": "varchar(500)"
+        },
+        "platform": {
+            "index": true,
+            "comment": "발송 채널",
+            "type": [
+                "fcm",
+                "apns",
+                "web"
+            ]
+        },
+        "push_data": {
+            "comment": "커스텀 페이로드 JSON 문자열",
+            "type": "varchar(2000)"
+        },
+        "ref_entity": {
+            "index": true,
+            "comment": "트리거 엔티티명"
+        },
+        "ref_seq": {
+            "index": true,
+            "comment": "트리거 레코드 seq"
+        },
+        "retry_count": {
+            "index": true,
+            "comment": "재시도 횟수",
+            "type": "uint",
+            "default": 0
+        },
+        "sent_time": {
+            "index": true,
+            "comment": "발송 완료 시각"
+        },
+        "status": {
+            "index": true,
+            "comment": "발송 상태",
+            "type": [
+                "pending",
+                "processing",
+                "sent",
+                "delivered",
+                "failed",
+                "expired"
+            ],
+            "default": "pending",
+            "required": true
+        },
+        "title": {
+            "index": true,
+            "comment": "알림 제목"
+        }
+    }
+}

package/src/app/plugins/push/entities/push_msg.json

@@ -0,0 +1,56 @@
+{
+    "name": "push_msg",
+    "description": "시스템 푸시 트리거 엔티티. insert 시 push hook로 비동기 발송. account_seq(JWT) 또는 device_id(HMAC) 중 하나 필수. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "fields": {
+        "account_seq": {
+            "index": true,
+            "comment": "수신자 account seq (JWT 인증 시 필수. HMAC 인증은 device_id 사용)",
+            "required": true
+        },
+        "device_id": {
+            "index": true,
+            "comment": "대상 디바이스 ID (HMAC 인증 시. 기기단위로 account 없이 푸시 발송)",
+            "type": "varchar(255)"
+        },
+        "title": {
+            "index": true,
+            "comment": "푸시 제목",
+            "required": true
+        },
+        "message": {
+            "comment": "푸시 본문",
+            "nullable": true
+        },
+        "ref_entity": {
+            "comment": "참조 엔티티명",
+            "nullable": true
+        },
+        "ref_seq": {
+            "comment": "참조 레코드 seq",
+            "nullable": true
+        },
+        "msg_data": {
+            "comment": "추가 데이터(JSON 문자열)",
+            "type": "varchar(2000)",
+            "nullable": true
+        }
+    },
+    "hooks": {
+        "after_insert": [
+            {
+                "type": "push",
+                "target_account_seq": "account_seq",
+                "target_device_id": "device_id",
+                "comment": "account_seq 있으면 계정 기반 발송, 없으면 device_id 기반 발송",
+                "title": "${new.title}",
+                "push_body": "${new.message}",
+                "push_data": {
+                    "push_msg_seq": "${new.seq}",
+                    "ref_entity": "${new.ref_entity}",
+                    "ref_seq": "${new.ref_seq}",
+                    "msg_data": "${new.msg_data}"
+                }
+            }
+        ]
+    }
+}