create-entity-app-server 0.0.3

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

@@ -0,0 +1,56 @@
+export interface AlimtalkJob {
+    provider: string;
+    templateCode: string;
+    templateName: string;
+    receiver: string;
+    variables: Record<string, string>;
+    buttons: AlimtalkButton[];
+    refEntity: string;
+    refSeq: number;
+    msgSeq: number;
+}
+
+export interface PendingAlimtalkLog {
+    logSeq: number;
+    provider: string;
+    templateCode: string;
+    templateName: string;
+    receiver: string;
+    variablesJSON: string;
+    retryCount: number;
+    msgSeq: number;
+}
+
+export interface AlimtalkButton {
+    type: string; // "WL" (web link), "AL" (app link), "DS" (delivery), "BK" (bot keyword)
+    name: string;
+    ordering: number;
+    url_web: string;
+    url_app: string;
+    scheme: string;
+    link_mobile: string;
+    link_pc: string;
+    scheme_ios: string;
+    scheme_android: string;
+}
+
+export interface AlimtalkRequest {
+    senderKey: string;
+    templateCode: string;
+    receiver: string;
+    variables: Record<string, string>;
+    buttons: AlimtalkButton[];
+}
+
+export interface AlimtalkResult {
+    providerMsgId: string;
+    statusCode: string;
+    requestId: string;
+}
+
+export interface AlimtalkTemplate {
+    templateCode: string;
+    templateName: string;
+    content: string;
+    variables: string[];
+}

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

