create-entity-app-server 0.0.3

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

@@ -0,0 +1,11 @@
+{
+  "_comment": "친구톡 설정 — enabled: false로 비활성화 상태",
+  "_note": "친구톡은 알림톡과 달리 사전 등록 템플릿 코드 없이 자유 형식으로 발송합니다. 본문 템플릿(content 패턴)은 templates/notification/friendtalk.json에 정의합니다.",
+  "_template_file": "templates/notification/friendtalk.json",
+  "enabled": false,
+  "workers": 2,
+  "ad_prefix": "(광고)",
+  "default_ad": true,
+  "deploy": true,
+  "minify": false
+}

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

@@ -0,0 +1,70 @@
+/**
+ * 친구톡 설정 로더
+ *
+ * 플러그인 디렉토리의 config.json을 읽습니다.
+ *
+ * ⚠️  친구톡은 알림톡과 달리 카카오 사전 등록 템플릿 코드가 필요하지 않습니다.
+ *     자유 형식(content) 으로 발송하며, 본문 패턴은
+ *     templates/notification/friendtalk.json에서 별도 로드합니다.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "@gateway/api";
+import type {
+    FriendTalkConfig,
+    FriendTalkTemplate,
+} from "../alimtalk/types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+const TEMPLATE_PATH = join(__dirname, "templates", "friendtalk.json");
+
+const DEFAULTS: FriendTalkConfig = {
+    enabled: false,
+    workers: 2,
+    ad_prefix: "(광고)",
+    default_ad: true,
+    templates: [],
+};
+
+/** 친구톡 본문 템플릿 목록을 templates/notification/friendtalk.json에서 로드한다 */
+function loadFriendTalkTemplates(): FriendTalkTemplate[] {
+    if (!existsSync(TEMPLATE_PATH)) {
+        return [];
+    }
+    try {
+        const raw = readFileSync(TEMPLATE_PATH, "utf-8");
+        return JSON.parse(raw) as FriendTalkTemplate[];
+    } catch (err) {
+        logger.error({ err }, "Failed to load friendtalk templates");
+        return [];
+    }
+}
+
+/** 친구톡 설정을 로드한다 */
+export function loadFriendTalkConfig(): FriendTalkConfig {
+    if (!existsSync(CONFIG_PATH)) {
+        return DEFAULTS;
+    }
+
+    try {
+        const raw = readFileSync(CONFIG_PATH, "utf-8");
+        const cfg = JSON.parse(raw) as FriendTalkConfig;
+        return {
+            enabled: cfg.enabled ?? DEFAULTS.enabled,
+            workers: cfg.workers > 0 ? cfg.workers : DEFAULTS.workers,
+            ad_prefix: cfg.ad_prefix || DEFAULTS.ad_prefix,
+            default_ad: cfg.default_ad ?? DEFAULTS.default_ad,
+            templates: loadFriendTalkTemplates(),
+        };
+    } catch (err) {
+        logger.error(
+            { err },
+            "Failed to load friendtalk config, using defaults",
+        );
+        return DEFAULTS;
+    }
+}

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

