create-entity-app-server 0.0.3

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

@@ -0,0 +1,242 @@
+import { logger, entityServer } from "@gateway/api";
+import type {
+    AisConfig,
+    AisStreamMessage,
+    AisVesselAccum,
+} from "./types/index.ts";
+
+const WS_URL = "wss://stream.aisstream.io/v0/stream";
+const ENTITY = "ais_vessel";
+
+// ──────────────────────────── WebSocket 수집 ─────────────────────────────────
+
+/**
+ * aisstream.io에 WebSocket으로 연결해 collectSeconds 동안 AIS 메시지를 수집합니다.
+ * PositionReport / ShipStaticData 메시지를 MMSI 키로 누적(merge)합니다.
+ * Node.js 22 내장 WebSocket 사용 — aisstream.io는 GitHub 로그인 후 무료 API key 발급.
+ */
+export function collectAisSnapshot(
+    apiKey: string,
+    collectSeconds: number,
+    boundingBoxes?: [number, number][][],
+): Promise<Map<string, AisVesselAccum>> {
+    return new Promise((resolve, reject) => {
+        const vessels = new Map<string, AisVesselAccum>();
+
+        // Node.js 22 내장 WebSocket (WHATWG 표준 API)
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ws = new (globalThis as any).WebSocket(WS_URL) as WebSocket;
+
+        const finish = () => {
+            try {
+                ws.close();
+            } catch {
+                /* ignore */
+            }
+            resolve(vessels);
+        };
+
+        const timer = setTimeout(finish, collectSeconds * 1000);
+
+        ws.addEventListener("open", () => {
+            const boxes = boundingBoxes ?? [
+                [
+                    [-90, -180],
+                    [90, 180],
+                ],
+            ];
+            ws.send(
+                JSON.stringify({
+                    APIKey: apiKey,
+                    BoundingBoxes: boxes,
+                    FilterMessageTypes: [
+                        "PositionReport",
+                        "StandardClassBPositionReport",
+                        "ExtendedClassBPositionReport",
+                        "ShipStaticData",
+                    ],
+                }),
+            );
+        });
+
+        ws.addEventListener("message", (event: Event) => {
+            let msg: AisStreamMessage;
+            try {
+                msg = JSON.parse(
+                    (event as MessageEvent).data as string,
+                ) as AisStreamMessage;
+            } catch {
+                return;
+            }
+            mergeMessage(vessels, msg);
+        });
+
+        ws.addEventListener("error", (ev: Event) => {
+            clearTimeout(timer);
+            reject(new Error(`ais WebSocket error: ${String(ev)}`));
+        });
+
+        ws.addEventListener("close", () => {
+            clearTimeout(timer);
+            resolve(vessels);
+        });
+    });
+}
+
+/** AIS 메시지를 파싱해 vessels 맵에 누적합니다 */
+function mergeMessage(
+    vessels: Map<string, AisVesselAccum>,
+    msg: AisStreamMessage,
+): void {
+    const mmsi = String(msg.MetaData?.MMSI ?? "");
+    if (!mmsi || mmsi === "0") return;
+
+    const v = vessels.get(mmsi) ?? { mmsi };
+    const { MessageType, MetaData, Message } = msg;
+
+    if (MetaData.ShipName?.trim()) {
+        v.name = MetaData.ShipName.trim();
+    }
+
+    if (
+        MessageType === "PositionReport" ||
+        MessageType === "StandardClassBPositionReport" ||
+        MessageType === "ExtendedClassBPositionReport"
+    ) {
+        const pos =
+            Message.PositionReport ??
+            (Message as Record<string, AisVesselAccum | undefined>)[
+                MessageType
+            ];
+        if (pos) {
+            const p = pos as {
+                Latitude?: number;
+                Longitude?: number;
+                Sog?: number;
+                Cog?: number;
+                TrueHeading?: number;
+                NavigationalStatus?: number;
+            };
+            if (p.Latitude != null) v.lat = p.Latitude;
+            if (p.Longitude != null) v.lon = p.Longitude;
+            if (p.Sog != null) v.sog = p.Sog;
+            if (p.Cog != null) v.cog = p.Cog;
+            if (p.TrueHeading != null) v.heading = p.TrueHeading;
+            if (p.NavigationalStatus != null)
+                v.nav_status = p.NavigationalStatus;
+            v.snapshot_at = MetaData.time_utc ?? new Date().toISOString();
+        }
+    } else if (MessageType === "ShipStaticData") {
+        const stat = Message.ShipStaticData;
+        if (stat) {
+            if (stat.Name?.trim()) v.name = stat.Name.trim();
+            if (stat.CallSign?.trim()) v.callsign = stat.CallSign.trim();
+            if (stat.ImoNumber) v.imo = stat.ImoNumber;
+            if (stat.Type) v.ship_type = stat.Type;
+            if (stat.Destination?.trim())
+                v.destination = stat.Destination.trim();
+        }
+    }
+
+    vessels.set(mmsi, v);
+}
+
+// ─────────────────────────── DB upsert 배치 ──────────────────────────────────
+
+async function upsertVessels(
+    vessels: Map<string, AisVesselAccum>,
+    batchSize: number,
+): Promise<{ saved: number; errors: number }> {
+    const entries = [...vessels.values()];
+    let saved = 0;
+    let errors = 0;
+
+    for (let i = 0; i < entries.length; i += batchSize) {
+        const chunk = entries.slice(i, i + batchSize);
+        const results = await Promise.allSettled(chunk.map(upsertOne));
+        for (const r of results) {
+            if (r.status === "fulfilled") saved++;
+            else errors++;
+        }
+    }
+
+    return { saved, errors };
+}
+
+async function upsertOne(v: AisVesselAccum): Promise<void> {
+    // 좌표가 없으면 저장하지 않음
+    if (v.lat == null || v.lon == null) return;
+
+    // 기존 레코드 제거
+    const existing = await entityServer.find<{ seq: number }[]>(ENTITY, {
+        where: { mmsi: v.mmsi },
+        limit: 1,
+    });
+    const list = Array.isArray(existing) ? existing : [];
+    for (const rec of list) {
+        await entityServer.delete(ENTITY, rec.seq);
+    }
+
+    // 신규 삽입
+    await entityServer.submit(ENTITY, {
+        mmsi: v.mmsi,
+        name: v.name ?? "",
+        callsign: v.callsign ?? "",
+        imo: v.imo ?? 0,
+        ship_type: v.ship_type ?? 0,
+        lat: v.lat,
+        lon: v.lon,
+        sog: v.sog ?? 0,
+        cog: v.cog ?? 360,
+        heading: v.heading ?? 511,
+        nav_status: v.nav_status ?? 15,
+        destination: v.destination ?? "",
+        snapshot_at: v.snapshot_at ?? new Date().toISOString(),
+    });
+}
+
+// ─────────────────────────── Service 클래스 ──────────────────────────────────
+
+export class AisService {
+    constructor(private readonly config: AisConfig) {}
+
+    /**
+     * aisstream.io에서 스냅샷을 수집하고 DB를 upsert합니다.
+     * 스케줄 및 수동 동기화 모두 이 메서드를 호출합니다.
+     */
+    async syncSnapshot(): Promise<{
+        collected: number;
+        saved: number;
+        errors: number;
+    }> {
+        const collectSeconds = this.config.collectSeconds ?? 60;
+        const batchSize = this.config.batchSize ?? 20;
+
+        logger.info({ collectSeconds }, "ais: collecting from aisstream.io");
+
+        const vessels = await collectAisSnapshot(
+            this.config.apiKey,
+            collectSeconds,
+            this.config.boundingBoxes,
+        );
+
+        logger.info(
+            { collected: vessels.size },
+            "ais: collection done, upserting",
+        );
+
+        const { saved, errors } = await upsertVessels(vessels, batchSize);
+        return { collected: vessels.size, saved, errors };
+    }
+
+    /**
+     * 현재 DB에 저장된 선박 수를 반환합니다.
+     */
+    async countVessels(): Promise<number> {
+        const result = await entityServer.find<{ seq: number }[]>(ENTITY, {
+            limit: 1,
+        });
+        const list = Array.isArray(result) ? result : [];
+        return list.length > 0 ? -1 : 0; // 존재 여부 확인용
+    }
+}

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

