create-entity-app-server 0.0.3

package/src/app/plugins/alimtalk/entities/alimtalk_msg.json

@@ -0,0 +1,53 @@
+{
+    "name": "alimtalk_msg",
+    "description": "알림톡 발송 트리거 엔티티 — Hook 또는 API를 통해 생성되면 알림톡 발송이 시작됩니다. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "history": false,
+    "fields": {
+        "template_code": {
+            "index": true,
+            "comment": "카카오 알림톡 템플릿 코드",
+            "required": true
+        },
+        "receiver": {
+            "index": true,
+            "hash": true,
+            "comment": "수신자 전화번호",
+            "required": true
+        },
+        "status": {
+            "index": true,
+            "type": [
+                "pending",
+                "processing",
+                "sent",
+                "delivered",
+                "failed"
+            ],
+            "default": "pending",
+            "comment": "발송 상태 (delivered = 프로바이더 수신 확인)"
+        },
+        "variables_json": {
+            "type": "text",
+            "comment": "템플릿 변수 JSON (#{key} 바인딩)"
+        },
+        "provider": {
+            "comment": "프로바이더 키 (빈 값이면 default)"
+        },
+        "ref_entity": {
+            "comment": "참조 엔티티 이름"
+        },
+        "ref_seq": {
+            "type": "int"
+        }
+    },
+    "hooks": {
+        "after_insert": [
+            {
+                "type": "alimtalk",
+                "alimtalk_receiver": "${new.receiver}",
+                "alimtalk_template_code": "${new.template_code}",
+                "alimtalk_variables": "${new.variables_json}"
+            }
+        ]
+    }
+}

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

@@ -0,0 +1,196 @@
+/**
+ * AlimtalkQuerier — Entity Server 어댑터
+ *
+ * entity-server-client를 통해 alimtalk_log, alimtalk_msg 엔티티에 접근.
+ * DB 큐 패턴: pending → processing → sent/failed/delivered
+ *
+ * Note: Go의 CompareAndSwap는 구현하지 않음.
+ *       단일 Node.js 프로세스이므로 dispatch loop에서 순차 처리하여 동시성 문제 방지.
+ */
+
+import { entityServer } from "@gateway/api";
+import { logger } from "@gateway/api";
+import type { AlimtalkQuerier, PendingAlimtalkLog } from "./types/index.ts";
+
+export class AlimtalkEntityAdapter implements AlimtalkQuerier {
+    /** AlimtalkEntityAdapter를 초기화한다 */
+    constructor(private readonly maxRetries: number = 3) {}
+
+    /** 알림톡 발송 로그를 등록한다 */
+    async submitAlimtalkLog(data: Record<string, unknown>): Promise<void> {
+        await entityServer.submit("alimtalk_log", data);
+    }
+
+    /** 대기 중인 알림톡 로그를 조회·점유한다 */
+    async claimPendingAlimtalkLogs(
+        limit: number,
+    ): Promise<PendingAlimtalkLog[]> {
+        const resp = await entityServer.list("alimtalk_log", {
+            status: "pending",
+            page: 1,
+            limit,
+            order: "seq",
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<
+            string,
+            unknown
+        >[];
+        const logs: PendingAlimtalkLog[] = [];
+
+        for (const item of items) {
+            const seq = Number(item.seq ?? 0);
+            if (seq <= 0) continue;
+
+            // pending → processing (단일 프로세스이므로 CAS 대신 직접 갱신)
+            try {
+                await entityServer.submit("alimtalk_log", {
+                    seq,
+                    status: "processing",
+                });
+            } catch {
+                continue; // 이미 다른 곳에서 처리 중 가능
+            }
+
+            logs.push({
+                logSeq: seq,
+                provider: String(item.provider ?? ""),
+                templateCode: String(item.template_code ?? ""),
+                templateName: String(item.template_name ?? ""),
+                receiver: String(item.receiver ?? ""),
+                variablesJSON: String(item.variables_json ?? ""),
+                retryCount: Number(item.retry_count ?? 0),
+                msgSeq: Number(item.alimtalk_msg_seq ?? 0),
+            });
+        }
+
+        return logs;
+    }
+
+    /** 알림톡 발송 로그 상태를 갱신한다 */
+    async updateAlimtalkLogStatus(
+        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("alimtalk_log", data);
+    }
+
+    /** 장기 처리 중인 알림톡 로그를 초기화한다 */
+    async resetStaleAlimtalkLogs(): Promise<void> {
+        const resp = await entityServer.list("alimtalk_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("alimtalk_log", {
+                        seq,
+                        status: "failed",
+                        error_message: "max retries exceeded (stale recovery)",
+                    })
+                    .catch((err) =>
+                        logger.error(
+                            { err },
+                            `Alimtalk: stale log update failed seq=${seq}`,
+                        ),
+                    );
+                continue;
+            }
+
+            try {
+                await entityServer.submit("alimtalk_log", {
+                    seq,
+                    status: "pending",
+                });
+                resetCount++;
+            } catch {
+                /* skip */
+            }
+        }
+
+        if (resetCount > 0) {
+            logger.info(
+                `Alimtalk: reset ${resetCount} stale processing logs to pending`,
+            );
+        }
+    }
+
+    /** 알림톡 메시지 상태를 갱신한다 */
+    async updateAlimtalkMsgStatus(
+        msgSeq: number,
+        status: string,
+    ): Promise<void> {
+        await entityServer.submit("alimtalk_msg", { seq: msgSeq, status });
+    }
+
+    /** 알림톡 발송 결과 웹훅을 반영한다 */
+    async updateAlimtalkLogDelivery(
+        providerMsgId: string,
+        status: string,
+        deliveredAt: string,
+        errMsg: string,
+    ): Promise<void> {
+        // provider_msg_id로 alimtalk_log 검색
+        const resp = await entityServer.list("alimtalk_log", {
+            provider_msg_id: providerMsgId,
+            page: 1,
+            limit: 1,
+        } as any);
+
+        const items = ((resp.data as any)?.items ?? []) as Record<
+            string,
+            unknown
+        >[];
+        if (items.length === 0) {
+            throw new Error(
+                `alimtalk delivery: log not found for provider_msg_id=${providerMsgId}`,
+            );
+        }
+
+        const item = items[0];
+        const logSeq = Number(item.seq ?? 0);
+        if (logSeq <= 0) {
+            throw new Error(
+                `alimtalk delivery: invalid seq for provider_msg_id=${providerMsgId}`,
+            );
+        }
+
+        const patch: Record<string, unknown> = { seq: logSeq, status };
+        if (deliveredAt) patch.delivered_at = deliveredAt;
+        if (errMsg) patch.error_message = errMsg;
+
+        await entityServer.submit("alimtalk_log", patch);
+
+        // alimtalk_msg 상태 갱신
+        const msgSeq = Number(item.alimtalk_msg_seq ?? 0);
+        if (msgSeq > 0) {
+            await this.updateAlimtalkMsgStatus(msgSeq, status).catch((err) =>
+                logger.warn(
+                    { err },
+                    `Alimtalk delivery: failed to update msg seq=${msgSeq}`,
+                ),
+            );
+        }
+    }
+}

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

