create-entity-app-server 0.0.3

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

@@ -0,0 +1,316 @@
+# KOBC 해운운임지수 플러그인
+
+[한국해양진흥공사(KOBC)](https://kobc.or.kr) 사이트에서 해운운임지수 4종을 일별·주별로 수집합니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [스케줄](#스케줄)
+- [API](#api)
+- [데이터 구조](#데이터-구조)
+
+---
+
+## 개요
+
+| 지수     | 설명                                                     | 수집 방식        | 단위               |
+| -------- | -------------------------------------------------------- | ---------------- | ------------------ |
+| **KDCI** | 건화물선운임지수 (Cape/Panamax/Supramax/Handy)           | 날짜 범위 쿼리   | integer (pt/$/day) |
+| **KCCI** | 컨테이너선운임지수 — KCCI + 13개 항로 코드               | 일별 최신 스냅샷 | integer (pt/$/FEU) |
+| **NCFI** | 닝보 컨테이너선운임지수 — Composite + 21개 항로          | 일별 최신 스냅샷 | decimal (pt)       |
+| **KPLI** | 항만물류지표 — 항만효율성·총항해시간·대기시간·항만정시성 | 날짜 범위 쿼리   | decimal (day)      |
+
+> **KCCI/NCFI 주의**: 해당 엔드포인트는 날짜 파라미터를 무시하고 항상 최신 데이터를 반환합니다.  
+> 스케줄을 통해 매일 한 번 수집하여 당일 날짜로 저장합니다.
+
+---
+
+## 설정
+
+`config.json` — 플러그인 폴더에 위치:
+
+```json
+{
+    "enabled": true,
+    "entity": "kobc_freight_entry",
+    "syncDays": 5,
+    "initialSyncFrom": "2024-01-01"
+}
+```
+
+### 설정 항목
+
+| 항목              | 필수 | 기본값               | 설명                                           |
+| ----------------- | ---- | -------------------- | ---------------------------------------------- |
+| `enabled`         | ✅   | —                    | `false`로 설정하면 플러그인·스케줄 모두 비활성 |
+| `entity`          |      | `kobc_freight_entry` | KDCI 저장 엔티티명                             |
+| `syncDays`        |      | `5`                  | KDCI 일별 소급 일수 (KPLI는 최소 14일 보장)    |
+| `initialSyncFrom` |      | —                    | KDCI 최초 1회 전체 수집 시작일 (YYYY-MM-DD)    |
+
+---
+
+## 스케줄
+
+스케줄 설정은 `app/schedules/kobc_freight_sync/config.json`에서 관리합니다.
+
+```json
+{
+    "enabled": true,
+    "cron": "0 6 * * *"
+}
+```
+
+매일 06:00에 KDCI · KCCI · NCFI · KPLI를 동시에 수집합니다.  
+KOBC 데이터는 전 영업일 오전에 업데이트됩니다.
+
+---
+
+## API
+
+기본 경로: `/api/v1/kobc_freight`
+
+| 메서드 | 경로                 | 인증        | 설명             |
+| ------ | -------------------- | ----------- | ---------------- |
+| `GET`  | `/entries`           |             | KDCI 목록 조회   |
+| `GET`  | `/entries/:seq`      |             | KDCI 단건 조회   |
+| `POST` | `/sync`              | 로그인 필요 | KDCI 수동 동기화 |
+| `GET`  | `/kcci/entries`      |             | KCCI 목록 조회   |
+| `GET`  | `/kcci/entries/:seq` |             | KCCI 단건 조회   |
+| `POST` | `/kcci/sync`         | 로그인 필요 | KCCI 수동 동기화 |
+| `GET`  | `/ncfi/entries`      |             | NCFI 목록 조회   |
+| `GET`  | `/ncfi/entries/:seq` |             | NCFI 단건 조회   |
+| `POST` | `/ncfi/sync`         | 로그인 필요 | NCFI 수동 동기화 |
+| `GET`  | `/kpli/entries`      |             | KPLI 목록 조회   |
+| `GET`  | `/kpli/entries/:seq` |             | KPLI 단건 조회   |
+| `POST` | `/kpli/sync`         | 로그인 필요 | KPLI 수동 동기화 |
+
+### 공통 쿼리 파라미터 (목록 조회)
+
+| 파라미터     | 타입   | 설명                              |
+| ------------ | ------ | --------------------------------- |
+| `index_date` | string | 특정 날짜 (YYYY-MM-DD)            |
+| `date_from`  | string | 시작 날짜 (YYYY-MM-DD)            |
+| `date_to`    | string | 종료 날짜 (YYYY-MM-DD)            |
+| `limit`      | number | 최대 결과 수 (기본 100, 최대 500) |
+| `offset`     | number | 페이지 오프셋 (기본 0)            |
+
+### POST /sync, /kpli/sync 요청 바디
+
+```json
+{
+    "start_date": "2026-01-01",
+    "end_date": "2026-03-22"
+}
+```
+
+바디 생략 시 최근 N일 자동 수집. KCCI/NCFI sync는 항상 오늘 날짜 스냅샷을 저장합니다.
+
+---
+
+## 데이터 구조
+
+### kobc_freight_entry (KDCI)
+
+| 컬럼         | 타입         | 설명                          |
+| ------------ | ------------ | ----------------------------- |
+| `seq`        | integer (PK) | 자동 증가                     |
+| `index_date` | varchar(10)  | 기준일 (YYYY-MM-DD)           |
+| `kdci`       | integer      | KOBC Dry Bulk Composite Index |
+| `cape`       | integer      | Capesize 운임 ($/day)         |
+| `panamax`    | integer      | Panamax 운임 ($/day)          |
+| `supramax`   | integer      | Supramax 운임 ($/day)         |
+| `handy`      | integer      | Handysize 운임 ($/day)        |
+
+### kobc_kcci_entry (KCCI)
+
+| 컬럼         | 타입         | 설명                          |
+| ------------ | ------------ | ----------------------------- |
+| `seq`        | integer (PK) | 자동 증가                     |
+| `index_date` | varchar(10)  | 수집일 (YYYY-MM-DD)           |
+| `kcci`       | integer      | KCCI Comprehensive Index (pt) |
+| `kuwi`       | integer      | USWC ($/FEU)                  |
+| `kuei`       | integer      | USEC ($/FEU)                  |
+| `knei`       | integer      | Europe ($/FEU)                |
+| `kmdi`       | integer      | Mediterranean ($/FEU)         |
+| `kmei`       | integer      | Middle East ($/FEU)           |
+| `kaui`       | integer      | Australia ($/FEU)             |
+| `klei`       | integer      | Latin America East Coast      |
+| `klwi`       | integer      | Latin America West Coast      |
+| `ksai`       | integer      | South Africa ($/FEU)          |
+| `kwai`       | integer      | West Africa ($/FEU)           |
+| `kci`        | integer      | China Intra-Asia (pt)         |
+| `kji`        | integer      | Japan Intra-Asia (pt)         |
+| `ksei`       | integer      | South East Asia (pt)          |
+
+### kobc_ncfi_entry (NCFI)
+
+| 컬럼                 | 타입          | 설명                      |
+| -------------------- | ------------- | ------------------------- |
+| `seq`                | integer (PK)  | 자동 증가                 |
+| `index_date`         | varchar(10)   | 수집일 (YYYY-MM-DD)       |
+| `composite`          | decimal(10,2) | Composite Index (pt)      |
+| `europe`             | decimal(10,2) | Europe (pt)               |
+| `west_med`           | decimal(10,2) | West Mediterranean (pt)   |
+| `east_med`           | decimal(10,2) | East Mediterranean (pt)   |
+| `west_america`       | decimal(10,2) | West America (pt)         |
+| `east_america`       | decimal(10,2) | East America (pt)         |
+| `mideast`            | decimal(10,2) | Mideast (pt)              |
+| `west_south_america` | decimal(10,2) | West South America (pt)   |
+| `east_south_america` | decimal(10,2) | East South America (pt)   |
+| `india_pakistan`     | decimal(10,2) | India & Pakistan (pt)     |
+| `red_sea`            | decimal(10,2) | Red Sea (pt)              |
+| `australia_nz`       | decimal(10,2) | Australia & New Zealand   |
+| `east_japan`         | decimal(10,2) | East Japan (pt)           |
+| `west_japan`         | decimal(10,2) | West Japan (pt)           |
+| `thailand_vietnam`   | decimal(10,2) | Thailand & Vietnam (pt)   |
+| `singapore_malaysia` | decimal(10,2) | Singapore & Malaysia (pt) |
+| `philippines`        | decimal(10,2) | Philippines (pt)          |
+| `black_sea`          | decimal(10,2) | Black Sea (pt)            |
+| `west_africa`        | decimal(10,2) | West Africa (pt)          |
+| `south_africa`       | decimal(10,2) | South Africa (pt)         |
+| `east_africa`        | decimal(10,2) | East Africa (pt)          |
+| `north_africa`       | decimal(10,2) | North Africa (pt)         |
+
+### kobc_kpli_entry (KPLI)
+
+| 컬럼                   | 타입          | 설명                        |
+| ---------------------- | ------------- | --------------------------- |
+| `seq`                  | integer (PK)  | 자동 증가                   |
+| `index_date`           | varchar(10)   | 기준 주 시작일 (YYYY-MM-DD) |
+| `port_efficiency`      | decimal(10,2) | 항만효율성 — 출발항 (day)   |
+| `total_voyage_time`    | decimal(10,2) | 총항해시간 (day)            |
+| `waiting_time`         | decimal(10,2) | 대기시간 — 도착항 (day)     |
+| `schedule_reliability` | decimal(10,2) | 항만정시성 (day)            |
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [스케줄](#스케줄)
+- [API](#api)
+- [데이터 구조](#데이터-구조)
+
+---
+
+## 개요
+
+| 항목        | 내용                                           |
+| ----------- | ---------------------------------------------- |
+| 데이터 소스 | KOBC 사이트 HTML 스크래핑 (별도 API 키 불필요) |
+| 수집 단위   | 일별 지수 (index_date 기준)                    |
+| 지수 항목   | KDCI, Cape, Panamax, Supramax, Handy           |
+| 기본 주기   | 매일 06:00 (`0 6 * * *`)                       |
+
+---
+
+## 설정
+
+`config.json` — 플러그인 폴더에 위치:
+
+```json
+{
+    "enabled": true,
+    "entity": "kobc_freight_entry",
+    "syncDays": 5,
+    "initialSyncFrom": "2024-01-01"
+}
+```
+
+### 설정 항목
+
+| 항목              | 필수 | 기본값               | 설명                                                       |
+| ----------------- | ---- | -------------------- | ---------------------------------------------------------- |
+| `enabled`         | ✅   | —                    | `false`로 설정하면 플러그인·스케줄 모두 비활성             |
+| `entity`          |      | `kobc_freight_entry` | 저장 엔티티명                                              |
+| `syncDays`        |      | `5`                  | 매일 수집 시 소급 일수 (주말·공휴일 데이터 보정용)         |
+| `initialSyncFrom` |      | —                    | 최초 1회 전체 수집 시작일 (YYYY-MM-DD). 없으면 소급만 수행 |
+
+> `initialSyncFrom` 설정 시 서버 시작 직후 해당 날짜부터 오늘까지 전체 수집을 1회 수행합니다. 완료 후에는 `syncDays` 기반 일별 수집으로 전환됩니다.
+
+---
+
+## 스케줄
+
+스케줄 설정은 `app/schedules/kobc_freight_sync/config.json`에서 관리합니다.
+
+```json
+{
+    "enabled": true,
+    "cron": "0 6 * * *"
+}
+```
+
+KOBC 데이터는 전 영업일 오전에 업데이트됩니다. 06:00 수집을 권장합니다.
+
+---
+
+## API
+
+기본 경로: `/api/v1/kobc_freight`
+
+| 메서드 | 경로            | 인증        | 설명           |
+| ------ | --------------- | ----------- | -------------- |
+| `GET`  | `/entries`      |             | 지수 목록 조회 |
+| `GET`  | `/entries/:seq` |             | 지수 단건 조회 |
+| `POST` | `/sync`         | 로그인 필요 | 수동 동기화    |
+
+### GET /entries 쿼리 파라미터
+
+| 파라미터     | 타입   | 설명                              |
+| ------------ | ------ | --------------------------------- |
+| `index_date` | string | 특정 날짜 (YYYY-MM-DD)            |
+| `date_from`  | string | 시작 날짜 (YYYY-MM-DD)            |
+| `date_to`    | string | 종료 날짜 (YYYY-MM-DD)            |
+| `limit`      | number | 최대 결과 수 (기본 100, 최대 500) |
+| `offset`     | number | 페이지 오프셋 (기본 0)            |
+
+### POST /sync 요청 바디
+
+```json
+{
+    "start_date": "2026-01-01",
+    "end_date": "2026-03-22"
+}
+```
+
+바디 생략 시 `syncDays` 기준 최근 N일을 수집합니다.
+
+### 응답 예시 (GET /entries)
+
+```json
+{
+    "ok": true,
+    "data": [
+        {
+            "seq": 1,
+            "index_date": "2026-03-21",
+            "kdci": 1234,
+            "cape": 5678,
+            "panamax": 9012,
+            "supramax": 3456,
+            "handy": 7890
+        }
+    ]
+}
+```
+
+---
+
+## 데이터 구조
+
+Entity: `kobc_freight_entry`
+
+| 컬럼         | 타입         | 설명                  |
+| ------------ | ------------ | --------------------- |
+| `seq`        | integer (PK) | 자동 증가             |
+| `index_date` | varchar      | 기준일 (YYYY-MM-DD)   |
+| `kdci`       | integer      | 종합 건화물선운임지수 |
+| `cape`       | integer      | 케이프사이즈 지수     |
+| `panamax`    | integer      | 파나막스 지수         |
+| `supramax`   | integer      | 수프라막스 지수       |
+| `handy`      | integer      | 핸디사이즈 지수       |

package/src/app/plugins/kobc_freight/entities/kobc_freight_entry.json

@@ -0,0 +1,31 @@
+{
+    "name": "kobc_freight_entry",
+    "description": "KOBC 건화물선운임지수 (KDCI) — 한국해양진흥공사 일별 건화물선 운임지수",
+    "fields": {
+        "index_date": {
+            "type": "varchar(10)",
+            "index": true,
+            "comment": "지수 날짜 (YYYY-MM-DD)"
+        },
+        "kdci": {
+            "type": "integer",
+            "comment": "KOBC Dry Bulk Composite Index (pt)"
+        },
+        "cape": {
+            "type": "integer",
+            "comment": "Capesize 운임 ($/day)"
+        },
+        "panamax": {
+            "type": "integer",
+            "comment": "Panamax 운임 ($/day)"
+        },
+        "supramax": {
+            "type": "integer",
+            "comment": "Supramax 운임 ($/day)"
+        },
+        "handy": {
+            "type": "integer",
+            "comment": "Handysize 운임 ($/day)"
+        }
+    }
+}

package/src/app/plugins/kobc_freight/entities/kobc_kcci_entry.json

@@ -0,0 +1,67 @@
+{
+    "name": "kobc_kcci_entry",
+    "description": "KOBC 컨테이너선운임지수 (KCCI) — 한국해양진흥공사 일별 스냅샷",
+    "fields": {
+        "index_date": {
+            "type": "varchar(10)",
+            "index": true,
+            "comment": "지수 날짜 (YYYY-MM-DD)"
+        },
+        "kcci": {
+            "type": "integer",
+            "comment": "KCCI Comprehensive Index (pt)"
+        },
+        "kuwi": {
+            "type": "integer",
+            "comment": "KUWI — USWC ($/FEU)"
+        },
+        "kuei": {
+            "type": "integer",
+            "comment": "KUEI — USEC ($/FEU)"
+        },
+        "knei": {
+            "type": "integer",
+            "comment": "KNEI — Europe ($/FEU)"
+        },
+        "kmdi": {
+            "type": "integer",
+            "comment": "KMDI — Mediterranean ($/FEU)"
+        },
+        "kmei": {
+            "type": "integer",
+            "comment": "KMEI — Middle East ($/FEU)"
+        },
+        "kaui": {
+            "type": "integer",
+            "comment": "KAUI — Australia ($/FEU)"
+        },
+        "klei": {
+            "type": "integer",
+            "comment": "KLEI — Latin America East Coast ($/FEU)"
+        },
+        "klwi": {
+            "type": "integer",
+            "comment": "KLWI — Latin America West Coast ($/FEU)"
+        },
+        "ksai": {
+            "type": "integer",
+            "comment": "KSAI — South Africa ($/FEU)"
+        },
+        "kwai": {
+            "type": "integer",
+            "comment": "KWAI — West Africa ($/FEU)"
+        },
+        "kci": {
+            "type": "integer",
+            "comment": "KCI — China (pt)"
+        },
+        "kji": {
+            "type": "integer",
+            "comment": "KJI — Japan (pt)"
+        },
+        "ksei": {
+            "type": "integer",
+            "comment": "KSEI — South East Asia (pt)"
+        }
+    }
+}

package/src/app/plugins/kobc_freight/entities/kobc_kpli_entry.json

@@ -0,0 +1,27 @@
+{
+    "name": "kobc_kpli_entry",
+    "description": "KOBC 항만물류지표 (KPLI) — 한국해양진흥공사 주간 항만·물류 지표 (단위: day)",
+    "fields": {
+        "index_date": {
+            "type": "varchar(10)",
+            "index": true,
+            "comment": "기준 주 시작일 (YYYY-MM-DD)"
+        },
+        "port_efficiency": {
+            "type": "decimal(10,2)",
+            "comment": "항만효율성 — 출발항 (day)"
+        },
+        "total_voyage_time": {
+            "type": "decimal(10,2)",
+            "comment": "총항해시간 (day)"
+        },
+        "waiting_time": {
+            "type": "decimal(10,2)",
+            "comment": "대기시간 — 도착항 (day)"
+        },
+        "schedule_reliability": {
+            "type": "decimal(10,2)",
+            "comment": "항만정시성 (day)"
+        }
+    }
+}

package/src/app/plugins/kobc_freight/entities/kobc_ncfi_entry.json

@@ -0,0 +1,99 @@
+{
+    "name": "kobc_ncfi_entry",
+    "description": "KOBC 닝보 컨테이너선운임지수 (NCFI) — 한국해양진흥공사 일별 스냅샷",
+    "fields": {
+        "index_date": {
+            "type": "varchar(10)",
+            "index": true,
+            "comment": "지수 날짜 (YYYY-MM-DD)"
+        },
+        "composite": {
+            "type": "decimal(10,2)",
+            "comment": "Composite Index (pt)"
+        },
+        "europe": {
+            "type": "decimal(10,2)",
+            "comment": "Europe (pt)"
+        },
+        "west_med": {
+            "type": "decimal(10,2)",
+            "comment": "West Mediterranean (pt)"
+        },
+        "east_med": {
+            "type": "decimal(10,2)",
+            "comment": "East Mediterranean (pt)"
+        },
+        "west_america": {
+            "type": "decimal(10,2)",
+            "comment": "West America (pt)"
+        },
+        "east_america": {
+            "type": "decimal(10,2)",
+            "comment": "East America (pt)"
+        },
+        "mideast": {
+            "type": "decimal(10,2)",
+            "comment": "Mideast (pt)"
+        },
+        "west_south_america": {
+            "type": "decimal(10,2)",
+            "comment": "West South America (pt)"
+        },
+        "east_south_america": {
+            "type": "decimal(10,2)",
+            "comment": "East South America (pt)"
+        },
+        "india_pakistan": {
+            "type": "decimal(10,2)",
+            "comment": "India & Pakistan (pt)"
+        },
+        "red_sea": {
+            "type": "decimal(10,2)",
+            "comment": "Red Sea (pt)"
+        },
+        "australia_nz": {
+            "type": "decimal(10,2)",
+            "comment": "Australia & New Zealand (pt)"
+        },
+        "east_japan": {
+            "type": "decimal(10,2)",
+            "comment": "East Japan (pt)"
+        },
+        "west_japan": {
+            "type": "decimal(10,2)",
+            "comment": "West Japan (pt)"
+        },
+        "thailand_vietnam": {
+            "type": "decimal(10,2)",
+            "comment": "Thailand & Vietnam (pt)"
+        },
+        "singapore_malaysia": {
+            "type": "decimal(10,2)",
+            "comment": "Singapore & Malaysia (pt)"
+        },
+        "philippines": {
+            "type": "decimal(10,2)",
+            "comment": "Philippines (pt)"
+        },
+        "black_sea": {
+            "type": "decimal(10,2)",
+            "comment": "Black Sea (pt)"
+        },
+        "west_africa": {
+            "type": "decimal(10,2)",
+            "comment": "West Africa (pt)"
+        },
+        "south_africa": {
+            "type": "decimal(10,2)",
+            "comment": "South Africa (pt)"
+        },
+        "east_africa": {
+            "type": "decimal(10,2)",
+            "comment": "East Africa (pt)"
+        },
+        "north_africa": {
+            "type": "decimal(10,2)",
+            "comment": "North Africa (pt)"
+        }
+    }
+}