@@ -0,0 +1,78 @@
+/** AIS 플러그인 설정 */
+export interface AisConfig {
+    /** 플러그인 활성화 여부 */
+    enabled: boolean;
+    /** aisstream.io API key (GitHub 로그인 후 무료 발급) */
+    apiKey: string;
+    /** WebSocket 수집 시간(초) — 기본 60 */
+    collectSeconds?: number;
+    /** 배치 upsert 병렬 크기 — 기본 20 */
+    batchSize?: number;
+    /** 지역 필터 (생략 시 전세계). [[lat1,lon1],[lat2,lon2]] 형식 */
+    boundingBoxes?: [number, number][][];
+}
+
+/** aisstream.io PositionReport 필드 중 사용하는 부분 */
+export interface AisPositionReport {
+    UserID: number; // MMSI
+    Latitude: number;
+    Longitude: number;
+    Sog: number;
+    Cog: number;
+    TrueHeading: number;
+    NavigationalStatus: number;
+}
+
+/** aisstream.io ShipStaticData 필드 중 사용하는 부분 */
+export interface AisShipStaticData {
+    UserID: number;
+    Name?: string;
+    CallSign?: string;
+    ImoNumber?: number;
+    Type?: number;
+    Destination?: string;
+}
+
+/** aisstream.io StaticDataReport.ReportA */
+export interface AisStaticDataReportA {
+    Name?: string;
+    Valid?: boolean;
+}
+
+/** aisstream.io 메시지 전체 봉투 */
+export interface AisStreamMessage {
+    MessageType: string;
+    MetaData: {
+        MMSI: number;
+        ShipName?: string;
+        latitude?: number;
+        longitude?: number;
+        time_utc?: string;
+    };
+    Message: {
+        PositionReport?: AisPositionReport;
+        ShipStaticData?: AisShipStaticData;
+        StandardClassBPositionReport?: AisPositionReport;
+        ExtendedClassBPositionReport?: AisPositionReport;
+    };
+}
+
+/** 수집 중 MMSI별로 누적하는 임시 레코드 */
+export interface AisVesselAccum {
+    mmsi: string;
+    name?: string;
+    callsign?: string;
+    imo?: number;
+    ship_type?: number;
+    lat?: number;
+    lon?: number;
+    sog?: number;
+    cog?: number;
+    heading?: number;
+    nav_status?: number;
+    destination?: string;
+    snapshot_at?: string;
+}
+
+/** Entity Server에 저장되는 레코드 */
+export type AisVesselRecord = Required<AisVesselAccum>;

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

