create-entity-app-server 0.0.3

package/src/app/plugins/alimtalk/service.ts

@@ -0,0 +1,423 @@
+/**
+ * 알림톡 / 친구톡 발송 서비스
+ *
+ * Go의 goroutine+channel → Node.js의 setInterval + async queue 패턴으로 전환
+ *
+ * 흐름:
+ *  1. EnqueueJob() → alimtalk_log(pending) DB 저장
+ *  2. dispatchLoop (setInterval N초) → pending 조회 → processing으로 claim → processOne 호출
+ *  3. processOne → 프로바이더 API 발송 → alimtalk_log 상태 갱신 (sent/failed)
+ *  4. 서버 시작 시 → resetStaleLogs → processing → pending 되돌림
+ */
+
+import { logger } from "@gateway/api";
+import type {
+    AlimtalkConfig,
+    AlimtalkClient,
+    AlimtalkQuerier,
+    FriendTalkQuerier,
+    AlimtalkJob,
+    FriendTalkJob,
+    PendingAlimtalkLog,
+    PendingFriendTalkLog,
+    AlimtalkButton,
+    FriendTalkItem,
+    FriendTalkCarousel,
+    FRIENDTALK_TYPE_TEXT as _,
+} from "./types/index.ts";
+import { FRIENDTALK_TYPE_TEXT } from "./types/index.ts";
+import { TemplateCache } from "./template-cache.ts";
+import { WebhookProcessor } from "./webhook.ts";
+
+export class AlimtalkService {
+    private readonly config: AlimtalkConfig;
+    private readonly clients: Map<string, AlimtalkClient>;
+    private readonly templateCache: TemplateCache;
+
+    private querier: AlimtalkQuerier | null = null;
+    private friendTalkQuerier: FriendTalkQuerier | null = null;
+
+    private dispatchTimer: ReturnType<typeof setInterval> | null = null;
+    private friendTalkDispatchTimer: ReturnType<typeof setInterval> | null =
+        null;
+    private running = false;
+
+    /** AlimtalkService를 설정과 클라이언트로 초기화한다 */
+    constructor(config: AlimtalkConfig, clients: Map<string, AlimtalkClient>) {
+        this.config = config;
+        this.clients = clients;
+        this.templateCache = new TemplateCache();
+
+        if (config.templates) {
+            this.templateCache.loadFromConfig(config.templates);
+        }
+    }
+
+    // ─── Inject ──────────────────────────────────────────────────────────
+
+    /** 알림톡 Entity 어댑터를 설정한다 */
+    setQuerier(q: AlimtalkQuerier): void {
+        this.querier = q;
+    }
+
+    /** 친구톡 Entity 어댑터를 설정한다 */
+    setFriendTalkQuerier(q: FriendTalkQuerier): void {
+        this.friendTalkQuerier = q;
+    }
+
+    // ─── Start / Stop ────────────────────────────────────────────────────
+
+    /** 발송 디스패치 루프를 시작한다 */
+    async start(): Promise<void> {
+        if (!this.querier) {
+            logger.warn("Alimtalk: querier not set, service will not start");
+            return;
+        }
+
+        // stale 레코드 복구
+        try {
+            await this.querier.resetStaleAlimtalkLogs();
+        } catch (err) {
+            logger.warn({ err }, "Alimtalk: failed to reset stale logs");
+        }
+
+        // 알림톡 디스패치 루프
+        const intervalMs = (this.config.dispatch_interval_sec || 5) * 1000;
+        this.dispatchTimer = setInterval(() => {
+            this.dispatch().catch((err) =>
+                logger.error({ err }, "Alimtalk dispatch error"),
+            );
+        }, intervalMs);
+
+        // 친구톡 디스패치 루프
+        if (this.config.friendtalk?.enabled && this.friendTalkQuerier) {
+            try {
+                await this.friendTalkQuerier.resetStaleFriendTalkLogs();
+            } catch (err) {
+                logger.warn({ err }, "FriendTalk: failed to reset stale logs");
+            }
+
+            this.friendTalkDispatchTimer = setInterval(() => {
+                this.friendTalkDispatch().catch((err) =>
+                    logger.error({ err }, "FriendTalk dispatch error"),
+                );
+            }, intervalMs);
+        }
+
+        this.running = true;
+        logger.info(
+            "Alimtalk service started (interval=%ds, workers=async)",
+            this.config.dispatch_interval_sec || 5,
+        );
+    }
+
+    /** 발송 디스패치 루프를 중지한다 */
+    stop(): void {
+        if (this.dispatchTimer) {
+            clearInterval(this.dispatchTimer);
+            this.dispatchTimer = null;
+        }
+        if (this.friendTalkDispatchTimer) {
+            clearInterval(this.friendTalkDispatchTimer);
+            this.friendTalkDispatchTimer = null;
+        }
+        this.running = false;
+        logger.info("Alimtalk service stopped");
+    }
+
+    // ─── Alimtalk Enqueue / Dispatch ─────────────────────────────────────
+
+    /** 알림톡 발송 작업을 큐에 등록한다 */
+    async enqueueJob(job: AlimtalkJob): Promise<void> {
+        if (!this.querier) throw new Error("alimtalk: querier not set");
+
+        const provider = (job.provider || "").trim() || this.config.default;
+        const variablesJSON = job.variables
+            ? JSON.stringify(job.variables)
+            : "";
+
+        await this.querier.submitAlimtalkLog({
+            status: "pending",
+            template_code: job.templateCode,
+            template_name: job.templateName,
+            receiver: job.receiver,
+            provider,
+            variables_json: variablesJSON,
+            alimtalk_msg_seq: job.msgSeq || 0,
+            retry_count: 0,
+        });
+    }
+
+    /** 대기 중인 알림톡을 일괄 발송한다 */
+    private async dispatch(): Promise<void> {
+        if (!this.querier) return;
+
+        const queueSize = this.config.queue_size || 200;
+        const pending = await this.querier.claimPendingAlimtalkLogs(queueSize);
+
+        // 동시 처리 (Promise.allSettled로 개별 실패 허용)
+        await Promise.allSettled(pending.map((p) => this.processOne(p)));
+    }
+
+    /** 알림톡 한 건을 발송 처리한다 */
+    private async processOne(pending: PendingAlimtalkLog): Promise<void> {
+        const providerKey =
+            (pending.provider || "").trim() || this.config.default;
+        const client = this.clients.get(providerKey);
+
+        if (!client) {
+            await this.finalize(
+                pending,
+                "",
+                new Error(`alimtalk: unknown provider "${providerKey}"`),
+            );
+            return;
+        }
+
+        // 변수 파싱
+        let variables: Record<string, string> = {};
+        if (pending.variablesJSON) {
+            try {
+                variables = JSON.parse(pending.variablesJSON);
+            } catch {
+                /* empty */
+            }
+        }
+
+        try {
+            const result = await client.send({
+                senderKey: this.config.sender_key,
+                templateCode: pending.templateCode,
+                receiver: pending.receiver,
+                variables,
+                buttons: [],
+            });
+
+            await this.finalize(pending, result.providerMsgId, null);
+        } catch (err) {
+            await this.finalize(pending, "", err as Error);
+        }
+    }
+
+    /** 알림톡 발송 결과를 저장한다 */
+    private async finalize(
+        pending: PendingAlimtalkLog,
+        providerMsgId: string,
+        sendErr: Error | null,
+    ): Promise<void> {
+        const status = sendErr ? "failed" : "sent";
+        const errMsg = sendErr?.message ?? "";
+
+        if (sendErr) {
+            logger.warn(
+                `Alimtalk send failed (seq=${pending.logSeq}, receiver=${pending.receiver}): ${errMsg}`,
+            );
+        }
+
+        try {
+            await this.querier!.updateAlimtalkLogStatus(
+                pending.logSeq,
+                status,
+                providerMsgId,
+                errMsg,
+            );
+        } catch (err) {
+            logger.error(
+                { err },
+                `Alimtalk: failed to update alimtalk_log seq=${pending.logSeq}`,
+            );
+        }
+
+        if (pending.msgSeq > 0) {
+            this.querier!.updateAlimtalkMsgStatus(pending.msgSeq, status).catch(
+                (err) =>
+                    logger.warn(
+                        { err },
+                        `Alimtalk: failed to update alimtalk_msg seq=${pending.msgSeq}`,
+                    ),
+            );
+        }
+    }
+
+    // ─── FriendTalk Enqueue / Dispatch ───────────────────────────────────
+
+    /** 친구톡 발송 작업을 큐에 등록한다 */
+    async enqueueFriendTalkJob(job: FriendTalkJob): Promise<void> {
+        if (!this.friendTalkQuerier)
+            throw new Error("friendtalk: querier not set");
+
+        const provider = (job.provider || "").trim() || this.config.default;
+        const msgType = (job.msgType || "").trim() || FRIENDTALK_TYPE_TEXT;
+
+        await this.friendTalkQuerier.submitFriendTalkLog({
+            status: "pending",
+            provider,
+            msg_type: msgType,
+            receiver: job.receiver,
+            content: job.content,
+            image_url: job.imageUrl,
+            image_link: job.imageLink,
+            is_ad: job.isAd,
+            buttons_json: job.buttonsJSON,
+            carousel_json: job.carouselJSON,
+            items_json: job.itemsJSON,
+            header: job.header,
+            friendtalk_msg_seq: job.msgSeq || 0,
+            retry_count: 0,
+        });
+    }
+
+    /** 대기 중인 친구톡을 일괄 발송한다 */
+    private async friendTalkDispatch(): Promise<void> {
+        if (!this.friendTalkQuerier) return;
+
+        const queueSize = this.config.queue_size || 200;
+        const pending =
+            await this.friendTalkQuerier.claimPendingFriendTalkLogs(queueSize);
+
+        await Promise.allSettled(
+            pending.map((p) => this.processFriendTalkOne(p)),
+        );
+    }
+
+    /** 친구톡 한 건을 발송 처리한다 */
+    private async processFriendTalkOne(
+        pending: PendingFriendTalkLog,
+    ): Promise<void> {
+        const providerKey =
+            (pending.provider || "").trim() || this.config.default;
+        const client = this.clients.get(providerKey);
+
+        if (!client) {
+            await this.finalizeFriendTalk(
+                pending,
+                "",
+                new Error(`friendtalk: unknown provider "${providerKey}"`),
+            );
+            return;
+        }
+
+        // 버튼 파싱
+        let buttons: AlimtalkButton[] = [];
+        if (pending.buttonsJSON) {
+            try {
+                buttons = JSON.parse(pending.buttonsJSON);
+            } catch {
+                /* empty */
+            }
+        }
+
+        // 와이드 아이템 파싱
+        let items: FriendTalkItem[] = [];
+        if (pending.itemsJSON) {
+            try {
+                items = JSON.parse(pending.itemsJSON);
+            } catch {
+                /* empty */
+            }
+        }
+
+        // 캐러셀 파싱
+        let carousel: FriendTalkCarousel | undefined;
+        if (pending.carouselJSON) {
+            try {
+                carousel = JSON.parse(pending.carouselJSON);
+            } catch {
+                /* empty */
+            }
+        }
+
+        try {
+            const result = await client.sendFriendTalk({
+                senderKey: this.config.sender_key,
+                msgType: pending.msgType,
+                receiver: pending.receiver,
+                content: pending.content,
+                imageUrl: pending.imageUrl,
+                imageLink: pending.imageLink,
+                isAd: pending.isAd,
+                buttons,
+                header: pending.header,
+                items,
+                carousel,
+            });
+
+            await this.finalizeFriendTalk(pending, result.providerMsgId, null);
+        } catch (err) {
+            await this.finalizeFriendTalk(pending, "", err as Error);
+        }
+    }
+
+    /** 친구톡 발송 결과를 저장한다 */
+    private async finalizeFriendTalk(
+        pending: PendingFriendTalkLog,
+        providerMsgId: string,
+        sendErr: Error | null,
+    ): Promise<void> {
+        const status = sendErr ? "failed" : "sent";
+        const errMsg = sendErr?.message ?? "";
+
+        if (sendErr) {
+            logger.warn(
+                `FriendTalk send failed (seq=${pending.logSeq}, receiver=${pending.receiver}): ${errMsg}`,
+            );
+        }
+
+        try {
+            await this.friendTalkQuerier!.updateFriendTalkLogStatus(
+                pending.logSeq,
+                status,
+                providerMsgId,
+                errMsg,
+            );
+        } catch (err) {
+            logger.error(
+                { err },
+                `FriendTalk: failed to update friendtalk_log seq=${pending.logSeq}`,
+            );
+        }
+
+        if (pending.msgSeq > 0) {
+            this.friendTalkQuerier!.updateFriendTalkMsgStatus(
+                pending.msgSeq,
+                status,
+            ).catch((err) =>
+                logger.warn(
+                    { err },
+                    `FriendTalk: failed to update friendtalk_msg seq=${pending.msgSeq}`,
+                ),
+            );
+        }
+    }
+
+    // ─── Templates ───────────────────────────────────────────────────────
+
+    /** 등록된 템플릿 목록을 반환한다 */
+    listTemplates() {
+        return this.templateCache.list();
+    }
+
+    // ─── Webhook ─────────────────────────────────────────────────────────
+
+    /** 프로바이더 웹훅 콜백을 처리한다 */
+    async processWebhook(
+        provider: string,
+        body: Buffer | string,
+    ): Promise<void> {
+        if (!this.querier) throw new Error("alimtalk: querier not set");
+        const wp = new WebhookProcessor(this.querier);
+        await wp.process(provider, body);
+    }
+
+    // ─── Getters ─────────────────────────────────────────────────────────
+
+    /** 서비스 실행 상태를 반환한다 */
+    isRunning(): boolean {
+        return this.running;
+    }
+
+    /** 알림톡 설정을 반환한다 */
+    getConfig(): AlimtalkConfig {
+        return this.config;
+    }
+}

