create-entity-app-server 0.0.3

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

@@ -0,0 +1,604 @@
+import { logger, entityServer } from "@gateway/api";
+import type {
+    KobcFreightConfig,
+    KobcFreightRow,
+    KobcFreightRecord,
+    KobcKcciRow,
+    KobcNcfiRow,
+    KobcKpliRow,
+} from "./types/index.ts";
+
+const KOBC_URL = "https://kobc.or.kr/ebz/shippinginfo/kdci/gridList.do";
+const MID = "0301000000";
+const ENTITY = "kobc_freight_entry";
+
+const KCCI_URL = "https://kobc.or.kr/ebz/shippinginfo/kcci/gridList.do";
+const KCCI_MID = "0304000000";
+const KCCI_ENTITY = "kobc_kcci_entry";
+
+const NCFI_URL = "https://kobc.or.kr/ebz/shippinginfo/ncfi/gridList.do";
+const NCFI_MID = "0305000000";
+const NCFI_ENTITY = "kobc_ncfi_entry";
+
+const KPLI_URL = "https://kobc.or.kr/ebz/shippinginfo/kpli/gridList.do";
+const KPLI_MID = "0306000000";
+const KPLI_ENTITY = "kobc_kpli_entry";
+
+// ────────────────────────── 날짜 유틸 ──────────────────────────────
+
+function toISO(d: Date): string {
+    return d.toISOString().slice(0, 10); // YYYY-MM-DD
+}
+
+function addDays(d: Date, n: number): Date {
+    const r = new Date(d);
+    r.setDate(r.getDate() + n);
+    return r;
+}
+
+/** today 기준으로 오늘을 포함한 지난 N일 목록. 시작일은 startDate 이상. */
+function buildDateRange(syncDays: number): {
+    startDate: string;
+    endDate: string;
+} {
+    const today = new Date();
+    const start = addDays(today, -(syncDays - 1));
+    return { startDate: toISO(start), endDate: toISO(today) };
+}
+
+/** YYYY-MM-DD 문자열 날짜를 90일 단위로 청크 분할 */
+function chunkDateRange(
+    from: string,
+    to: string,
+    chunkDays = 90,
+): Array<[string, string]> {
+    const chunks: Array<[string, string]> = [];
+    let cur = new Date(from);
+    const end = new Date(to);
+    while (cur <= end) {
+        const chunkEnd = addDays(cur, chunkDays - 1);
+        chunks.push([toISO(cur), toISO(chunkEnd > end ? end : chunkEnd)]);
+        cur = addDays(chunkEnd, 1);
+    }
+    return chunks;
+}
+
+// ────────────────────── HTML 스크래핑 ──────────────────────────────
+
+/**
+ * KOBC 사이트에 POST 요청을 보내 건화물선운임지수 데이터를 가져옵니다.
+ * 날짜 범위가 너무 넓으면 청크로 나눠 호출합니다.
+ */
+export async function fetchFreightRows(
+    startDate: string,
+    endDate: string,
+): Promise<KobcFreightRow[]> {
+    const body = new URLSearchParams({
+        mId: MID,
+        startDate,
+        endDate,
+    });
+
+    const res = await fetch(`${KOBC_URL}?mId=${MID}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "User-Agent":
+                "Mozilla/5.0 (compatible; entity-app-server/1.0; +https://kobc.or.kr)",
+            Referer: `${KOBC_URL}?mId=${MID}`,
+            Accept: "text/html,application/xhtml+xml",
+        },
+        body: body.toString(),
+        signal: AbortSignal.timeout(30_000),
+    });
+
+    if (!res.ok) {
+        throw new Error(`kobc_freight: HTTP ${res.status} from KOBC`);
+    }
+
+    const html = await res.text();
+    return parseFreightTable(html);
+}
+
+/** HTML `<tbody>` 에서 운임지수 행을 추출합니다. */
+function parseFreightTable(html: string): KobcFreightRow[] {
+    const rows: KobcFreightRow[] = [];
+
+    // <tbody> 섹션 추출
+    const tbodyMatch = html.match(/<tbody[^>]*>([\s\S]*?)<\/tbody>/i);
+    if (!tbodyMatch) return rows;
+
+    const tbody = tbodyMatch[1];
+    const rowRegex = /<tr[^>]*>([\s\S]*?)<\/tr>/gi;
+
+    for (const rowMatch of tbody.matchAll(rowRegex)) {
+        const cells = [
+            ...rowMatch[1].matchAll(/<td[^>]*>([\s\S]*?)<\/td>/gi),
+        ].map((m) => m[1].replace(/<[^>]*>/g, "").trim());
+
+        if (cells.length !== 6) continue;
+
+        const [indexDate, kdciRaw, capeRaw, panamaxRaw, supramaxRaw, handyRaw] =
+            cells;
+
+        // 날짜 형식 검증 (YYYY-MM-DD)
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(indexDate)) continue;
+
+        rows.push({
+            index_date: indexDate,
+            kdci: parseNum(kdciRaw),
+            cape: parseNum(capeRaw),
+            panamax: parseNum(panamaxRaw),
+            supramax: parseNum(supramaxRaw),
+            handy: parseNum(handyRaw),
+        });
+    }
+
+    return rows;
+}
+
+function parseNum(s: string): number {
+    return parseInt(s.replace(/,/g, ""), 10) || 0;
+}
+
+function parseFloat2(s: string): number {
+    return parseFloat(s.replace(/,/g, "")) || 0;
+}
+
+// ─────────────────── KCCI 스크래핑 ───────────────────────────────────────────
+
+/**
+ * code(7셀: cells[1], 6셀: cells[0]) → 컬럼명 매핑
+ * 날짜 파라미터 무관 — 항상 최신 데이터 반환
+ */
+const KCCI_CODE_MAP: Partial<
+    Record<string, keyof Omit<KobcKcciRow, "index_date">>
+> = {
+    KCCI: "kcci",
+    KUWI: "kuwi",
+    KUEI: "kuei",
+    KNEI: "knei",
+    KMDI: "kmdi",
+    KMEI: "kmei",
+    KAUI: "kaui",
+    KLEI: "klei",
+    KLWI: "klwi",
+    KSAI: "ksai",
+    KWAI: "kwai",
+    KCI: "kci",
+    KJI: "kji",
+    KSEI: "ksei",
+};
+
+export async function fetchKcciSnapshot(): Promise<
+    Omit<KobcKcciRow, "index_date">
+> {
+    const today = toISO(new Date());
+    const body = new URLSearchParams({
+        mId: KCCI_MID,
+        startDate: today,
+        endDate: today,
+    });
+    const res = await fetch(`${KCCI_URL}?mId=${KCCI_MID}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "User-Agent":
+                "Mozilla/5.0 (compatible; entity-app-server/1.0; +https://kobc.or.kr)",
+            Referer: `${KCCI_URL}?mId=${KCCI_MID}`,
+            Accept: "text/html,application/xhtml+xml",
+        },
+        body: body.toString(),
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok) throw new Error(`kobc_kcci: HTTP ${res.status} from KOBC`);
+    return parseKcciTable(await res.text());
+}
+
+function parseKcciTable(html: string): Omit<KobcKcciRow, "index_date"> {
+    const result: Partial<Omit<KobcKcciRow, "index_date">> = {};
+    const tbodyMatch = html.match(/<tbody[^>]*>([\s\S]*?)<\/tbody>/i);
+    if (!tbodyMatch) return result as Omit<KobcKcciRow, "index_date">;
+
+    for (const rowMatch of tbodyMatch[1].matchAll(
+        /<tr[^>]*>([\s\S]*?)<\/tr>/gi,
+    )) {
+        const cells = [
+            ...rowMatch[1].matchAll(/<td[^>]*>([\s\S]*?)<\/td>/gi),
+        ].map((m) => m[1].replace(/<[^>]*>/g, "").trim());
+        // 7셀: [category, CODE, route, weight, current, prev, change]
+        // 6셀: [CODE, route, weight, current, prev, change]
+        const code =
+            cells.length === 7
+                ? cells[1]
+                : cells.length === 6
+                  ? cells[0]
+                  : null;
+        const valueStr =
+            cells.length === 7
+                ? cells[4]
+                : cells.length === 6
+                  ? cells[3]
+                  : null;
+        if (!code || !valueStr) continue;
+        const col = KCCI_CODE_MAP[code];
+        if (col) result[col] = parseNum(valueStr);
+    }
+    return result as Omit<KobcKcciRow, "index_date">;
+}
+
+// ─────────────────── NCFI 스크래핑 ───────────────────────────────────────────
+
+/**
+ * 항로명 → 컬럼명 매핑
+ * 날짜 파라미터 무관 — 항상 최신 데이터 반환
+ */
+const NCFI_ROUTE_MAP: Partial<
+    Record<string, keyof Omit<KobcNcfiRow, "index_date">>
+> = {
+    "Composite Index": "composite",
+    Europe: "europe",
+    "West Mediterranean": "west_med",
+    "East Mediterranean": "east_med",
+    "West America": "west_america",
+    "East America": "east_america",
+    Mideast: "mideast",
+    "West South America": "west_south_america",
+    "East South America": "east_south_america",
+    "India &Pakistan": "india_pakistan",
+    "Red Sea": "red_sea",
+    "Australia& New Zealand": "australia_nz",
+    "East Japan": "east_japan",
+    "West Japan": "west_japan",
+    "Thailand& Vietnam": "thailand_vietnam",
+    "Singapore& Malaysia": "singapore_malaysia",
+    Philippines: "philippines",
+    "Black Sea": "black_sea",
+    "West Africa": "west_africa",
+    "South Africa": "south_africa",
+    "East Africa": "east_africa",
+    "North Africa": "north_africa",
+};
+
+export async function fetchNcfiSnapshot(): Promise<
+    Omit<KobcNcfiRow, "index_date">
+> {
+    const today = toISO(new Date());
+    const body = new URLSearchParams({
+        mId: NCFI_MID,
+        startDate: today,
+        endDate: today,
+    });
+    const res = await fetch(`${NCFI_URL}?mId=${NCFI_MID}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "User-Agent":
+                "Mozilla/5.0 (compatible; entity-app-server/1.0; +https://kobc.or.kr)",
+            Referer: `${NCFI_URL}?mId=${NCFI_MID}`,
+            Accept: "text/html,application/xhtml+xml",
+        },
+        body: body.toString(),
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok) throw new Error(`kobc_ncfi: HTTP ${res.status} from KOBC`);
+    return parseNcfiTable(await res.text());
+}
+
+function parseNcfiTable(html: string): Omit<KobcNcfiRow, "index_date"> {
+    const result: Partial<Omit<KobcNcfiRow, "index_date">> = {};
+    const tbodyMatch = html.match(/<tbody[^>]*>([\s\S]*?)<\/tbody>/i);
+    if (!tbodyMatch) return result as Omit<KobcNcfiRow, "index_date">;
+
+    for (const rowMatch of tbodyMatch[1].matchAll(
+        /<tr[^>]*>([\s\S]*?)<\/tr>/gi,
+    )) {
+        const cells = [
+            ...rowMatch[1].matchAll(/<td[^>]*>([\s\S]*?)<\/td>/gi),
+        ].map((m) => m[1].replace(/<[^>]*>/g, "").trim());
+        // [route_name, current_value, prev_value, change_pct]
+        if (cells.length < 2) continue;
+        const col = NCFI_ROUTE_MAP[cells[0]];
+        if (col) result[col] = parseFloat2(cells[1]);
+    }
+    return result as Omit<KobcNcfiRow, "index_date">;
+}
+
+// ─────────────────── KPLI 스크래핑 ───────────────────────────────────────────
+
+/** 날짜 범위 쿼리 지원 — 주간 시계열 데이터 */
+export async function fetchKpliRows(
+    startDate: string,
+    endDate: string,
+): Promise<KobcKpliRow[]> {
+    const body = new URLSearchParams({ mId: KPLI_MID, startDate, endDate });
+    const res = await fetch(`${KPLI_URL}?mId=${KPLI_MID}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "User-Agent":
+                "Mozilla/5.0 (compatible; entity-app-server/1.0; +https://kobc.or.kr)",
+            Referer: `${KPLI_URL}?mId=${KPLI_MID}`,
+            Accept: "text/html,application/xhtml+xml",
+        },
+        body: body.toString(),
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok) throw new Error(`kobc_kpli: HTTP ${res.status} from KOBC`);
+    return parseKpliTable(await res.text());
+}
+
+function parseKpliTable(html: string): KobcKpliRow[] {
+    const rows: KobcKpliRow[] = [];
+    const tbodyMatch = html.match(/<tbody[^>]*>([\s\S]*?)<\/tbody>/i);
+    if (!tbodyMatch) return rows;
+
+    for (const rowMatch of tbodyMatch[1].matchAll(
+        /<tr[^>]*>([\s\S]*?)<\/tr>/gi,
+    )) {
+        const cells = [
+            ...rowMatch[1].matchAll(/<td[^>]*>([\s\S]*?)<\/td>/gi),
+        ].map((m) => m[1].replace(/<[^>]*>/g, "").trim());
+        // [date, port_efficiency, total_voyage_time, waiting_time, schedule_reliability]
+        if (cells.length !== 5) continue;
+        const [indexDate, pe, tvt, wt, sr] = cells;
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(indexDate)) continue;
+        rows.push({
+            index_date: indexDate,
+            port_efficiency: parseFloat2(pe),
+            total_voyage_time: parseFloat2(tvt),
+            waiting_time: parseFloat2(wt),
+            schedule_reliability: parseFloat2(sr),
+        });
+    }
+    return rows;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class KobcFreightService {
+    constructor(private readonly config: KobcFreightConfig) {}
+
+    get entityName(): string {
+        return this.config.entity ?? ENTITY;
+    }
+
+    /**
+     * 특정 날짜 범위를 수집·저장합니다.
+     * 기존 레코드는 같은 index_date로 삭제 후 재삽입.
+     */
+    async syncRange(
+        startDate: string,
+        endDate: string,
+    ): Promise<{ saved: number; errors: number }> {
+        let saved = 0;
+        let errors = 0;
+
+        const chunks = chunkDateRange(startDate, endDate);
+        for (const [chunkStart, chunkEnd] of chunks) {
+            try {
+                const rows = await fetchFreightRows(chunkStart, chunkEnd);
+                if (rows.length === 0) continue;
+
+                // 기존 레코드 삭제 (같은 날짜 범위)
+                await this.deleteRange(chunkStart, chunkEnd);
+
+                // 新 레코드 저장
+                const records: KobcFreightRecord[] = rows.map((r) => ({
+                    ...r,
+                }));
+                for (const record of records) {
+                    await entityServer.submit(this.entityName, record);
+                }
+                saved += records.length;
+            } catch (err) {
+                logger.error(
+                    { err, chunkStart, chunkEnd },
+                    "kobc_freight: sync chunk failed",
+                );
+                errors++;
+            }
+        }
+
+        return { saved, errors };
+    }
+
+    /**
+     * 최근 syncDays일 데이터를 수집합니다 (스케줄 호출용).
+     * initialSyncFrom이 설정된 경우, 데이터가 비어 있을 때 최초 전체 수집을 수행합니다.
+     */
+    async syncRecent(): Promise<{
+        saved: number;
+        errors: number;
+        rangeStart: string;
+        rangeEnd: string;
+    }> {
+        const syncDays = this.config.syncDays ?? 5;
+
+        // 데이터가 없으면 initialSyncFrom부터 전체 수집
+        if (this.config.initialSyncFrom) {
+            const count = await this.countAll();
+            if (count === 0) {
+                logger.info(
+                    { from: this.config.initialSyncFrom },
+                    "kobc_freight: initial full sync",
+                );
+                const endDate = toISO(new Date());
+                const result = await this.syncRange(
+                    this.config.initialSyncFrom,
+                    endDate,
+                );
+                return {
+                    ...result,
+                    rangeStart: this.config.initialSyncFrom,
+                    rangeEnd: endDate,
+                };
+            }
+        }
+
+        const { startDate, endDate } = buildDateRange(syncDays);
+        const result = await this.syncRange(startDate, endDate);
+        return { ...result, rangeStart: startDate, rangeEnd: endDate };
+    }
+
+    private async deleteRange(
+        startDate: string,
+        endDate: string,
+    ): Promise<void> {
+        const existing = await entityServer.find<{ seq: number }[]>(
+            this.entityName,
+            {
+                where: { index_date: { between: [startDate, endDate] } },
+                limit: 500,
+            },
+        );
+        const list = Array.isArray(existing) ? existing : [];
+        for (const rec of list) {
+            await entityServer.delete(this.entityName, rec.seq);
+        }
+    }
+
+    private async countAll(): Promise<number> {
+        const result = await entityServer.find<{ seq: number }[]>(
+            this.entityName,
+            {
+                limit: 1,
+            },
+        );
+        // 단순히 1건 이상이면 데이터 있음
+        const list = Array.isArray(result) ? result : [];
+        return list.length;
+    }
+
+    // ─────────────────── KCCI 동기화 ────────────────────────────────────────
+
+    /**
+     * 오늘의 KCCI 스냅샷을 수집·저장합니다.
+     * KCCI 엔드포인트는 날짜와 무관하게 항상 최신 데이터를 반환하므로
+     * 매일 한 번 실행하여 당일 날짜로 저장합니다.
+     */
+    async syncKcci(): Promise<{ saved: number }> {
+        const today = toISO(new Date());
+        try {
+            const snapshot = await fetchKcciSnapshot();
+            await this.deleteEntityByDate(KCCI_ENTITY, today);
+            await entityServer.submit(KCCI_ENTITY, {
+                index_date: today,
+                ...snapshot,
+            });
+            return { saved: 1 };
+        } catch (err) {
+            logger.error({ err }, "kobc_kcci: sync failed");
+            return { saved: 0 };
+        }
+    }
+
+    // ─────────────────── NCFI 동기화 ────────────────────────────────────────
+
+    /**
+     * 오늘의 NCFI 스냅샷을 수집·저장합니다.
+     * NCFI 엔드포인트도 날짜와 무관하게 항상 최신 데이터를 반환합니다.
+     */
+    async syncNcfi(): Promise<{ saved: number }> {
+        const today = toISO(new Date());
+        try {
+            const snapshot = await fetchNcfiSnapshot();
+            await this.deleteEntityByDate(NCFI_ENTITY, today);
+            await entityServer.submit(NCFI_ENTITY, {
+                index_date: today,
+                ...snapshot,
+            });
+            return { saved: 1 };
+        } catch (err) {
+            logger.error({ err }, "kobc_ncfi: sync failed");
+            return { saved: 0 };
+        }
+    }
+
+    // ─────────────────── KPLI 동기화 ────────────────────────────────────────
+
+    /**
+     * 특정 날짜 범위의 KPLI 데이터를 수집·저장합니다.
+     * KPLI는 날짜 범위 쿼리를 지원하는 주간 시계열 데이터입니다.
+     */
+    async syncKpliRange(
+        startDate: string,
+        endDate: string,
+    ): Promise<{ saved: number; errors: number }> {
+        let saved = 0;
+        let errors = 0;
+
+        const chunks = chunkDateRange(startDate, endDate);
+        for (const [chunkStart, chunkEnd] of chunks) {
+            try {
+                const rows = await fetchKpliRows(chunkStart, chunkEnd);
+                if (rows.length === 0) continue;
+                await this.deleteEntityRange(KPLI_ENTITY, chunkStart, chunkEnd);
+                for (const record of rows) {
+                    await entityServer.submit(
+                        KPLI_ENTITY,
+                        record as unknown as Record<string, unknown>,
+                    );
+                }
+                saved += rows.length;
+            } catch (err) {
+                logger.error(
+                    { err, chunkStart, chunkEnd },
+                    "kobc_kpli: sync chunk failed",
+                );
+                errors++;
+            }
+        }
+        return { saved, errors };
+    }
+
+    /**
+     * 최근 syncDays일 KPLI 데이터를 수집합니다 (스케줄 호출용).
+     * KPLI는 주간 데이터이므로 최소 7일 이상 소급이 권장됩니다.
+     */
+    async syncKpliRecent(): Promise<{
+        saved: number;
+        errors: number;
+        rangeStart: string;
+        rangeEnd: string;
+    }> {
+        // KPLI는 주간 데이터 — syncDays와 별개로 최소 14일 소급
+        const syncDays = Math.max(this.config.syncDays ?? 5, 14);
+        const { startDate, endDate } = buildDateRange(syncDays);
+        const result = await this.syncKpliRange(startDate, endDate);
+        return { ...result, rangeStart: startDate, rangeEnd: endDate };
+    }
+
+    // ─────────────────── 내부 헬퍼 ──────────────────────────────────────────
+
+    /** 특정 엔티티에서 지정 날짜 레코드를 삭제합니다 */
+    private async deleteEntityByDate(
+        entity: string,
+        date: string,
+    ): Promise<void> {
+        const existing = await entityServer.find<{ seq: number }[]>(entity, {
+            where: { index_date: date },
+            limit: 10,
+        });
+        const list = Array.isArray(existing) ? existing : [];
+        for (const rec of list) {
+            await entityServer.delete(entity, rec.seq);
+        }
+    }
+
+    /** 특정 엔티티에서 날짜 범위 레코드를 삭제합니다 */
+    private async deleteEntityRange(
+        entity: string,
+        startDate: string,
+        endDate: string,
+    ): Promise<void> {
+        const existing = await entityServer.find<{ seq: number }[]>(entity, {
+            where: { index_date: { between: [startDate, endDate] } },
+            limit: 500,
+        });
+        const list = Array.isArray(existing) ? existing : [];
+        for (const rec of list) {
+            await entityServer.delete(entity, rec.seq);
+        }
+    }
+}

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