@@ -0,0 +1,52 @@
+{
+    "_comment": "알림톡 설정 — enabled: false로 비활성화 상태",
+    "enabled": false,
+    "default": "aligo",
+    "sender_key": "${ALIMTALK_SENDER_KEY}",
+    "workers": 2,
+    "dispatch_interval_sec": 5,
+    "queue_size": 200,
+    "max_retries": 3,
+    "_template_file": "templates/notification/alimtalk.json",
+    "providers": {
+        "aligo": {
+            "driver": "aligo",
+            "_comment": "알리고",
+            "api_key": "${ALIGO_API_KEY}",
+            "api_secret": "",
+            "user_id": "${ALIGO_USER_ID}",
+            "account": "",
+            "sender_key": "${ALIMTALK_SENDER_KEY}",
+            "pf_id": "",
+            "app_key": "",
+            "secret_key": ""
+        },
+        "solapi": {
+            "driver": "solapi",
+            "_comment": "솔라피 (Solapi)",
+            "api_key": "${SOLAPI_API_KEY}",
+            "api_secret": "${SOLAPI_API_SECRET}",
+            "sender_key": "${ALIMTALK_SENDER_KEY}",
+            "pf_id": "${SOLAPI_PF_ID}",
+            "api_url": "https://api.solapi.com"
+        },
+        "bizgo": {
+            "driver": "bizgo",
+            "_comment": "비즈고 (BizGo)",
+            "biz_id": "${BIZGO_BIZ_ID}",
+            "api_key": "${BIZGO_API_KEY}",
+            "api_secret": "${BIZGO_API_SECRET}",
+            "sender_key": "${ALIMTALK_SENDER_KEY}",
+            "api_url": "https://bizgo.kakao.com"
+        },
+        "nhncloud": {
+            "driver": "nhncloud",
+            "_comment": "NHN Cloud Alimtalk",
+            "app_key": "${NHNCLOUD_APP_KEY}",
+            "secret_key": "${NHNCLOUD_SECRET_KEY}",
+            "sender_key": "${ALIMTALK_SENDER_KEY}",
+            "plus_friend_id": "${KAKAO_PLUS_FRIEND_ID}",
+            "api_url": "https://api-alimtalk.cloud.toast.com"
+        }
+    }
+}

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