package/src/app/plugins/alimtalk/template-cache.ts

@@ -0,0 +1,42 @@
+/**
+ * 알림톡 템플릿 캐시
+ *
+ * configs/notification/alimtalk.json의 templates 배열에서 로드.
+ * DB 엔티티를 사용하지 않으며, 설정 파일 수정으로 템플릿 관리.
+ */
+
+import { logger } from "@gateway/api";
+import type { AlimtalkTemplateMapping, AlimtalkTemplate } from "./types/index.ts";
+
+export class TemplateCache {
+    private cache = new Map<string, AlimtalkTemplate>();
+
+    /** 설정 파일에서 템플릿을 로드한다 */
+    loadFromConfig(templates: AlimtalkTemplateMapping[]): void {
+        if (!templates?.length) return;
+
+        this.cache.clear();
+        for (const tpl of templates) {
+            if (!tpl.code) continue;
+            this.cache.set(tpl.code, {
+                templateCode: tpl.code,
+                templateName: tpl.description,
+                content: "",
+                variables: tpl.variables ?? [],
+            });
+        }
+        logger.info(
+            `Alimtalk: loaded ${this.cache.size} template(s) from config`,
+        );
+    }
+
+    /** 전체 템플릿 목록을 반환한다 */
+    list(): AlimtalkTemplate[] {
+        return [...this.cache.values()];
+    }
+
+    /** 캐시에서 템플릿을 조회한다 */
+    get(code: string): AlimtalkTemplate | undefined {
+        return this.cache.get(code);
+    }
+}

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