@@ -0,0 +1,99 @@
+/** Plugin 설정 */
+export interface KobcFreightConfig {
+    /** 플러그인 활성화 여부 (false면 비활성) */
+    enabled: boolean;
+    /** 엔티티 명칭 */
+    entity?: string;
+    /** 최초 수집 시작일 (YYYY-MM-DD). 없으면 최근 syncDays일만 수집 */
+    initialSyncFrom?: string;
+    /** 일별 스케줄에서 소급 수집할 일수 (기본 5 — 주말·공휴일 커버) */
+    syncDays?: number;
+}
+
+/** KOBC가 반환하는 HTML 테이블 한 행의 parsed 결과 */
+export interface KobcFreightRow {
+    /** YYYY-MM-DD */
+    index_date: string;
+    kdci: number;
+    cape: number;
+    panamax: number;
+    supramax: number;
+    handy: number;
+}
+
+/** Entity Server에 저장되는 레코드 */
+export interface KobcFreightRecord extends Record<string, unknown> {
+    index_date: string;
+    kdci: number;
+    cape: number;
+    panamax: number;
+    supramax: number;
+    handy: number;
+}
+
+// ─────────────────── KCCI (컨테이너선운임지수) ────────────────────────────────
+
+/** KCCI 스냅샷 — 14개 코드 값 */
+export interface KobcKcciRow {
+    index_date: string;
+    kcci: number;
+    kuwi: number;
+    kuei: number;
+    knei: number;
+    kmdi: number;
+    kmei: number;
+    kaui: number;
+    klei: number;
+    klwi: number;
+    ksai: number;
+    kwai: number;
+    kci: number;
+    kji: number;
+    ksei: number;
+}
+
+export interface KobcKcciRecord extends Record<string, unknown>, KobcKcciRow {}
+
+// ─────────────────── NCFI (닝보 컨테이너선운임지수) ──────────────────────────
+
+/** NCFI 스냅샷 — 22개 항로 값 */
+export interface KobcNcfiRow {
+    index_date: string;
+    composite: number;
+    europe: number;
+    west_med: number;
+    east_med: number;
+    west_america: number;
+    east_america: number;
+    mideast: number;
+    west_south_america: number;
+    east_south_america: number;
+    india_pakistan: number;
+    red_sea: number;
+    australia_nz: number;
+    east_japan: number;
+    west_japan: number;
+    thailand_vietnam: number;
+    singapore_malaysia: number;
+    philippines: number;
+    black_sea: number;
+    west_africa: number;
+    south_africa: number;
+    east_africa: number;
+    north_africa: number;
+}
+
+export interface KobcNcfiRecord extends Record<string, unknown>, KobcNcfiRow {}
+
+// ─────────────────── KPLI (항만물류지표) ─────────────────────────────────────
+
+/** KPLI 주간 시계열 레코드 */
+export interface KobcKpliRow {
+    index_date: string;
+    port_efficiency: number;
+    total_voyage_time: number;
+    waiting_time: number;
+    schedule_reliability: number;
+}
+
+export interface KobcKpliRecord extends Record<string, unknown>, KobcKpliRow {}