@@ -0,0 +1,26 @@
+{
+  "_comment": "알림톡 설정 — enabled: false로 비활성화 상태",
+  "enabled": false,
+  "default": "aligo",
+  "sender_key": "${ALIMTALK_SENDER_KEY}",
+  "workers": 2,
+  "dispatch_interval_sec": 5,
+  "queue_size": 200,
+  "max_retries": 3,
+  "_template_file": "templates/notification/alimtalk.json",
+  "providers": {
+    "aligo": {
+      "driver": "aligo",
+      "api_key": "${ALIGO_API_KEY}",
+      "api_secret": "",
+      "user_id": "${ALIGO_USER_ID}",
+      "account": "",
+      "sender_key": "${ALIMTALK_SENDER_KEY}",
+      "pf_id": "",
+      "app_key": "",
+      "secret_key": ""
+    }
+  },
+  "deploy": true,
+  "minify": false
+}

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

@@ -0,0 +1,75 @@
+/**
+ * 알림톡 설정 로더
+ *
+ * 플러그인 디렉토리의 config.json을 읽고 환경변수 치환을 수행합니다.
+ * 친구톡 설정은 friendtalk/config.json에서 별도 로드합니다.
+ * 알림톡 템플릿은 templates/notification/alimtalk.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 { AlimtalkConfig, AlimtalkTemplateMapping } from "./types/index.ts";
+import { loadFriendTalkConfig } from "../friendtalk/config.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+const TEMPLATE_PATH = join(__dirname, "templates", "alimtalk.json");
+
+/** 알림톡 템플릿 목록을 templates/notification/alimtalk.json에서 로드한다 */
+function loadAlimtalkTemplates(): AlimtalkTemplateMapping[] {
+    if (!existsSync(TEMPLATE_PATH)) {
+        return [];
+    }
+    try {
+        const raw = readFileSync(TEMPLATE_PATH, "utf-8");
+        return JSON.parse(raw) as AlimtalkTemplateMapping[];
+    } catch (err) {
+        logger.error({ err }, "Failed to load alimtalk templates");
+        return [];
+    }
+}
+
+/** 알림톡 설정을 로드한다 */
+export function loadAlimtalkConfig(): AlimtalkConfig | null {
+    try {
+        let raw = readFileSync(CONFIG_PATH, "utf-8");
+
+        // 환경변수 치환: ${VAR} → process.env.VAR
+        raw = raw.replace(
+            /\$\{([^}]+)\}/g,
+            (_match, name) => process.env[name] ?? "",
+        );
+
+        const cfg: AlimtalkConfig = JSON.parse(raw);
+
+        if (cfg.enabled === false) {
+            logger.info("Alimtalk plugin disabled in config");
+            return null;
+        }
+
+        // 기본값 보정
+        if (!cfg.workers || cfg.workers <= 0) cfg.workers = 2;
+        if (!cfg.dispatch_interval_sec || cfg.dispatch_interval_sec <= 0)
+            cfg.dispatch_interval_sec = 5;
+        if (!cfg.queue_size || cfg.queue_size <= 0) cfg.queue_size = 200;
+        if (!cfg.max_retries || cfg.max_retries <= 0) cfg.max_retries = 3;
+
+        // 친구톡 설정은 friendtalk.json에서 별도 로드
+        cfg.friendtalk = loadFriendTalkConfig();
+
+        // 알림톡 템플릿은 templates/notification/alimtalk.json에서 별도 로드
+        cfg.templates = loadAlimtalkTemplates();
+
+        return cfg;
+    } catch (err: unknown) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            logger.info("Alimtalk config not found, plugin skipped");
+        } else {
+            logger.error({ err }, "Failed to load alimtalk config");
+        }
+        return null;
+    }
+}

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