@@ -0,0 +1,211 @@
+/**
+ * 알림톡 웹훅 처리
+ *
+ * 각 프로바이더가 발송 결과를 POST로 통보하면
+ * provider_msg_id로 alimtalk_log를 찾아 delivered/failed 상태 갱신
+ *
+ * 지원: aligo, solapi, ppurio, nhn_cloud
+ */
+
+import { logger } from "@gateway/api";
+import type { AlimtalkQuerier } from "./types/index.ts";
+
+interface CallbackResult {
+    providerMsgId: string;
+    status: string; // "delivered" | "failed"
+    deliveredAt: string;
+    errMsg: string;
+}
+
+export class WebhookProcessor {
+    /** WebhookProcessor를 초기화한다 */
+    constructor(private readonly querier: AlimtalkQuerier) {}
+
+    /** 프로바이더 웹훅 콜백을 처리한다 */
+    async process(provider: string, body: Buffer | string): Promise<void> {
+        const result = this.parseCallback(provider, body);
+        if (!result) return;
+        if (!result.providerMsgId) {
+            throw new Error(
+                `alimtalk webhook (${provider}): provider_msg_id empty`,
+            );
+        }
+
+        await this.querier.updateAlimtalkLogDelivery(
+            result.providerMsgId,
+            result.status,
+            result.deliveredAt,
+            result.errMsg,
+        );
+
+        logger.info(
+            `Alimtalk webhook (${provider}): msg=${result.providerMsgId} status=${result.status}`,
+        );
+    }
+
+    /** 프로바이더별 콜백 본문을 파싱한다 */
+    private parseCallback(
+        provider: string,
+        body: Buffer | string,
+    ): CallbackResult | null {
+        const str = typeof body === "string" ? body : body.toString("utf-8");
+        switch (provider.toLowerCase()) {
+            case "aligo":
+                return this.parseAligo(str);
+            case "solapi":
+                return this.parseSolapi(str);
+            case "ppurio":
+                return this.parsePpurio(str);
+            case "nhn_cloud":
+            case "nhn":
+                return this.parseNHN(str);
+            default:
+                throw new Error(`Unknown webhook provider: ${provider}`);
+        }
+    }
+
+    // ─── Aligo ───────────────────────────────────────────────────────────
+    // res_code == "1000" → delivered
+
+    /** 알리고 웹훅 응답을 파싱한다 */
+    private parseAligo(body: string): CallbackResult {
+        const trimmed = body.trim();
+        let mid = "";
+        let resCode = "";
+        let resMsg = "";
+        let recvTime = "";
+
+        if (trimmed.startsWith("{")) {
+            const data = JSON.parse(trimmed) as Record<string, string>;
+            mid = data.mid ?? "";
+            resCode = data.res_code ?? "";
+            resMsg = data.res_msg ?? "";
+            recvTime = data.recv_time ?? "";
+        } else {
+            const params = new URLSearchParams(trimmed);
+            mid = params.get("mid") ?? "";
+            resCode = params.get("res_code") ?? "";
+            resMsg = params.get("res_msg") ?? "";
+            recvTime = params.get("recv_time") ?? "";
+        }
+
+        if (!mid) throw new Error("aligo: mid is empty");
+
+        return {
+            providerMsgId: mid,
+            status: resCode === "1000" ? "delivered" : "failed",
+            deliveredAt: recvTime,
+            errMsg: resCode !== "1000" ? `aligo(${resCode}): ${resMsg}` : "",
+        };
+    }
+
+    // ─── Solapi ──────────────────────────────────────────────────────────
+    // statusCode == "4000" → delivered
+
+    /** Solapi 웹훅 응답을 파싱한다 */
+    private parseSolapi(body: string): CallbackResult {
+        const data = JSON.parse(body) as Record<string, unknown>;
+
+        // 배열(messages) 형식
+        const messages = data.messages as
+            | Array<Record<string, string>>
+            | undefined;
+        if (messages?.length) {
+            const m = messages[0];
+            return solapiResult(
+                m.messageId,
+                m.statusCode,
+                m.statusName,
+                m.updatedAt,
+            );
+        }
+
+        // 단일 형식
+        const single = data as Record<string, string>;
+        if (!single.messageId) throw new Error("solapi: messageId is empty");
+        return solapiResult(
+            single.messageId,
+            single.statusCode,
+            single.statusName,
+            single.updatedAt,
+        );
+    }
+
+    // ─── Ppurio ──────────────────────────────────────────────────────────
+    // resultCode == "0" → delivered
+
+    /** 뿀리오 웹훅 응답을 파싱한다 */
+    private parsePpurio(body: string): CallbackResult {
+        const data = JSON.parse(body) as {
+            requestId?: string;
+            receivers?: Array<{
+                resultCode?: string;
+                resultMessage?: string;
+                receivedAt?: string;
+            }>;
+        };
+
+        if (!data.requestId) throw new Error("ppurio: requestId is empty");
+
+        const r = data.receivers?.[0];
+        if (r) {
+            return {
+                providerMsgId: data.requestId,
+                status: r.resultCode === "0" ? "delivered" : "failed",
+                deliveredAt: r.receivedAt ?? "",
+                errMsg:
+                    r.resultCode !== "0"
+                        ? `ppurio(${r.resultCode}): ${r.resultMessage ?? ""}`
+                        : "",
+            };
+        }
+
+        return {
+            providerMsgId: data.requestId,
+            status: "delivered",
+            deliveredAt: "",
+            errMsg: "",
+        };
+    }
+
+    // ─── NHN Cloud ───────────────────────────────────────────────────────
+    // resultCode == "MRC01" → delivered
+
+    /** NHN Cloud 웹훅 응답을 파싱한다 */
+    private parseNHN(body: string): CallbackResult {
+        const data = JSON.parse(body) as {
+            requestId?: string;
+            resultCode?: string;
+            resultMessage?: string;
+            receiveDateTime?: string;
+        };
+
+        if (!data.requestId) throw new Error("nhn_cloud: requestId is empty");
+
+        return {
+            providerMsgId: data.requestId,
+            status: data.resultCode === "MRC01" ? "delivered" : "failed",
+            deliveredAt: data.receiveDateTime ?? "",
+            errMsg:
+                data.resultCode !== "MRC01"
+                    ? `nhn_cloud(${data.resultCode}): ${data.resultMessage ?? ""}`
+                    : "",
+        };
+    }
+}
+
+/** Solapi 콜백 결과를 생성한다 */
+function solapiResult(
+    msgId: string,
+    code: string,
+    name: string,
+    updatedAt: string,
+): CallbackResult {
+    const isDelivered = code === "4000" || name?.toUpperCase() === "DELIVERED";
+    return {
+        providerMsgId: msgId ?? "",
+        status: isDelivered ? "delivered" : "failed",
+        deliveredAt: updatedAt ?? "",
+        errMsg: isDelivered ? "" : `solapi(${code}): ${name}`,
+    };
+}