@@ -0,0 +1,84 @@
+/**
+ * 알림톡 핸들러 구현
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail } from "@gateway/api";
+
+/** 알림톡 발송 요청을 처리한다 */
+export async function send(req: FastifyRequest, reply: FastifyReply) {
+    const svc = req.server.alimtalkService;
+    if (!svc)
+        return reply.status(503).send(fail("Alimtalk service not available"));
+
+    const body = req.body as Record<string, unknown> | undefined;
+    const templateCode = String(body?.template_code ?? "");
+    const receiver = String(body?.receiver ?? "");
+
+    if (!templateCode || !receiver) {
+        return reply
+            .status(400)
+            .send(fail("template_code and receiver are required"));
+    }
+
+    await svc.enqueueJob({
+        templateCode,
+        receiver,
+        variables: (body?.variables ?? {}) as Record<string, string>,
+        provider: String(body?.provider ?? ""),
+        templateName: "",
+        buttons: [],
+        refEntity: "",
+        refSeq: 0,
+        msgSeq: 0,
+    });
+
+    return reply.status(202).send(ok({ message: "alimtalk queued" }));
+}
+
+/** 발송 상태를 조회한다 */
+export async function getStatus(_req: FastifyRequest, reply: FastifyReply) {
+    return reply.status(501).send(fail("not implemented yet"));
+}
+
+/** 등록된 템플릿 목록을 조회한다 */
+export async function listTemplates(req: FastifyRequest, reply: FastifyReply) {
+    const svc = req.server.alimtalkService;
+    if (!svc)
+        return reply.status(503).send(fail("Alimtalk service not available"));
+
+    const templates = svc.listTemplates();
+    return ok({
+        templates: templates.map((t) => ({
+            code: t.templateCode,
+            name: t.templateName,
+            variables: t.variables,
+        })),
+        count: templates.length,
+    });
+}
+
+/** 프로바이더 웹훅 콜백을 수신한다 */
+export async function webhook(req: FastifyRequest, reply: FastifyReply) {
+    const svc = req.server.alimtalkService;
+    if (!svc) return reply.status(200).send("OK");
+
+    const provider = (req.params as Record<string, string>).provider ?? "";
+    if (!provider) return reply.status(400).send("provider required");
+
+    try {
+        const rawBody =
+            typeof req.body === "string"
+                ? req.body
+                : JSON.stringify(req.body ?? {});
+        await svc.processWebhook(provider, rawBody);
+    } catch (err) {
+        req.server.log.warn(
+            err,
+            `Alimtalk webhook callback (${provider}) error`,
+        );
+    }
+
+    // 프로바이더 재시도 방지 — 항상 200 반환
+    return reply.status(200).send("OK");
+}

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