@@ -0,0 +1,140 @@
+# 알림톡 플러그인 (Alimtalk)
+
+카카오 알림톡을 큐 기반으로 발송합니다. 사전 등록된 템플릿 코드를 사용하며, 알리고(Aligo) 프로바이더를 통해 발송합니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [환경변수](#환경변수)
+- [API](#api)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+| 항목       | 내용                                |
+| ---------- | ----------------------------------- |
+| 발송 방식  | 큐 기반 비동기 발송 (dispatch loop) |
+| 프로바이더 | aligo (알리고)                      |
+| 템플릿     | 카카오 사전 등록 템플릿 코드 필요   |
+| 변수 치환  | `#{변수명}` 패턴                    |
+
+> 알림톡 플러그인은 기본적으로 비활성화(`enabled: false`) 상태입니다. 카카오 비즈니스 채널 및 알리고 계정 설정 후 활성화하세요.
+
+---
+
+## 설정
+
+`config.json`:
+
+```json
+{
+    "enabled": false,
+    "default": "aligo",
+    "sender_key": "${ALIMTALK_SENDER_KEY}",
+    "workers": 2,
+    "dispatch_interval_sec": 5,
+    "queue_size": 200,
+    "max_retries": 3,
+    "providers": {
+        "aligo": {
+            "driver": "aligo",
+            "api_key": "${ALIGO_API_KEY}",
+            "user_id": "${ALIGO_USER_ID}",
+            "sender_key": "${ALIMTALK_SENDER_KEY}"
+        }
+    }
+}
+```
+
+### 설정 항목
+
+| 항목                    | 기본값  | 설명                       |
+| ----------------------- | ------- | -------------------------- |
+| `enabled`               | `false` | 플러그인 활성화 여부       |
+| `default`               | `aligo` | 사용할 프로바이더 키       |
+| `sender_key`            | —       | 카카오 채널 발신 프로필 키 |
+| `workers`               | `2`     | 병렬 발송 워커 수          |
+| `dispatch_interval_sec` | `5`     | 큐 처리 간격(초)           |
+| `queue_size`            | `200`   | 최대 메모리 큐 크기        |
+| `max_retries`           | `3`     | 실패 시 최대 재시도 횟수   |
+
+---
+
+## 환경변수
+
+```env
+ALIMTALK_SENDER_KEY=카카오_채널_발신프로필_키
+ALIGO_API_KEY=알리고_API_키
+ALIGO_USER_ID=알리고_사용자_아이디
+```
+
+### 발신 프로필 키 발급
+
+1. [카카오 비즈니스](https://business.kakao.com) → 채널 등록 및 비즈니스 인증
+2. [알리고 알림톡](https://aligo.biz/talk) → 채널 연동 → 발신 프로필 키 발급
+3. 카카오 채널 검수 완료 후 `ALIMTALK_SENDER_KEY` 설정
+
+---
+
+## API
+
+기본 경로: `/api/v1/alimtalk`
+
+| 메서드 | 경로                 | 인증        | 설명                      |
+| ------ | -------------------- | ----------- | ------------------------- |
+| `POST` | `/send`              | 로그인 필요 | 알림톡 발송 (큐 등록)     |
+| `GET`  | `/status/:seq`       |             | 발송 상태 조회            |
+| `GET`  | `/templates`         |             | 등록 템플릿 목록          |
+| `POST` | `/webhook/:provider` |             | 프로바이더 발송 결과 웹훅 |
+
+### POST /send 요청 바디
+
+```json
+{
+    "template_code": "TM_WELCOME_01",
+    "receiver": "01012345678",
+    "variables": {
+        "name": "홍길동",
+        "order_id": "ORD-2026-001"
+    }
+}
+```
+
+### GET /status/:seq 응답 예시
+
+```json
+{
+    "ok": true,
+    "data": {
+        "seq": 1,
+        "template_code": "TM_WELCOME_01",
+        "receiver": "01012345678",
+        "status": "sent",
+        "sent_at": "2026-03-22T06:00:00.000Z"
+    }
+}
+```
+
+### 발송 상태 값
+
+| 상태         | 설명                |
+| ------------ | ------------------- |
+| `pending`    | 큐 대기 중          |
+| `processing` | 발송 시도 중        |
+| `sent`       | 발송 완료           |
+| `failed`     | 최대 재시도 후 실패 |
+
+---
+
+## 운영 팁
+
+- `#{변수명}`과 `variables` JSON의 키가 정확히 일치해야 함
+- 카카오 검수 반려 시 본문 수정 후 재신청 필요 (1~3 영업일 소요)
+- 알림톡 발송 실패 시 SMS 폴백(fallback) 설정 가능 (알리고 설정 참고)
+- 채널 차단 계정에는 발송 불가 → `failed` 상태로 기록됨
+- 광고성 내용 포함 시 카카오 검수에서 반려됨 (정보성 메시지만 허용)

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

@@ -0,0 +1,65 @@
+{
+    "name": "alimtalk_log",
+    "description": "알림톡 발송 로그 — 워커가 소비하는 DB 큐 역할을 합니다. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "history": false,
+    "read_only": true,
+    "compress": true,
+    "fields": {
+        "status": {
+            "index": true,
+            "type": [
+                "pending",
+                "processing",
+                "sent",
+                "delivered",
+                "failed",
+                "expired"
+            ],
+            "default": "pending",
+            "comment": "발송 상태 (delivered = 프로바이더 수신 확인)"
+        },
+        "template_code": {
+            "index": true,
+            "comment": "카카오 알림톡 템플릿 코드",
+            "required": true
+        },
+        "receiver": {
+            "index": true,
+            "hash": true,
+            "comment": "수신자 전화번호",
+            "required": true
+        },
+        "alimtalk_msg_seq": {
+            "index": true,
+            "comment": "alimtalk_msg 참조 seq"
+        },
+        "template_name": {
+            "comment": "내부 템플릿 이름"
+        },
+        "variables_json": {
+            "type": "text",
+            "comment": "템플릿 변수 JSON"
+        },
+        "provider": {
+            "comment": "사용 프로바이더"
+        },
+        "provider_msg_id": {
+            "comment": "프로바이더 메시지 ID"
+        },
+        "error_message": {
+            "type": "text",
+            "comment": "오류 메시지"
+        },
+        "retry_count": {
+            "type": "uint",
+            "default": 0
+        },
+        "sent_at": {
+            "type": "string"
+        },
+        "delivered_at": {
+            "type": "string",
+            "comment": "프로바이더 수신 확인 시각"
+        }
+    }
+}