@@ -0,0 +1,27 @@
+[
+    {
+        "code": "welcome",
+        "description": "회원가입 환영",
+        "variables": ["name", "date"]
+    },
+    {
+        "code": "order_confirm",
+        "description": "주문 확인",
+        "variables": ["name", "order_no", "product", "amount"]
+    },
+    {
+        "code": "delivery_start",
+        "description": "배송 시작 안내",
+        "variables": ["name", "order_no", "carrier", "tracking_no"]
+    },
+    {
+        "code": "appointment_remind",
+        "description": "예약 리마인더",
+        "variables": ["name", "datetime", "location", "staff"]
+    },
+    {
+        "code": "password_reset",
+        "description": "비밀번호 재설정",
+        "variables": ["name", "code"]
+    }
+]

package/src/app/plugins/alimtalk/types/client.ts

@@ -0,0 +1,48 @@
+import type {
+    AlimtalkRequest,
+    AlimtalkResult,
+    PendingAlimtalkLog,
+} from "./job.ts";
+import type {
+    FriendTalkRequest,
+    FriendTalkResult,
+    PendingFriendTalkLog,
+} from "./friendtalk.ts";
+
+export interface AlimtalkClient {
+    name(): string;
+    send(req: AlimtalkRequest): Promise<AlimtalkResult>;
+    sendFriendTalk(req: FriendTalkRequest): Promise<FriendTalkResult>;
+}
+
+export interface AlimtalkQuerier {
+    submitAlimtalkLog(data: Record<string, unknown>): Promise<void>;
+    claimPendingAlimtalkLogs(limit: number): Promise<PendingAlimtalkLog[]>;
+    updateAlimtalkLogStatus(
+        logSeq: number,
+        status: string,
+        providerMsgId: string,
+        errMsg: string,
+    ): Promise<void>;
+    resetStaleAlimtalkLogs(): Promise<void>;
+    updateAlimtalkMsgStatus(msgSeq: number, status: string): Promise<void>;
+    updateAlimtalkLogDelivery(
+        providerMsgId: string,
+        status: string,
+        deliveredAt: string,
+        errMsg: string,
+    ): Promise<void>;
+}
+
+export interface FriendTalkQuerier {
+    submitFriendTalkLog(data: Record<string, unknown>): Promise<void>;
+    claimPendingFriendTalkLogs(limit: number): Promise<PendingFriendTalkLog[]>;
+    updateFriendTalkLogStatus(
+        logSeq: number,
+        status: string,
+        providerMsgId: string,
+        errMsg: string,
+    ): Promise<void>;
+    resetStaleFriendTalkLogs(): Promise<void>;
+    updateFriendTalkMsgStatus(msgSeq: number, status: string): Promise<void>;
+}

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