@@ -0,0 +1,80 @@
+/**
+ * 알림톡 / 친구톡 Fastify 플러그인
+ *
+ * 설정 로드 → 프로바이더 클라이언트 생성 → Entity Adapter 주입 →
+ * AlimtalkService 시작 → app.alimtalkService 데코레이터 등록
+ */
+
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { loadAlimtalkConfig } from "./config.ts";
+import { createAlimtalkClient } from "./providers/index.ts";
+import { AlimtalkService } from "./service.ts";
+import { AlimtalkEntityAdapter } from "./entity-adapter.ts";
+import { FriendTalkEntityAdapter } from "../friendtalk/entity-adapter.ts";
+import type { AlimtalkClient } from "./types/index.ts";
+
+declare module "fastify" {
+    interface FastifyInstance {
+        alimtalkService: AlimtalkService | null;
+    }
+}
+
+/** 알림톡 플러그인을 등록한다 */
+export default fp(
+    async (app: FastifyInstance) => {
+        const config = loadAlimtalkConfig();
+
+        if (!config) {
+            app.decorate("alimtalkService", null);
+            return;
+        }
+
+        // 프로바이더 클라이언트 생성
+        const clients = new Map<string, AlimtalkClient>();
+        for (const [name, provCfg] of Object.entries(config.providers ?? {})) {
+            try {
+                const client = createAlimtalkClient(provCfg);
+                clients.set(name, client);
+                app.log.info(
+                    `Alimtalk provider registered: ${name} (${provCfg.driver})`,
+                );
+            } catch (err) {
+                app.log.error(
+                    err,
+                    `Failed to create alimtalk provider: ${name} (${provCfg.driver})`,
+                );
+            }
+        }
+
+        if (clients.size === 0) {
+            app.log.warn(
+                "Alimtalk: no valid providers configured, service disabled",
+            );
+            app.decorate("alimtalkService", null);
+            return;
+        }
+
+        const service = new AlimtalkService(config, clients);
+
+        // Entity Adapter 주입
+        service.setQuerier(new AlimtalkEntityAdapter(config.max_retries));
+
+        if (config.friendtalk?.enabled) {
+            service.setFriendTalkQuerier(
+                new FriendTalkEntityAdapter(config.max_retries),
+            );
+        }
+
+        // 서비스 시작 (dispatch loop)
+        await service.start();
+
+        app.decorate("alimtalkService", service);
+
+        // graceful shutdown
+        app.addHook("onClose", async () => {
+            service.stop();
+        });
+    },
+    { name: "alimtalk-plugin" },
+);

package/src/app/plugins/alimtalk/providers/aligo.ts

