create-entity-app-server 0.0.3

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

@@ -0,0 +1,165 @@
+# SMTP 플러그인
+
+이메일 발송 기능을 제공합니다.  
+앱 서버에서 로컬 HTML 템플릿을 렌더링한 뒤 Go 엔티티서버로 전달합니다.  
+라우트에 등록되지 않은 `/api/v1/smtp/*` 경로는 Go 서버로 자동 패스스루됩니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [동작 방식](#동작-방식)
+- [API](#api)
+- [이메일 템플릿](#이메일-템플릿)
+
+---
+
+## 개요
+
+| 항목             | 내용                                           |
+| ---------------- | ---------------------------------------------- |
+| 기본 경로        | `/api/v1/smtp`                                 |
+| 설정 파일        | `config.json`                                  |
+| 활성화 기본값    | `true`                                         |
+| 이메일 발송 주체 | Go 엔티티서버 (앱 서버는 템플릿 렌더링만 처리) |
+
+---
+
+## 설정
+
+설정 파일: `src/app/plugins/smtp/config.json`
+
+| 키        | 기본값 | 설명                   |
+| --------- | ------ | ---------------------- |
+| `enabled` | `true` | 플러그인 활성화 여부   |
+| `deploy`  | `true` | 빌드 배포 포함 여부    |
+| `minify`  | `true` | 빌드 시 코드 압축 여부 |
+
+> SMTP 서버 주소·계정 등 실제 메일 발송 설정은 Go 엔티티서버의 `configs/smtp.json`에서 관리합니다.  
+> 앱 서버에는 별도의 SMTP 환경변수가 없습니다.
+
+---
+
+## 동작 방식
+
+```
+클라이언트
+    │
+    ▼
+POST /api/v1/smtp/send (앱 서버)
+    │  templateName 지정 시 로컬 templates/ 에서 HTML 렌더링
+    │  body_html/body_text 직접 지정 시 그대로 전달
+    ▼
+Go 엔티티서버 (실제 SMTP 발송)
+    │
+    ▼
+이메일 발송 결과 → sms_log / mail_log 기록
+```
+
+**직접 패스스루 경로**
+
+라우트에 등록되어 있지 않은 `/api/v1/smtp/*` 경로(예: `/api/v1/smtp/templates`, `/api/v1/smtp/logs` 등)는 `system/proxy/register.ts`에 의해 Go 서버로 그대로 전달됩니다.
+
+---
+
+## API
+
+기본 경로: `/api/v1/smtp`
+
+| 메서드 | 경로                              | 인증 | 설명               |
+| ------ | --------------------------------- | ---- | ------------------ |
+| `POST` | [`/send`](#post-send)             |      | 이메일 발송        |
+| `GET`  | [`/status/:seq`](#get-status-seq) |      | 발송 상태 조회     |
+| 기타   | `/api/v1/smtp/*`                  |      | Go 서버로 패스스루 |
+
+---
+
+### POST /send
+
+로컬 템플릿 렌더링 후 Go 서버 경유로 이메일을 발송합니다.
+
+**요청 Body**
+
+| 필드           | 타입     | 필수 | 설명                               |
+| -------------- | -------- | ---- | ---------------------------------- |
+| `to`           | string[] | ✅   | 수신자 이메일 주소 목록            |
+| `subject`      | string   | ✅   | 메일 제목                          |
+| `templateName` | string   |      | 로컬 템플릿 이름 (확장자 제외)     |
+| `templateData` | object   |      | 템플릿에 주입할 데이터             |
+| `body_html`    | string   |      | HTML 본문 (templateName 미사용 시) |
+| `body_text`    | string   |      | 텍스트 본문                        |
+| `cc`           | string[] |      | 참조                               |
+| `bcc`          | string[] |      | 숨은 참조                          |
+| `reply_to`     | string   |      | 회신 주소                          |
+
+**templateName 동작**
+
+`templateName`이 지정되면 `templates/{templateName}.html`을 불러와 `templateData`로 렌더링한 결과를 `body_html`로 사용합니다.
+
+**응답 예시**
+
+```json
+{
+    "success": true,
+    "data": {
+        "seq": 1042
+    }
+}
+```
+
+---
+
+### GET /status/:seq
+
+Go 엔티티서버에서 이메일 발송 상태를 조회합니다.
+
+**경로 파라미터**
+
+| 파라미터 | 타입   | 설명          |
+| -------- | ------ | ------------- |
+| `seq`    | number | 발송 기록 SEQ |
+
+**응답 예시**
+
+```json
+{
+    "success": true,
+    "data": {
+        "seq": 1042,
+        "state": "sent",
+        "sent_at": "2025-01-15T09:00:00Z"
+    }
+}
+```
+
+---
+
+## 이메일 템플릿
+
+템플릿 파일 위치: `src/app/plugins/smtp/templates/`
+
+| 파일          | 설명                                    |
+| ------------- | --------------------------------------- |
+| `layout.html` | 공통 레이아웃 (모든 템플릿의 기본 구조) |
+
+### 템플릿 추가 방법
+
+1. `templates/` 폴더에 `.html` 파일 생성
+2. `POST /send` 요청 시 `templateName`에 파일명(확장자 제외) 지정
+3. `templateData`로 변수 데이터 주입
+
+**예시**
+
+```json
+{
+    "to": ["user@example.com"],
+    "subject": "회원가입 완료",
+    "templateName": "welcome",
+    "templateData": {
+        "name": "홍길동",
+        "loginUrl": "https://example.com/login"
+    }
+}
+```

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

@@ -0,0 +1,52 @@
+/**
+ * SMTP API 핸들러
+ *
+ * 앱 서버가 직접 처리하는 이유:
+ *  - 로컬 템플릿(templates/*.html) 렌더링 후 body_html을 완성하여 Go 서버로 전달
+ *  - 프록시 패스스루로는 앱 서버 로컬 파일에 접근 불가
+ *
+ * 라우트에 없는 /api/v1/smtp/* 경로는 proxy/register.ts가 Go 서버로 패스스루한다.
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail, sendEmail, entityServer } from "@gateway/api";
+import type { SendEmailParams } from "@gateway/api";
+
+// ─── 핸들러 ──────────────────────────────────────────────────────────────────
+
+/**
+ * POST /api/v1/smtp/send
+ *
+ * templateName이 지정되면 로컬 templates/ 에서 렌더링 후 Go 서버에 전달.
+ * templateName 없이 body_html/body_text만 지정하면 그대로 전달.
+ */
+export async function handleSend(request: FastifyRequest, reply: FastifyReply) {
+    const params = (request.body ?? {}) as SendEmailParams;
+
+    if (!params.to || params.to.length === 0) {
+        return reply.status(400).send(fail("to is required"));
+    }
+
+    const seq = await sendEmail(params);
+    return ok({ seq });
+}
+
+/**
+ * GET /api/v1/smtp/status/:seq
+ *
+ * Go 서버에 발송 상태를 조회한다.
+ */
+export async function handleStatus(
+    request: FastifyRequest,
+    reply: FastifyReply,
+) {
+    const { seq } = request.params as { seq: string };
+    const seqNum = Number(seq);
+
+    if (!seqNum || seqNum <= 0) {
+        return reply.status(400).send(fail("Invalid seq"));
+    }
+
+    const result = await entityServer.smtpStatus(seqNum);
+    return ok(result);
+}

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

@@ -0,0 +1,33 @@
+/**
+ * SMTP 플러그인
+ *
+ * 앱 서버 내 모든 이메일 발송에 사용할 공유 레이아웃을 등록한다.
+ * 알파벳 순 플러그인 로드 중 초기화되며, 이후의 모든 renderTemplate 호출에서
+ * plugins/smtp/templates/layout.html 을 공통 래퍼로 사용한다.
+ *
+ * HTTP 라우트는 routes.ts 에서 등록하며, proxy/register.ts 의 패스스루보다
+ * 먼저 처리된다 (system/routes/loader.ts → system/proxy/register.ts 순서).
+ *
+ *  - POST /api/v1/smtp/send    → 로컬 템플릿 렌더링 후 Go 서버로 발송
+ *  - GET  /api/v1/smtp/status/:seq → Go 서버에 발송 상태 조회
+ *
+ * routes.ts에 없는 /api/v1/smtp/* 경로는 Go 서버로 패스스루된다.
+ */
+
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { setSharedLayout } from "@gateway/api";
+import { logger } from "@gateway/api";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default fp(
+    async (_app: FastifyInstance) => {
+        const layoutPath = join(__dirname, "templates", "layout.html");
+        setSharedLayout(layoutPath);
+        logger.debug({ layout: layoutPath }, "Email shared layout registered");
+    },
+    { name: "smtp" },
+);

package/src/app/plugins/smtp/routes.ts

@@ -0,0 +1,19 @@
+/**
+ * SMTP 라우트 테이블
+ * 등록 경로: /api/v1/smtp/*
+ *
+ * 여기서 처리되지 않는 /api/v1/smtp/* 경로는
+ * system/proxy/register.ts 에 의해 Go 서버로 패스스루된다.
+ */
+
+import type { FastifyInstance } from "fastify";
+import * as h from "./handlers.ts";
+
+/** SMTP 라우트를 등록한다 */
+export default async function smtpRoutes(app: FastifyInstance) {
+    // POST /api/v1/smtp/send — 로컬 템플릿 렌더링 후 Go 서버로 발송
+    app.post("/send", h.handleSend);
+
+    // GET /api/v1/smtp/status/:seq — 발송 상태 조회
+    app.get("/status/:seq", h.handleStatus);
+}

package/src/app/plugins/smtp/templates/layout.html

@@ -0,0 +1,50 @@
+<!DOCTYPE html>
+<html lang="ko">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <!--[if mso]>
+    <noscript>
+        <xml>
+            <o:OfficeDocumentSettings>
+                <o:PixelsPerInch>96</o:PixelsPerInch>
+            </o:OfficeDocumentSettings>
+        </xml>
+    </noscript>
+    <![endif]-->
+</head>
+
+<body style="margin: 0; padding: 0; background-color: #f4f4f7; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; -webkit-text-size-adjust: 100%; -ms-text-size-adjust: 100%;">
+    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background-color: #f4f4f7;">
+        <tr>
+            <td align="center" style="padding: 24px 16px;">
+                <table role="presentation" width="600" cellpadding="0" cellspacing="0" style="max-width: 600px; width: 100%; background-color: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.08);">
+                    <!-- Header -->
+                    <tr>
+                        <td style="padding: 32px 40px 24px; border-bottom: 1px solid #eaeaea;">
+                            <span style="font-size: 18px; font-weight: 700; color: #1a1a2e;">${app_name|Entity Server}</span>
+                        </td>
+                    </tr>
+                    <!-- Content -->
+                    <tr>
+                        <td style="padding: 32px 40px;">
+                            ${content}
+                        </td>
+                    </tr>
+                    <!-- Footer -->
+                    <tr>
+                        <td style="padding: 24px 40px; border-top: 1px solid #eaeaea; background-color: #fafafa;">
+                            <p style="margin: 0; font-size: 12px; color: #999; line-height: 1.6;">
+                                이 이메일은 자동 발송되었습니다. 회신하지 마세요.<br>
+                                &copy; ${company|Entity Server}
+                            </p>
+                        </td>
+                    </tr>
+                </table>
+            </td>
+        </tr>
+    </table>
+</body>
+
+</html>

package/src/app/plugins/smtp/types/config.ts

@@ -0,0 +1,8 @@
+/** plugins/smtp/config.json 스키마 */
+export interface SmtpPluginConfig {
+    enabled: boolean; // 라우트 활성화 여부 (false면 routes.ts 등록 안 됨)
+
+    deploy?: boolean; // 빌드 시 dist에서 제외 여부
+
+    minify?: boolean; // 빌드 시 난독화 여부
+}

package/src/app/plugins/smtp/types/index.ts

@@ -0,0 +1 @@
+export * from "./config.ts";

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

@@ -0,0 +1,60 @@
+{
+    "enabled": false,
+    "default": "barobill",
+    "workers": 2,
+    "queue_size": 100,
+    "dispatch_interval_sec": 10,
+    "max_retries": 3,
+    "providers": {
+        "barobill": {
+            "driver": "barobill",
+            "_comment": "바로빌",
+            "cert_key": "${TAXINVOICE_CERT_KEY}",
+            "corp_num": "${TAXINVOICE_CORP_NUM}",
+            "user_id": "${TAXINVOICE_USER_ID}",
+            "api_endpoint": "https://barobill.co.kr/TAPI/TaxInvoiceService.asmx",
+            "timeout_sec": 30
+        },
+        "ezero": {
+            "driver": "ezero",
+            "_comment": "이지로 (EZERO)",
+            "cert_key": "${EZERO_CERT_KEY}",
+            "corp_num": "${EZERO_CORP_NUM}",
+            "user_id": "${EZERO_USER_ID}",
+            "api_endpoint": "https://www.ezero.co.kr/tax-invoice/api",
+            "timeout_sec": 30
+        },
+        "popbill": {
+            "driver": "popbill",
+            "_comment": "팝빌 (Popbill)",
+            "link_id": "${POPBILL_LINK_ID}",
+            "secret_key": "${POPBILL_SECRET_KEY}",
+            "corp_num": "${POPBILL_CORP_NUM}",
+            "api_url": "https://www.popbill.com",
+            "timeout_sec": 30
+        },
+        "ktnet": {
+            "driver": "ktnet",
+            "_comment": "KT-NET 세금계산서",
+            "cert_key": "${KTNET_CERT_KEY}",
+            "corp_num": "${KTNET_CORP_NUM}",
+            "user_id": "${KTNET_USER_ID}",
+            "api_endpoint": "https://www.b2b.kt.com/einvoice",
+            "timeout_sec": 30
+        }
+    },
+    "nts": {
+        "auto_send": false,
+        "taxation_option": 1,
+        "taxation_add_tax_allow": 0,
+        "tax_exemption_option": 1,
+        "tax_exemption_add_tax_allow": 0
+    },
+    "notify": ["log"],
+    "sync": {
+        "enabled": false,
+        "interval_sec": 600,
+        "state_sync_interval_min": 10,
+        "max_list_days": 200
+    }
+}

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

@@ -0,0 +1,35 @@
+{
+    "_comment": "전자세금계산서 플러그인 — 바로빌 연동, 국세청 자동 전송·상태 동기화·발행 큐 처리 지원",
+    "enabled": false,
+    "default": "barobill",
+    "workers": 2,
+    "queue_size": 100,
+    "dispatch_interval_sec": 10,
+    "max_retries": 3,
+    "providers": {
+        "barobill": {
+            "driver": "barobill",
+            "cert_key": "${TAXINVOICE_CERT_KEY}",
+            "corp_num": "${TAXINVOICE_CORP_NUM}",
+            "user_id": "${TAXINVOICE_USER_ID}",
+            "api_endpoint": "https://barobill.co.kr/TAPI/TaxInvoiceService.asmx",
+            "timeout_sec": 30
+        }
+    },
+    "nts": {
+        "auto_send": false,
+        "taxation_option": 1,
+        "taxation_add_tax_allow": 0,
+        "tax_exemption_option": 1,
+        "tax_exemption_add_tax_allow": 0
+    },
+    "notify": ["log"],
+    "sync": {
+        "enabled": false,
+        "interval_sec": 600,
+        "state_sync_interval_min": 10,
+        "max_list_days": 200
+    },
+    "deploy": true,
+    "minify": false
+}

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

@@ -0,0 +1,117 @@
+/**
+ * 전자세금계산서 설정 로더
+ *
+ * 플러그인 디렉토리의 config.json 로드 + ${ENV_VAR} 치환 + 검증
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import type { TaxInvoiceConfig } from "./types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+/** 세금계산서 설정을 로드한다 */
+export function loadTaxInvoiceConfig(): TaxInvoiceConfig | null {
+    if (!existsSync(CONFIG_PATH)) return null;
+
+    const raw = readFileSync(CONFIG_PATH, "utf-8");
+    const replaced = raw.replace(
+        /\$\{(\w+)\}/g,
+        (_, key) => process.env[key] ?? "",
+    );
+    const config: TaxInvoiceConfig = JSON.parse(replaced);
+
+    if (config.enabled === false) return null;
+
+    // 기본값 보정
+    config.workers ??= 2;
+    config.queue_size ??= 100;
+    config.dispatch_interval_sec ??= 10;
+    config.max_retries ??= 3;
+    config.nts ??= {
+        auto_send: false,
+        taxation_option: 1,
+        taxation_add_tax_allow: 0,
+        tax_exemption_option: 1,
+        tax_exemption_add_tax_allow: 0,
+    };
+    config.sync ??= {
+        enabled: false,
+        interval_sec: 0,
+        state_sync_interval_min: 10,
+        max_list_days: 200,
+    };
+
+    if (!config.default && Object.keys(config.providers ?? {}).length === 1) {
+        config.default = Object.keys(config.providers)[0];
+    }
+
+    // 검증
+    if (!Object.keys(config.providers ?? {}).length) {
+        throw new Error(
+            "taxinvoice config: at least one provider must be configured",
+        );
+    }
+    if (!config.default) {
+        throw new Error(
+            "taxinvoice config: 'default' provider driver must be specified",
+        );
+    }
+    if (!(config.default in config.providers)) {
+        throw new Error(
+            `taxinvoice config: default provider "${config.default}" not found in providers`,
+        );
+    }
+
+    for (const [name, p] of Object.entries(config.providers)) {
+        if (!p.driver)
+            throw new Error(
+                `taxinvoice config: provider "${name}": driver is required`,
+            );
+        if (!p.api_endpoint)
+            throw new Error(
+                `taxinvoice config: provider "${name}" (${p.driver}): api_endpoint is required`,
+            );
+
+        switch (p.driver) {
+            case "barobill":
+                if (!p.cert_key || !p.corp_num || !p.user_id)
+                    throw new Error(
+                        `taxinvoice config: barobill requires cert_key, corp_num, user_id`,
+                    );
+                break;
+            case "popbill":
+                if (!p.link_id || !p.secret_key || !p.corp_num)
+                    throw new Error(
+                        `taxinvoice config: popbill requires link_id, secret_key, corp_num`,
+                    );
+                break;
+            case "bolta":
+                if (!p.api_key || !p.customer_key)
+                    throw new Error(
+                        `taxinvoice config: bolta requires api_key, customer_key`,
+                    );
+                break;
+            case "smartbill":
+                if (!p.api_key || !p.corp_num)
+                    throw new Error(
+                        `taxinvoice config: smartbill requires api_key, corp_num`,
+                    );
+                break;
+            case "esero":
+                if (!p.corp_num || !p.cert_path)
+                    throw new Error(
+                        `taxinvoice config: esero requires corp_num, cert_path`,
+                    );
+                break;
+            default:
+                throw new Error(
+                    `taxinvoice config: unknown driver "${p.driver}"`,
+                );
+        }
+    }
+
+    return config;
+}