@@ -0,0 +1,53 @@
+export interface AlimtalkConfig {
+    enabled?: boolean;
+    default: string;
+    sender_key: string;
+    workers: number;
+    dispatch_interval_sec: number;
+    queue_size: number;
+    max_retries: number;
+    providers: Record<string, AlimtalkProviderConfig>;
+    templates?: AlimtalkTemplateMapping[]; // 알림톡 사전 등록 템플릿 목록 — templates/notification/alimtalk.json에서 별도 로드
+    rate_limit?: AlimtalkRateLimitConfig;
+    friendtalk?: FriendTalkConfig;
+}
+
+export interface FriendTalkConfig {
+    enabled?: boolean;
+    workers: number;
+    ad_prefix: string;
+    default_ad: boolean;
+    templates?: FriendTalkTemplate[]; // 친구톡 자유 형식 본문 패턴 — templates/notification/friendtalk.json에서 별도 로드
+}
+
+/** 친구톡 자유 형식 본문 템플릿 (알림톡의 templateCode 방식과 무관) */
+export interface FriendTalkTemplate {
+    code: string;
+    description: string;
+    msgType: string; // 메시지 유형: "text" | "image" | "wide_image" | "wide_item_list" | "carousel"
+    content: string;
+    variables: string[];
+}
+
+export interface AlimtalkProviderConfig {
+    driver: string; // "aligo" | "solapi" | "ppurio" | "nhn_cloud"
+    api_key: string;
+    api_secret: string;
+    user_id: string;
+    account: string;
+    sender_key: string;
+    pf_id: string;
+    app_key: string;
+    secret_key: string;
+}
+
+export interface AlimtalkTemplateMapping {
+    code: string;
+    description: string;
+    variables: string[];
+}
+
+export interface AlimtalkRateLimitConfig {
+    per_minute: number;
+    per_hour: number;
+}