@@ -0,0 +1,151 @@
+/**
+ * Aligo(알리고) 알림톡 프로바이더 어댑터
+ *
+ * API: https://kakaoapi.aligo.in/akv10/alimtalk/send/
+ *      https://kakaoapi.aligo.in/akv10/friend/send/
+ * form-encoded POST, ~6원/건
+ */
+
+import type {
+    AlimtalkClient,
+    AlimtalkProviderConfig,
+    AlimtalkRequest,
+    AlimtalkResult,
+    FriendTalkRequest,
+    FriendTalkResult,
+} from "../types/index.ts";
+
+export class AligoClient implements AlimtalkClient {
+    private readonly apiKey: string;
+    private readonly userId: string;
+    private readonly senderKey: string;
+
+    /** AligoClient 인스턴스를 초기화한다 */
+    constructor(cfg: AlimtalkProviderConfig) {
+        if (!cfg.api_key || !cfg.user_id) {
+            throw new Error("aligo alimtalk: api_key and user_id are required");
+        }
+        this.apiKey = cfg.api_key;
+        this.userId = cfg.user_id;
+        this.senderKey = cfg.sender_key;
+    }
+
+    /** 프로바이더 이름을 반환한다 */
+    name(): string {
+        return "aligo";
+    }
+
+    /** 알림톡 발송 API를 호출한다 */
+    async send(req: AlimtalkRequest): Promise<AlimtalkResult> {
+        const senderKey = req.senderKey || this.senderKey;
+
+        const params = new URLSearchParams();
+        params.set("apikey", this.apiKey);
+        params.set("userid", this.userId);
+        params.set("senderkey", senderKey);
+        params.set("tpl_code", req.templateCode);
+        params.set("receiver_1", req.receiver);
+
+        // 변수 바인딩 — 알리고는 message_1에 전체 본문 전달
+        if (req.variables && Object.keys(req.variables).length > 0) {
+            const first = Object.entries(req.variables)[0];
+            if (first) params.set("subject_1", `${first[0]}=${first[1]}`);
+        }
+
+        // 버튼
+        if (req.buttons && req.buttons.length > 0) {
+            const btns = req.buttons.map((b) => ({
+                name: b.name,
+                linkType: b.type,
+                linkM: b.url_web,
+                linkP: b.url_web,
+                ...(b.url_app ? { linkA: b.url_app } : {}),
+            }));
+            params.set("button_1", JSON.stringify({ button: btns }));
+        }
+
+        const resp = await fetch(
+            "https://kakaoapi.aligo.in/akv10/alimtalk/send/",
+            {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                body: params.toString(),
+                signal: AbortSignal.timeout(30_000),
+            },
+        );
+
+        const body = (await resp.json()) as {
+            code: number;
+            message: string;
+            info?: { mid?: string };
+        };
+        if (body.code !== 0) {
+            throw new Error(
+                `aligo alimtalk: send failed (code=${body.code}): ${body.message}`,
+            );
+        }
+
+        return {
+            providerMsgId: body.info?.mid ?? "",
+            statusCode: String(body.code),
+            requestId: "",
+        };
+    }
+
+    /** 친구톡 발송 API를 호출한다 */
+    async sendFriendTalk(req: FriendTalkRequest): Promise<FriendTalkResult> {
+        const senderKey = req.senderKey || this.senderKey;
+
+        const params = new URLSearchParams();
+        params.set("apikey", this.apiKey);
+        params.set("userid", this.userId);
+        params.set("senderkey", senderKey);
+        params.set("receiver_1", req.receiver);
+        params.set("message_1", req.content);
+
+        if (req.imageUrl) params.set("image", req.imageUrl);
+        if (req.isAd) params.set("adFlag", "Y");
+
+        if (req.buttons && req.buttons.length > 0) {
+            const btns = req.buttons.map((b) => ({
+                name: b.name,
+                linkType: b.type,
+                linkM: b.url_web,
+                linkP: b.url_web,
+                ...(b.url_app ? { linkA: b.url_app } : {}),
+            }));
+            params.set("button_1", JSON.stringify({ button: btns }));
+        }
+
+        const resp = await fetch(
+            "https://kakaoapi.aligo.in/akv10/friend/send/",
+            {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                body: params.toString(),
+                signal: AbortSignal.timeout(30_000),
+            },
+        );
+
+        const body = (await resp.json()) as {
+            code: number;
+            message: string;
+            info?: { mid?: string };
+        };
+        if (body.code !== 0) {
+            throw new Error(
+                `aligo friendtalk: send failed (code=${body.code}): ${body.message}`,
+            );
+        }
+
+        return {
+            providerMsgId: body.info?.mid ?? "",
+            statusCode: String(body.code),
+            requestId: "",
+        };
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * 알림톡 클라이언트 팩토리
+ *
+ * 프로바이더 설정에 따라 적절한 AlimtalkClient를 생성합니다.
+ */
+
+import type { AlimtalkProviderConfig, AlimtalkClient } from "../types/index.ts";
+import { AligoClient } from "./aligo.ts";
+import { SolapiClient } from "./solapi.ts";
+import { PpurioClient } from "./ppurio.ts";
+import { NHNClient } from "./nhn.ts";
+
+/** 드라이버에 맞는 알림톡 클라이언트를 생성한다 */
+export function createAlimtalkClient(
+    cfg: AlimtalkProviderConfig,
+): AlimtalkClient {
+    switch (cfg.driver) {
+        case "aligo":
+            return new AligoClient(cfg);
+        case "solapi":
+            return new SolapiClient(cfg);
+        case "ppurio":
+            return new PpurioClient(cfg);
+        case "nhn_cloud":
+            return new NHNClient(cfg);
+        default:
+            throw new Error(`Unsupported alimtalk driver: ${cfg.driver}`);
+    }
+}