@@ -0,0 +1,110 @@
+# 친구톡 플러그인 (Friendtalk)
+
+카카오 친구톡을 큐 기반으로 발송합니다. 알림톡과 달리 사전 등록 템플릿 코드 없이 자유 형식으로 발송 가능합니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [알림톡 vs 친구톡](#알림톡-vs-친구톡)
+- [설정](#설정)
+- [환경변수](#환경변수)
+- [API](#api)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+| 항목       | 내용                                |
+| ---------- | ----------------------------------- |
+| 발송 방식  | 큐 기반 비동기 발송 (dispatch loop) |
+| 프로바이더 | 카카오 비즈 (알리고 등 중계사 경유) |
+| 템플릿     | 자유 형식 (사전 카카오 검수 불필요) |
+
+> 기본 비활성화(`enabled: false`) 상태입니다. 카카오 비즈니스 채널 설정 후 활성화하세요.
+
+---
+
+## 알림톡 vs 친구톡
+
+| 항목      | 알림톡                | 친구톡                         |
+| --------- | --------------------- | ------------------------------ |
+| 템플릿    | 카카오 사전 등록 필수 | 자유 작성                      |
+| 수신 대상 | 카카오톡 사용자 전체  | 채널 친구 추가한 사용자만      |
+| 광고 여부 | 정보성만 허용         | 정보성·광고성 모두 가능        |
+| 발송 비용 | 상대적으로 저렴       | 상대적으로 비쌈                |
+| 본문 형식 | 텍스트 · 버튼         | 텍스트 · 이미지 · 카드 등 다양 |
+
+---
+
+## 설정
+
+`config.json`:
+
+```json
+{
+    "enabled": false,
+    "workers": 2,
+    "ad_prefix": "(광고)",
+    "default_ad": true
+}
+```
+
+### 설정 항목
+
+| 항목         | 기본값   | 설명                                |
+| ------------ | -------- | ----------------------------------- |
+| `enabled`    | `false`  | 플러그인 활성화 여부                |
+| `workers`    | `2`      | 병렬 발송 워커 수                   |
+| `ad_prefix`  | `(광고)` | 광고 메시지 앞에 자동 추가되는 문구 |
+| `default_ad` | `true`   | 기본으로 광고 접두사 포함 여부      |
+
+---
+
+## 환경변수
+
+친구톡 발송은 알림톡과 동일한 알리고 계정을 공유합니다.
+
+```env
+ALIMTALK_SENDER_KEY=카카오_채널_발신프로필_키
+ALIGO_API_KEY=알리고_API_키
+ALIGO_USER_ID=알리고_사용자_아이디
+```
+
+---
+
+## API
+
+기본 경로: `/api/v1/friendtalk`
+
+| 메서드 | 경로    | 인증        | 설명        |
+| ------ | ------- | ----------- | ----------- |
+| `POST` | `/send` | 로그인 필요 | 친구톡 발송 |
+
+### POST /send 요청 바디
+
+```json
+{
+    "receiver": "01012345678",
+    "content": "안녕하세요! 이번 주 특가 상품을 소개합니다.",
+    "ad": true,
+    "buttons": [
+        {
+            "name": "자세히 보기",
+            "type": "WL",
+            "url_mobile": "https://example.com/event"
+        }
+    ]
+}
+```
+
+---
+
+## 운영 팁
+
+- 채널 친구 추가를 하지 않은 사용자에게는 발송 불가 → `failed` 처리
+- 광고성 메시지는 `ad: true`로 설정하고 `(광고)` 접두사가 자동 추가됨
+- 야간(오후 9시 ~ 오전 8시) 광고 메시지 발송 금지 (법적 규정)
+- 정보성 메시지는 `ad: false`로 설정 시 야간 발송 가능

package/src/app/plugins/friendtalk/entities/friendtalk_log.json

@@ -0,0 +1,89 @@
+{
+    "name": "friendtalk_log",
+    "description": "친구톡(브랜드메시지) 발송 로그 — 워커가 소비하는 DB 큐 역할을 합니다. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "history": false,
+    "read_only": true,
+    "compress": true,
+    "fields": {
+        "status": {
+            "index": true,
+            "type": [
+                "pending",
+                "processing",
+                "sent",
+                "failed",
+                "expired"
+            ],
+            "default": "pending",
+            "comment": "발송 상태"
+        },
+        "msg_type": {
+            "index": true,
+            "type": [
+                "text",
+                "image",
+                "wide_image",
+                "wide_item_list",
+                "carousel"
+            ],
+            "default": "text"
+        },
+        "receiver": {
+            "index": true,
+            "hash": true,
+            "comment": "수신자 전화번호",
+            "required": true
+        },
+        "friendtalk_msg_seq": {
+            "index": true,
+            "comment": "friendtalk_msg 참조 seq"
+        },
+        "content": {
+            "type": "text",
+            "comment": "메시지 본문"
+        },
+        "image_url": {
+            "comment": "이미지 URL"
+        },
+        "image_link": {
+            "comment": "이미지 클릭 시 이동 URL"
+        },
+        "is_ad": {
+            "type": "bool",
+            "default": true,
+            "comment": "광고성 메시지 여부"
+        },
+        "buttons_json": {
+            "type": "text",
+            "comment": "버튼 목록 JSON"
+        },
+        "carousel_json": {
+            "type": "text",
+            "comment": "캐러셀 데이터 JSON"
+        },
+        "items_json": {
+            "type": "text",
+            "comment": "와이드 아이템 리스트 JSON"
+        },
+        "header": {
+            "comment": "와이드 아이템 리스트 헤더"
+        },
+        "provider": {
+            "comment": "사용 프로바이더"
+        },
+        "provider_msg_id": {
+            "comment": "프로바이더 메시지 ID"
+        },
+        "error_message": {
+            "type": "text",
+            "comment": "오류 메시지"
+        },
+        "retry_count": {
+            "type": "uint",
+            "default": 0
+        },
+        "sent_at": {
+            "type": "string"
+        }
+    }
+}

package/src/app/plugins/friendtalk/entities/friendtalk_msg.json

@@ -0,0 +1,91 @@
+{
+    "name": "friendtalk_msg",
+    "description": "친구톡(브랜드메시지) 발송 트리거 엔티티 — Hook 또는 API를 통해 생성되면 친구톡 발송이 시작됩니다. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "history": false,
+    "fields": {
+        "receiver": {
+            "index": true,
+            "hash": true,
+            "comment": "수신자 전화번호",
+            "required": true
+        },
+        "msg_type": {
+            "index": true,
+            "type": [
+                "text",
+                "image",
+                "wide_image",
+                "wide_item_list",
+                "carousel"
+            ],
+            "default": "text"
+        },
+        "status": {
+            "index": true,
+            "type": [
+                "pending",
+                "processing",
+                "sent",
+                "failed"
+            ],
+            "default": "pending"
+        },
+        "content": {
+            "type": "text",
+            "required": true,
+            "comment": "메시지 본문"
+        },
+        "image_url": {
+            "comment": "이미지 URL"
+        },
+        "image_link": {
+            "comment": "이미지 클릭 시 이동 URL"
+        },
+        "is_ad": {
+            "type": "bool",
+            "default": true,
+            "comment": "광고성 메시지 여부"
+        },
+        "buttons_json": {
+            "type": "text",
+            "comment": "버튼 목록 JSON"
+        },
+        "carousel_json": {
+            "type": "text",
+            "comment": "캐러셀 데이터 JSON"
+        },
+        "items_json": {
+            "type": "text",
+            "comment": "와이드 아이템 리스트 JSON"
+        },
+        "header": {
+            "comment": "와이드 아이템 리스트 헤더"
+        },
+        "provider": {
+            "comment": "프로바이더 키 (빈 값이면 default)"
+        },
+        "ref_entity": {
+            "comment": "참조 엔티티 이름"
+        },
+        "ref_seq": {
+            "type": "int"
+        }
+    },
+    "hooks": {
+        "after_insert": [
+            {
+                "type": "friendtalk",
+                "friendtalk_receiver": "${new.receiver}",
+                "friendtalk_content": "${new.content}",
+                "friendtalk_msg_type": "${new.msg_type}",
+                "friendtalk_image_url": "${new.image_url}",
+                "friendtalk_image_link": "${new.image_link}",
+                "friendtalk_is_ad": "${new.is_ad}",
+                "friendtalk_buttons_json": "${new.buttons_json}",
+                "friendtalk_carousel_json": "${new.carousel_json}",
+                "friendtalk_items_json": "${new.items_json}",
+                "friendtalk_header": "${new.header}"
+            }
+        ]
+    }
+}

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

@@ -0,0 +1,150 @@
+/**
+ * FriendTalkQuerier — Entity Server 어댑터
+ *
+ * entity-server-client를 통해 friendtalk_log, friendtalk_msg 엔티티에 접근.
+ */
+
+import { entityServer } from "@gateway/api";
+import { logger } from "@gateway/api";
+import type {
+    FriendTalkQuerier,
+    PendingFriendTalkLog,
+} from "../alimtalk/types/index.ts";
+
+export class FriendTalkEntityAdapter implements FriendTalkQuerier {
+    constructor(private readonly maxRetries: number = 3) {}
+
+    /** 친구톡 발송 로그를 Entity Server에 등록한다 */
+    async submitFriendTalkLog(data: Record<string, unknown>): Promise<void> {
+        await entityServer.submit("friendtalk_log", data);
+    }
+
+    /** 대기 중인 친구톡 발송 로그를 일괄 조회·점유한다 */
+    async claimPendingFriendTalkLogs(
+        limit: number,
+    ): Promise<PendingFriendTalkLog[]> {
+        const resp = await entityServer.list("friendtalk_log", {
+            status: "pending",
+            page: 1,
+            limit,
+            order: "seq",
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<
+            string,
+            unknown
+        >[];
+        const logs: PendingFriendTalkLog[] = [];
+
+        for (const item of items) {
+            const seq = Number(item.seq ?? 0);
+            if (seq <= 0) continue;
+
+            try {
+                await entityServer.submit("friendtalk_log", {
+                    seq,
+                    status: "processing",
+                });
+            } catch {
+                continue;
+            }
+
+            logs.push({
+                logSeq: seq,
+                provider: String(item.provider ?? ""),
+                msgType: String(item.msg_type ?? ""),
+                receiver: String(item.receiver ?? ""),
+                content: String(item.content ?? ""),
+                imageUrl: String(item.image_url ?? ""),
+                imageLink: String(item.image_link ?? ""),
+                isAd:
+                    String(item.is_ad) === "true" || String(item.is_ad) === "1",
+                buttonsJSON: String(item.buttons_json ?? ""),
+                carouselJSON: String(item.carousel_json ?? ""),
+                itemsJSON: String(item.items_json ?? ""),
+                header: String(item.header ?? ""),
+                retryCount: Number(item.retry_count ?? 0),
+                msgSeq: Number(item.friendtalk_msg_seq ?? 0),
+            });
+        }
+
+        return logs;
+    }
+
+    /** 친구톡 발송 로그 상태를 갱신한다 */
+    async updateFriendTalkLogStatus(
+        logSeq: number,
+        status: string,
+        providerMsgId: string,
+        errMsg: string,
+    ): Promise<void> {
+        const data: Record<string, unknown> = { seq: logSeq, status };
+        if (providerMsgId) data.provider_msg_id = providerMsgId;
+        if (errMsg) data.error_message = errMsg;
+        if (status === "sent") data.sent_at = new Date().toISOString();
+
+        await entityServer.submit("friendtalk_log", data);
+    }
+
+    /** 장기 처리 중인 친구톡 로그를 pending으로 초기화한다 */
+    async resetStaleFriendTalkLogs(): Promise<void> {
+        const resp = await entityServer.list("friendtalk_log", {
+            status: "processing",
+            page: 1,
+            limit: 1000,
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<
+            string,
+            unknown
+        >[];
+        let resetCount = 0;
+
+        for (const item of items) {
+            const seq = Number(item.seq ?? 0);
+            if (seq <= 0) continue;
+
+            const retryCount = Number(item.retry_count ?? 0);
+
+            if (retryCount >= this.maxRetries) {
+                await entityServer
+                    .submit("friendtalk_log", {
+                        seq,
+                        status: "failed",
+                        error_message: "max retries exceeded (stale recovery)",
+                    })
+                    .catch((err) =>
+                        logger.error(
+                            { err },
+                            `FriendTalk: stale log update failed seq=${seq}`,
+                        ),
+                    );
+                continue;
+            }
+
+            try {
+                await entityServer.submit("friendtalk_log", {
+                    seq,
+                    status: "pending",
+                });
+                resetCount++;
+            } catch {
+                /* skip */
+            }
+        }
+
+        if (resetCount > 0) {
+            logger.info(
+                `FriendTalk: reset ${resetCount} stale processing logs to pending`,
+            );
+        }
+    }
+
+    /** 친구톡 메시지 상태를 갱신한다 */
+    async updateFriendTalkMsgStatus(
+        msgSeq: number,
+        status: string,
+    ): Promise<void> {
+        await entityServer.submit("friendtalk_msg", { seq: msgSeq, status });
+    }
+}

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

@@ -0,0 +1,56 @@
+/**
+ * 친구톡 핸들러 구현
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail } from "@gateway/api";
+import type { AlimtalkButton } from "../alimtalk/types/index.ts";
+
+/** 친구톡 발송 요청을 큐에 등록한다 */
+export async function send(req: FastifyRequest, reply: FastifyReply) {
+    const svc = req.server.alimtalkService;
+    if (!svc)
+        return reply.status(503).send(fail("FriendTalk service not available"));
+
+    const body = req.body as Record<string, unknown> | undefined;
+    const receiver = String(body?.receiver ?? "");
+    const content = String(body?.content ?? "");
+
+    if (!receiver || !content) {
+        return reply
+            .status(400)
+            .send(fail("receiver and content are required"));
+    }
+
+    const msgType = String(body?.msg_type ?? "text");
+
+    let isAd = true;
+    if (body?.is_ad !== undefined && body?.is_ad !== null) {
+        isAd = Boolean(body.is_ad);
+    }
+
+    let buttonsJSON = "";
+    const buttons = body?.buttons as AlimtalkButton[] | undefined;
+    if (buttons?.length) {
+        buttonsJSON = JSON.stringify(buttons);
+    }
+
+    await svc.enqueueFriendTalkJob({
+        provider: String(body?.provider ?? ""),
+        msgType,
+        receiver,
+        content,
+        imageUrl: String(body?.image_url ?? ""),
+        imageLink: String(body?.image_link ?? ""),
+        isAd,
+        buttonsJSON,
+        carouselJSON: String(body?.carousel_json ?? ""),
+        itemsJSON: String(body?.items_json ?? ""),
+        header: String(body?.header ?? ""),
+        refEntity: "",
+        refSeq: 0,
+        msgSeq: 0,
+    });
+
+    return reply.status(202).send(ok({ message: "friendtalk queued" }));
+}

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

@@ -0,0 +1,12 @@
+/**
+ * 친구톡 라우트 테이블
+ * 등록 경로: /api/v1/friendtalk/*
+ */
+
+import type { FastifyInstance } from "fastify";
+import * as h from "./handlers.ts";
+
+/** 친구톡 라우트를 Fastify에 등록한다 */
+export default async function friendtalkRoutes(app: FastifyInstance) {
+    app.post("/send", h.send);
+}

package/src/app/plugins/friendtalk/templates/friendtalk.json

@@ -0,0 +1,16 @@
+[
+    {
+        "code": "promo_banner",
+        "description": "프로모션 배너",
+        "msgType": "image",
+        "content": "안녕하세요 {{name}}님!\n지금 바로 {{discount}}% 할인 혜택을 받으세요.",
+        "variables": ["name", "discount"]
+    },
+    {
+        "code": "event_notice",
+        "description": "이벤트 공지",
+        "msgType": "text",
+        "content": "{{event_title}}\n\n{{event_desc}}\n\n기간: {{start_date}} ~ {{end_date}}",
+        "variables": ["event_title", "event_desc", "start_date", "end_date"]
+    }
+]

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

@@ -0,0 +1,6 @@
+{
+    "enabled": false,
+    "cron": "0 3 1 1,12 *",
+    "yearsAhead": 1,
+    "entity": "holiday"
+}

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

@@ -0,0 +1,10 @@
+{
+    "_comment": "공휴일 자동 동기화 플러그인 — 공공데이터포털 API로 연간 공휴일을 주기적으로 갱신합니다. apiKey 필수",
+    "enabled": true,
+    "cron": "0 3 1 1,12 *",
+    "yearsAhead": 1,
+    "entity": "holiday",
+    "apiKey": "${HOLIDAY_API_KEY}",
+    "deploy": true,
+    "minify": false
+}

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

@@ -0,0 +1,44 @@
+/**
+ * 공휴일 동기화 설정 로더
+ *
+ * 플러그인 디렉토리의 config.json을 읽어 HolidaysConfig를 반환합니다.
+ * 파일이 없거나 enabled: false이면 null을 반환합니다.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "@gateway/api";
+import type { HolidaysConfig } from "./types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+/** 공휴일 설정을 로드한다 */
+export function loadHolidaysConfig(): HolidaysConfig | 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 = JSON.parse(raw) as HolidaysConfig;
+
+        if (cfg.enabled === false) {
+            logger.info("Holidays plugin disabled in config");
+            return null;
+        }
+
+        return cfg;
+    } catch (err) {
+        logger.error({ err }, "Failed to load holidays config");
+        return null;
+    }
+}