package/src/app/plugins/alimtalk/types/friendtalk.ts

@@ -0,0 +1,90 @@
+import type { AlimtalkButton } from "./job.ts";
+
+export const FRIENDTALK_TYPE_TEXT = "text";
+export const FRIENDTALK_TYPE_IMAGE = "image";
+export const FRIENDTALK_TYPE_WIDE_IMAGE = "wide_image";
+export const FRIENDTALK_TYPE_WIDE_ITEM_LIST = "wide_item_list";
+export const FRIENDTALK_TYPE_CAROUSEL = "carousel";
+
+export interface FriendTalkJob {
+    provider: string;
+    msgType: string;
+    receiver: string;
+    content: string;
+    imageUrl: string;
+    imageLink: string;
+    isAd: boolean;
+    buttonsJSON: string;
+    carouselJSON: string;
+    itemsJSON: string;
+    header: string;
+    refEntity: string;
+    refSeq: number;
+    msgSeq: number;
+}
+
+export interface PendingFriendTalkLog {
+    logSeq: number;
+    provider: string;
+    msgType: string;
+    receiver: string;
+    content: string;
+    imageUrl: string;
+    imageLink: string;
+    isAd: boolean;
+    buttonsJSON: string;
+    carouselJSON: string;
+    itemsJSON: string;
+    header: string;
+    retryCount: number;
+    msgSeq: number;
+}
+
+export interface FriendTalkRequest {
+    senderKey: string;
+    msgType: string;
+    receiver: string;
+    content: string;
+    imageUrl: string;
+    imageLink: string;
+    isAd: boolean;
+    buttons: AlimtalkButton[];
+    header: string;
+    items: FriendTalkItem[];
+    carousel?: FriendTalkCarousel;
+}
+
+export interface FriendTalkItem {
+    title: string;
+    image_url: string;
+    link_mobile: string;
+    link_pc?: string;
+    scheme_ios?: string;
+    scheme_android?: string;
+}
+
+export interface FriendTalkCarousel {
+    items: FriendTalkCarouselItem[];
+    tail?: FriendTalkLink;
+}
+
+export interface FriendTalkCarouselItem {
+    header: string;
+    message: string;
+    image_url: string;
+    image_link?: string;
+    buttons?: AlimtalkButton[];
+}
+
+export interface FriendTalkLink {
+    link_mobile: string;
+    link_pc?: string;
+    scheme_ios?: string;
+    scheme_android?: string;
+}
+
+export interface FriendTalkResult {
+    providerMsgId: string;
+    statusCode: string;
+    requestId: string;
+}

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

@@ -0,0 +1,4 @@
+export * from "./config.ts";
+export * from "./job.ts";
+export * from "./friendtalk.ts";
+export * from "./client.ts";