package/src/app/plugins/distance-server/config.json

@@ -0,0 +1,6 @@
+{
+    "enabled": true,
+    "minify": false,
+    "url": "http://127.0.0.1:49200",
+    "timeout": 30000
+}

package/src/app/plugins/distance-server/config.ts

@@ -0,0 +1,50 @@
+/**
+ * distance-server 플러그인 설정 로더
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "@gateway/api";
+import type { DistanceServerConfig } from "./types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+export function loadDistanceServerConfig(): DistanceServerConfig | null {
+    try {
+        let raw = readFileSync(CONFIG_PATH, "utf-8");
+
+        raw = raw.replace(
+            /\$\{([^}]+)\}/g,
+            (_match, name) => process.env[name] ?? "",
+        );
+
+        const cfg: DistanceServerConfig = JSON.parse(raw);
+
+        if (cfg.enabled === false) {
+            logger.info("distance-server plugin disabled in config");
+            return null;
+        }
+
+        cfg.url = cfg.url.replace(/\/$/, "");
+        const userSecret = process.env.DISTANCE_HMAC_USER_SECRET?.trim();
+        if (!userSecret) {
+            throw new Error(
+                "DISTANCE_HMAC_USER_SECRET is required when distance-server plugin is enabled",
+            );
+        }
+
+        cfg.userSecret = userSecret;
+        cfg.timeout ??= 30_000;
+
+        return cfg;
+    } catch (err: unknown) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            logger.info("distance-server config not found, plugin skipped");
+        } else {
+            logger.error({ err }, "Failed to load distance-server config");
+        }
+        return null;
+    }
+}

package/src/app/plugins/distance-server/docs/README.md

@@ -0,0 +1,114 @@
+# Distance Server 플러그인
+
+Rust 기반 [distance-server](../../../../distance-server/README.md)로의 프록시 플러그인입니다. 항로 계산, 항구 조회, 기상 정보, 해적 위협 정보 등 물류 거리 계산 API를 제공합니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [인증 방식](#인증-방식)
+- [API](#api)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+| 항목     | 내용                                             |
+| -------- | ------------------------------------------------ |
+| 역할     | distance-server(Rust) → entity-app-server 프록시 |
+| 인증     | HMAC-SHA256 서명 (내부 서버 간)                  |
+| 기본 URL | `http://127.0.0.1:49200`                         |
+
+> 이 플러그인 자체는 데이터를 저장하지 않습니다. 모든 요청을 Rust 서버로 포워딩하고 응답을 그대로 반환합니다.
+
+---
+
+## 설정
+
+`config.json`:
+
+```json
+{
+    "enabled": true,
+    "url": "http://127.0.0.1:49200",
+    "timeout_ms": 30000,
+    "minify": false
+}
+```
+
+### 설정 항목
+
+| 항목         | 기본값                   | 설명                                              |
+| ------------ | ------------------------ | ------------------------------------------------- |
+| `enabled`    | `true`                   | 플러그인 활성화                                   |
+| `url`        | `http://127.0.0.1:49200` | distance-server 주소                              |
+| `timeout_ms` | `30000`                  | 요청 타임아웃(ms) — 항로 계산은 오래 걸릴 수 있음 |
+
+---
+
+## 인증 방식
+
+클라이언트 → entity-app-server 구간은 기존 JWT 인증을 사용합니다.  
+entity-app-server → distance-server 구간은 HMAC-SHA256 서명 헤더로 인증합니다.
+
+---
+
+## API
+
+기본 경로: `/api/v1/distance-server`
+
+### 항로
+
+| 메서드 | 경로              | 인증        | 설명                 |
+| ------ | ----------------- | ----------- | -------------------- |
+| `POST` | `/route`          | 로그인 필요 | 두 지점 간 항로 계산 |
+| `POST` | `/route-reports`  | 로그인 필요 | 항로 보고서 생성     |
+| `GET`  | `/routing-points` |             | 항로 경유지 목록     |
+
+### 항구
+
+| 메서드 | 경로     | 인증 | 설명             |
+| ------ | -------- | ---- | ---------------- |
+| `GET`  | `/ports` |      | 전세계 항구 목록 |
+
+### 기상
+
+| 메서드 | 경로                     | 인증 | 설명           |
+| ------ | ------------------------ | ---- | -------------- |
+| `GET`  | `/weather/pressure`      |      | 기압 정보      |
+| `GET`  | `/weather/typhoon`       |      | 태풍 정보      |
+| `GET`  | `/weather/ocean-current` |      | 해류 정보      |
+| `GET`  | `/weather/wind`          |      | 풍향/풍속 정보 |
+
+### 위험 구역
+
+| 메서드 | 경로           | 인증 | 설명                               |
+| ------ | -------------- | ---- | ---------------------------------- |
+| `GET`  | `/seca/list`   |      | SECA(황산화물 배출 통제 구역) 목록 |
+| `GET`  | `/piracy/list` |      | 해적 위협 지역 목록                |
+| `GET`  | `/piracy/map`  |      | 해적 위협 지도 데이터              |
+
+### POST /route 요청 예시
+
+```json
+{
+    "from": { "lat": 37.4563, "lon": 126.7052 },
+    "to": { "lat": 1.2897, "lon": 103.8501 },
+    "options": {
+        "avoid_seca": false,
+        "avoid_piracy": true
+    }
+}
+```
+
+---
+
+## 운영 팁
+
+- distance-server가 실행 중이지 않으면 모든 요청이 `503` 에러를 반환
+- 항로 계산은 최대 수 초 소요 — `timeout_ms`를 넉넉히 설정
+- 기상/해류 데이터는 distance-server 내부 캐시에서 제공
+- distance-server 별도 설정은 `/distance-server/configs/` 참고

package/src/app/plugins/distance-server/handlers.ts

@@ -0,0 +1,104 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { proxyDistanceRequest } from "./service.ts";
+
+export async function handleRoute(
+    request: FastifyRequest,
+    reply: FastifyReply,
+): Promise<unknown> {
+    return proxyDistanceRequest(request, reply, "/api/v1/route", 60_000);
+}
+
+export async function handlePorts(
+    request: FastifyRequest,
+    reply: FastifyReply,
+): Promise<unknown> {
+    return proxyDistanceRequest(request, reply, "/api/v1/ports", 10_000);
+}
+
+export async function handleWeatherPressure(
+    request: FastifyRequest,
+    reply: FastifyReply,
+): Promise<unknown> {
+    return proxyDistanceRequest(
+        request,
+        reply,
+        "/api/v1/weather/pressure",
+        15_000,
+    );
+}
+
+export async function handleWeatherTyphoon(
+    request: FastifyRequest,
+    reply: FastifyReply,
+): Promise<unknown> {
+    return proxyDistanceRequest(
+        request,
+        reply,
+        "/api/v1/weather/typhoon",
+        15_000,
+    );
+}
+
+export async function handleWeatherOceanCurrent(
+    request: FastifyRequest,
+    reply: FastifyReply,
+): Promise<unknown> {
+    return proxyDistanceRequest(
+        request,
+        reply,
+        "/api/v1/weather/ocean-current",
+        15_000,
+    );
+}
+
+export async function handleWeatherWind(
+    request: FastifyRequest,
+    reply: FastifyReply,
+): Promise<unknown> {
+    return proxyDistanceRequest(request, reply, "/api/v1/weather/wind", 15_000);
+}
+
+export async function handleSecaList(
+    request: FastifyRequest,
+    reply: FastifyReply,
+): Promise<unknown> {
+    return proxyDistanceRequest(request, reply, "/api/v1/seca/list", 10_000);
+}
+
+export async function handlePiracyList(
+    request: FastifyRequest,
+    reply: FastifyReply,
+): Promise<unknown> {
+    return proxyDistanceRequest(request, reply, "/api/v1/piracy/list", 10_000);
+}
+
+export async function handlePiracyMap(
+    request: FastifyRequest,
+    reply: FastifyReply,
+): Promise<unknown> {
+    return proxyDistanceRequest(request, reply, "/api/v1/piracy/map", 10_000);
+}
+
+export async function handleRouteReport(
+    request: FastifyRequest,
+    reply: FastifyReply,
+): Promise<unknown> {
+    return proxyDistanceRequest(
+        request,
+        reply,
+        "/api/v1/route-reports",
+        10_000,
+    );
+}
+
+export async function handleRoutingPoints(
+    request: FastifyRequest,
+    reply: FastifyReply,
+): Promise<unknown> {
+    return proxyDistanceRequest(
+        request,
+        reply,
+        "/api/v1/routing-points",
+        10_000,
+    );
+}

package/src/app/plugins/distance-server/index.ts

@@ -0,0 +1,23 @@
+/**
+ * distance-server 플러그인
+ *
+ * 실제 HTTP 경로 등록은 `*-routes.ts`에서 처리한다.
+ * 이 파일은 설정 로드와 시작 로그만 담당한다.
+ */
+
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { loadDistanceServerConfig } from "./config.ts";
+
+export default fp(
+    async (app: FastifyInstance) => {
+        const config = loadDistanceServerConfig();
+
+        if (!config) {
+            return;
+        }
+
+        app.log.info({ upstream: config.url }, "distance-server plugin ready");
+    },
+    { name: "distance-server-plugin" },
+);

