create-entity-app-server 0.0.3

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

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "@gateway/api";
+import type { VesselKrConfig } from "./types/index.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+export function loadVesselKrConfig(): VesselKrConfig | null {
+    if (!existsSync(CONFIG_PATH)) return null;
+
+    try {
+        const raw = readFileSync(CONFIG_PATH, "utf-8").replace(
+            /\$\{([^}]+)\}/g,
+            (_m, name) => process.env[name] ?? "",
+        );
+        const cfg = JSON.parse(raw) as VesselKrConfig;
+        if (cfg.enabled === false) {
+            logger.info("vessel_kr plugin disabled in config");
+            return null;
+        }
+        if (!cfg.apiKey) {
+            logger.warn("vessel_kr: VESSEL_API_KEY not set, plugin disabled");
+            return null;
+        }
+        return cfg;
+    } catch (err) {
+        logger.error({ err }, "vessel_kr: failed to load config");
+        return null;
+    }
+}

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

@@ -0,0 +1,167 @@
+# 선박 입항 정보 플러그인 (vessel_kr)
+
+[공공데이터포털](https://www.data.go.kr)에서 제공하는 **해양수산부 선박 입출항 정보** API를 수집합니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [환경변수](#환경변수)
+- [스케줄](#스케줄)
+- [API](#api)
+- [데이터 구조](#데이터-구조)
+
+---
+
+## 개요
+
+| 항목        | 내용                                          |
+| ----------- | --------------------------------------------- |
+| 데이터 소스 | 공공데이터포털 `VsslEtrynd5` API (XML 응답)   |
+| API URL     | `https://apis.data.go.kr/1192000/VsslEtrynd5` |
+| 수집 단위   | 입항일 기준 일별 (synced_date)                |
+| 인증 방식   | 공공데이터포털 서비스 키 필요                 |
+| 기본 주기   | 매일 03:00 (`0 3 * * *`)                      |
+
+---
+
+## 설정
+
+`config.json` — 플러그인 폴더에 위치:
+
+```json
+{
+    "enabled": true,
+    "entity": "vessel_kr_entry",
+    "apiKey": "서비스키",
+    "prtAgCodes": ["011", "021"],
+    "syncDays": 1
+}
+```
+
+### 설정 항목
+
+| 항목         | 필수 | 기본값            | 설명                                            |
+| ------------ | ---- | ----------------- | ----------------------------------------------- |
+| `enabled`    | ✅   | —                 | `false`로 설정하면 플러그인·스케줄 모두 비활성  |
+| `entity`     |      | `vessel_kr_entry` | 저장 엔티티명                                   |
+| `apiKey`     | ✅   | —                 | 공공데이터포털에서 발급한 서비스 키 (인코딩 키) |
+| `prtAgCodes` | ✅   | —                 | 수집할 항만청 코드 배열 (아래 표 참조)          |
+| `syncDays`   |      | `1`               | 매일 수집 시 소급 일수                          |
+
+### 주요 항만청 코드 (prtAgCodes)
+
+| 코드  | 항만청          |
+| ----- | --------------- |
+| `011` | 인천항만청      |
+| `021` | 부산항만청      |
+| `031` | 여수·광양항만청 |
+| `041` | 울산항만청      |
+| `051` | 경인항만청      |
+
+---
+
+## 환경변수
+
+```env
+VESSEL_KR_API_KEY=공공데이터포털_인코딩_서비스키
+```
+
+`config.json`의 `apiKey`를 환경변수로 대체할 경우 위 값을 사용합니다.
+
+### 공공데이터포털 API 키 발급
+
+1. [data.go.kr](https://www.data.go.kr) 로그인 후 마이페이지 → 인증키 발급
+2. 검색창에 `선박 입출항 정보` 또는 `VsslEtrynd5` 검색
+3. 활용 신청 → 승인 후 **인코딩 서비스키** 복사
+4. `config.json`의 `apiKey` 또는 `.env`의 `VESSEL_KR_API_KEY`에 붙여넣기
+
+---
+
+## 스케줄
+
+스케줄 설정은 `app/schedules/vessel_kr_sync/config.json`에서 관리합니다.
+
+```json
+{
+    "enabled": true,
+    "cron": "0 3 * * *"
+}
+```
+
+입항 데이터는 당일 새벽 이후 반영됩니다. 03:00 수집을 권장합니다.
+
+---
+
+## API
+
+기본 경로: `/api/v1/vessel_kr`
+
+| 메서드 | 경로            | 인증        | 설명                |
+| ------ | --------------- | ----------- | ------------------- |
+| `GET`  | `/entries`      |             | 입항 정보 목록 조회 |
+| `GET`  | `/entries/:seq` |             | 입항 정보 단건 조회 |
+| `POST` | `/sync`         | 로그인 필요 | 수동 동기화         |
+
+### GET /entries 쿼리 파라미터
+
+| 파라미터      | 타입   | 설명                               |
+| ------------- | ------ | ---------------------------------- |
+| `prt_ag_cd`   | string | 항만청 코드 필터 (`011`, `021` 등) |
+| `vssl_nm`     | string | 선박명 부분 검색                   |
+| `clsgn`       | string | 호출부호 (콜사인) 검색             |
+| `etryn_nm`    | string | 입항지명 검색                      |
+| `synced_date` | string | 수집일 필터 (YYYYMMDD)             |
+| `date_from`   | string | 입항일 시작 (YYYYMMDD)             |
+| `date_to`     | string | 입항일 종료 (YYYYMMDD)             |
+| `limit`       | number | 최대 결과 수 (기본 50, 최대 200)   |
+| `offset`      | number | 페이지 오프셋 (기본 0)             |
+
+### POST /sync 요청 바디
+
+```json
+{
+    "date": "20260322"
+}
+```
+
+바디 생략 시 `syncDays` 기준 최근 N일을 수집합니다.
+
+### 응답 예시 (GET /entries)
+
+```json
+{
+    "ok": true,
+    "data": [
+        {
+            "seq": 1,
+            "prt_ag_cd": "021",
+            "vssl_nm": "ELIM STAR",
+            "clsgn": "HLAA1",
+            "gross_tonnage": 50000,
+            "etryn_nm": "부산항",
+            "etryn_dt": "20260321",
+            "synced_date": "20260322"
+        }
+    ]
+}
+```
+
+---
+
+## 데이터 구조
+
+Entity: `vessel_kr_entry`
+
+| 컬럼            | 타입         | 설명              |
+| --------------- | ------------ | ----------------- |
+| `seq`           | integer (PK) | 자동 증가         |
+| `prt_ag_cd`     | varchar      | 항만청 코드       |
+| `vssl_nm`       | varchar      | 선박명            |
+| `clsgn`         | varchar      | 호출부호 (콜사인) |
+| `gross_tonnage` | integer      | 총톤수            |
+| `etryn_nm`      | varchar      | 입항지명          |
+| `etryn_dt`      | varchar      | 입항일 (YYYYMMDD) |
+| `synced_date`   | varchar      | 수집일 (YYYYMMDD) |

package/src/app/plugins/vessel_kr/entities/vessel_kr_entry.json

@@ -0,0 +1,136 @@
+{
+    "name": "vessel_kr_entry",
+    "description": "선박 입출항 신고 정보 - 한국 (해양수산부 선박운항정보 API)",
+    "fields": {
+        "prt_ag_cd": {
+            "type": "varchar(8)",
+            "index": true,
+            "comment": "항만청 코드 (예: 011=인천, 021=부산)"
+        },
+        "prt_ag_nm": {
+            "comment": "항만청 명칭"
+        },
+        "clsgn": {
+            "type": "varchar(20)",
+            "index": true,
+            "comment": "호출부호 (Call Sign)"
+        },
+        "vssl_nm": {
+            "index": true,
+            "comment": "선박명"
+        },
+        "vssl_nlty_cd": {
+            "type": "varchar(8)",
+            "index": true,
+            "comment": "선박 국적 코드"
+        },
+        "vssl_nlty_nm": {
+            "comment": "선박 국적명"
+        },
+        "vssl_knd_cd": {
+            "type": "varchar(8)",
+            "index": true,
+            "comment": "선종 코드"
+        },
+        "vssl_knd_nm": {
+            "comment": "선종명"
+        },
+        "etrypt_purps_cd": {
+            "type": "varchar(8)",
+            "comment": "입항목적 코드"
+        },
+        "etrypt_purps_nm": {
+            "comment": "입항목적명"
+        },
+        "etryn_nm": {
+            "type": "varchar(10)",
+            "index": true,
+            "comment": "입출항 구분명 (입항/출항)"
+        },
+        "reqst_se_nm": {
+            "comment": "신고구분명"
+        },
+        "etrypt_dt": {
+            "type": "varchar(20)",
+            "index": true,
+            "comment": "입항 일시 (YYYYMMDDHHMM)"
+        },
+        "tkoff_dt": {
+            "type": "varchar(20)",
+            "index": true,
+            "comment": "출항 일시 (YYYYMMDDHHMM)"
+        },
+        "ibobprt_nm": {
+            "index": true,
+            "comment": "입출항 항구명"
+        },
+        "laidup_fclty_nm": {
+            "comment": "계류시설명"
+        },
+        "tug_yn": {
+            "type": "varchar(2)",
+            "comment": "예선 여부 (Y/N)"
+        },
+        "piltg_yn": {
+            "type": "varchar(2)",
+            "comment": "도선 여부 (Y/N)"
+        },
+        "grtg": {
+            "type": "varchar(20)",
+            "comment": "총톤수"
+        },
+        "intrl_grtg": {
+            "type": "varchar(20)",
+            "comment": "국제총톤수"
+        },
+        "crew_co": {
+            "type": "varchar(10)",
+            "comment": "선원수 (전체)"
+        },
+        "koran_crew_co": {
+            "type": "varchar(10)",
+            "comment": "한국인 선원수"
+        },
+        "frgnr_crew_co": {
+            "type": "varchar(10)",
+            "comment": "외국인 선원수"
+        },
+        "mr_num": {
+            "type": "varchar(20)",
+            "index": true,
+            "comment": "IMO 번호"
+        },
+        "satmnt_entrps_nm": {
+            "comment": "선박 대리점명"
+        },
+        "frst_dpmprt_prt_nm": {
+            "comment": "최초 출발항구명"
+        },
+        "prvs_dpmprt_prt_nm": {
+            "comment": "직전 출발항구명"
+        },
+        "nxlnpt_prt_nm": {
+            "comment": "다음 입항항구명"
+        },
+        "dstn_prt_nm": {
+            "comment": "최종 목적지항구명"
+        },
+        "ldadng_ton": {
+            "type": "varchar(20)",
+            "comment": "적재 톤수"
+        },
+        "landng_frght_ton": {
+            "type": "varchar(20)",
+            "comment": "양하 화물 톤수"
+        },
+        "ld_frght_ton": {
+            "type": "varchar(20)",
+            "comment": "적화 톤수"
+        },
+        "synced_date": {
+            "type": "varchar(10)",
+            "index": true,
+            "comment": "데이터 수집 기준일 (YYYYMMDD)"
+        }
+    }
+}

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

@@ -0,0 +1,102 @@
+import type { FastifyRequest, FastifyReply } from "fastify";
+import {
+    ok,
+    fail,
+    entityServer,
+    BadRequestError,
+    NotFoundError,
+} from "@gateway/api";
+
+// ─── 목록 조회 ───────────────────────────────────────────────────
+
+interface ListQuery {
+    prt_ag_cd?: string;
+    vssl_nm?: string;
+    clsgn?: string;
+    etryn_nm?: string;
+    synced_date?: string;
+    date_from?: string;
+    date_to?: string;
+    limit?: string;
+    offset?: string;
+}
+
+export async function listEntries(
+    req: FastifyRequest<{ Querystring: ListQuery }>,
+    reply: FastifyReply,
+) {
+    const {
+        prt_ag_cd,
+        vssl_nm,
+        clsgn,
+        etryn_nm,
+        synced_date,
+        date_from,
+        date_to,
+        limit = "50",
+        offset = "0",
+    } = req.query;
+
+    const where: Record<string, unknown> = {};
+    if (prt_ag_cd) where.prt_ag_cd = prt_ag_cd;
+    if (vssl_nm) where.vssl_nm = { like: `%${vssl_nm}%` };
+    if (clsgn) where.clsgn = clsgn;
+    if (etryn_nm) where.etryn_nm = etryn_nm;
+    if (synced_date) where.synced_date = synced_date;
+    if (date_from && date_to) {
+        where.synced_date = { between: [date_from, date_to] };
+    } else if (date_from) {
+        where.synced_date = { gte: date_from };
+    } else if (date_to) {
+        where.synced_date = { lte: date_to };
+    }
+
+    const result = await entityServer.find("vessel_kr_entry", {
+        where,
+        limit: Math.min(Number(limit), 200),
+        offset: Number(offset),
+        orderBy: [{ field: "etrypt_dt", direction: "desc" }],
+    });
+
+    return reply.send(ok(result));
+}
+
+// ─── 단건 조회 ───────────────────────────────────────────────────
+
+export async function getEntry(
+    req: FastifyRequest<{ Params: { seq: string } }>,
+    reply: FastifyReply,
+) {
+    const seq = Number(req.params.seq);
+    if (!seq || isNaN(seq)) throw new BadRequestError("seq must be a number");
+
+    const result = await entityServer.get("vessel_kr_entry", seq);
+    if (!result) throw new NotFoundError("vessel entry not found");
+
+    return reply.send(ok(result));
+}
+
+// ─── 수동 동기화 ─────────────────────────────────────────────────
+
+interface SyncBody {
+    date?: string; // YYYYMMDD, 생략 시 config.syncDays 기간 전체
+}
+
+export async function triggerSync(
+    req: FastifyRequest<{ Body: SyncBody }>,
+    reply: FastifyReply,
+) {
+    const service = req.server
+        .vesselKrService as import("./service.ts").VesselKrService;
+    const { date } = req.body ?? {};
+
+    if (date) {
+        if (!/^\d{8}$/.test(date))
+            throw new BadRequestError("date must be YYYYMMDD");
+        const result = await service.syncDate(date);
+        return reply.send(ok({ date, ...result }));
+    }
+
+    const result = await service.syncAll();
+    return reply.send(ok(result));
+}

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

@@ -0,0 +1,21 @@
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { ensurePluginEntities } from "@gateway/api";
+import { loadVesselKrConfig } from "./config.ts";
+import { VesselKrService } from "./service.ts";
+
+export default fp(
+    async (app: FastifyInstance) => {
+        const config = loadVesselKrConfig();
+        if (!config) return;
+
+        // 엔티티 스키마 등록
+        await ensurePluginEntities(import.meta.url);
+
+        const service = new VesselKrService(config);
+
+        // 서비스 인스턴스를 Fastify 데코레이터로 노출 (라우트 로더가 routes.ts를 별도 등록)
+        app.decorate("vesselKrService", service);
+    },
+    { name: "vessel_kr" },
+);

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

@@ -0,0 +1,15 @@
+import type { FastifyInstance } from "fastify";
+import * as h from "./handlers.ts";
+
+export default async function vesselKrRoutes(app: FastifyInstance) {
+    // GET /api/v1/vessel_kr/entries        — 목록 조회
+    app.get("/entries", h.listEntries);
+
+    // GET /api/v1/vessel_kr/entries/:seq   — 단건 조회
+    app.get("/entries/:seq", h.getEntry);
+
+    // POST /api/v1/vessel_kr/sync          — 수동 동기화 (관리자용)
+    app.post("/sync", { preHandler: [app.authRequired] }, (req, reply) =>
+        h.triggerSync(req as Parameters<typeof h.triggerSync>[0], reply),
+    );
+}