package/src/app/plugins/distance-server/routes.ts

@@ -0,0 +1,36 @@
+/**
+ * distance-server 라우트 테이블
+ * 등록 경로: /api/v1/distance-server/*
+ */
+
+import type { FastifyInstance } from "fastify";
+import * as h from "./handlers.ts";
+
+export default async function distanceServerRoutes(app: FastifyInstance) {
+    // POST /api/v1/distance-server/route
+    app.post("/route", h.handleRoute);
+
+    // GET /api/v1/distance-server/ports
+    app.get("/ports", h.handlePorts);
+
+    // GET /api/v1/distance-server/weather/*
+    app.get("/weather/pressure", h.handleWeatherPressure);
+    app.get("/weather/typhoon", h.handleWeatherTyphoon);
+    app.get("/weather/ocean-current", h.handleWeatherOceanCurrent);
+    app.get("/weather/wind", h.handleWeatherWind);
+
+    // GET /api/v1/distance-server/seca/list
+    app.get("/seca/list", h.handleSecaList);
+
+    // GET /api/v1/distance-server/piracy/list
+    app.get("/piracy/list", h.handlePiracyList);
+
+    // GET /api/v1/distance-server/piracy/map
+    app.get("/piracy/map", h.handlePiracyMap);
+
+    // POST /api/v1/distance-server/route-reports
+    app.post("/route-reports", h.handleRouteReport);
+
+    // GET /api/v1/distance-server/routing-points
+    app.get("/routing-points", h.handleRoutingPoints);
+}