create-entity-app-server 0.0.3

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

@@ -0,0 +1,142 @@
+# AIS 선박 위치 플러그인
+
+[aisstream.io](https://aisstream.io) WebSocket API를 통해 전세계 선박의 AIS 위치를 주기적으로 수집하고 DB에 저장합니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [환경변수](#환경변수)
+- [스케줄](#스케줄)
+- [API](#api)
+- [데이터 구조](#데이터-구조)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+| 항목        | 내용                                             |
+| ----------- | ------------------------------------------------ |
+| 데이터 소스 | aisstream.io (WebSocket, 무료)                   |
+| 수집 방식   | WebSocket 연결 → N초 수집 → 끊기 → MMSI별 upsert |
+| 저장 단위   | MMSI 기준 최신 위치 1건 (이전 레코드 교체)       |
+| 기본 주기   | 10분마다 (`*/10 * * * *`)                        |
+
+---
+
+## 설정
+
+`config.json` — 플러그인 폴더에 위치:
+
+```json
+{
+    "enabled": true,
+    "apiKey": "${AIS_API_KEY}",
+    "collectSeconds": 60,
+    "batchSize": 20
+}
+```
+
+### 설정 항목
+
+| 항목             | 필수 | 기본값 | 설명                                            |
+| ---------------- | ---- | ------ | ----------------------------------------------- |
+| `enabled`        | ✅   | —      | `false`로 설정하면 플러그인·스케줄 모두 비활성  |
+| `apiKey`         | ✅   | —      | aisstream.io API 키 (`${AIS_API_KEY}` 환경변수) |
+| `collectSeconds` |      | `60`   | WebSocket 수집 시간(초)                         |
+| `batchSize`      |      | `20`   | upsert 배치 크기 (병렬 처리 단위)               |
+| `boundingBoxes`  |      | 전세계 | 지역 필터. `[[lat1,lon1],[lat2,lon2]]` 배열     |
+
+### 지역 필터 예시 (한반도+동아시아)
+
+```json
+{
+    "enabled": true,
+    "apiKey": "${AIS_API_KEY}",
+    "boundingBoxes": [
+        [
+            [25.0, 115.0],
+            [45.0, 135.0]
+        ]
+    ]
+}
+```
+
+---
+
+## 환경변수
+
+```env
+# .env 또는 시스템 환경변수
+AIS_API_KEY=your_aisstream_api_key
+```
+
+### API 키 발급
+
+1. [aisstream.io](https://aisstream.io) 접속
+2. GitHub 계정으로 로그인
+3. **API Keys** 메뉴에서 키 생성 (무료)
+
+---
+
+## 스케줄
+
+스케줄 설정은 플러그인이 아닌 `app/schedules/ais_sync/config.json`에서 관리합니다.
+
+```json
+{
+    "enabled": true,
+    "cron": "*/10 * * * *"
+}
+```
+
+스케줄을 비활성화하려면 `enabled: false`로 설정합니다. 플러그인 자체(`ais/config.json`)는 활성 상태를 유지해도 됩니다.
+
+---
+
+## API
+
+기본 경로: `/api/v1/ais`
+
+| 메서드 | 경로            | 인증        | 설명                           |
+| ------ | --------------- | ----------- | ------------------------------ |
+| `GET`  | `/vessels`      |             | 선박 목록 조회 (필터 지원)     |
+| `GET`  | `/vessels/:seq` |             | 선박 단건 조회                 |
+| `POST` | `/sync`         | 로그인 필요 | 스냅샷 즉시 수집 (수동 동기화) |
+
+파라미터 상세 → [api.md](./api.md)
+
+---
+
+## 데이터 구조
+
+Entity: `ais_vessel` — MMSI 기준 최신 위치 1건 유지
+
+| 컬럼          | 타입         | 설명                               |
+| ------------- | ------------ | ---------------------------------- |
+| `seq`         | integer (PK) | 자동 증가                          |
+| `mmsi`        | varchar(15)  | MMSI (고유 인덱스)                 |
+| `name`        | varchar(30)  | 선박명                             |
+| `callsign`    | varchar(10)  | 호출부호                           |
+| `imo`         | integer      | IMO 번호 (0=미확인)                |
+| `ship_type`   | integer      | 선종 코드 (AIS Type of ship)       |
+| `lat`         | double       | 위도 (WGS84)                       |
+| `lon`         | double       | 경도 (WGS84)                       |
+| `sog`         | double       | 대지속력 (knots)                   |
+| `cog`         | double       | 대지침로 (degrees, 360=N/A)        |
+| `heading`     | integer      | 선수방위 (degrees, 511=N/A)        |
+| `nav_status`  | integer      | 항해 상태 (0=항진, 1=정박, 5=계류) |
+| `destination` | varchar(30)  | 목적지                             |
+| `snapshot_at` | varchar(30)  | AIS 메시지 수신 시각 (UTC ISO)     |
+
+---
+
+## 운영 팁
+
+- aisstream.io 무료 플랜은 **초당 ~300메시지** 처리. 전세계 수집 시 60초면 수만 척 커버.
+- 특정 해역만 필요하다면 `boundingBoxes`로 범위를 좁혀 네트워크·처리 비용 절감.
+- `collectSeconds`를 늘리면 더 많은 선박 수집. 단, 스케줄 간격(`cron`)보다 짧아야 함.
+- 수집 중 WebSocket 오류 발생 시 해당 tick은 skip되고 다음 tick에 재시도.

package/src/app/plugins/ais/docs/api.md

@@ -0,0 +1,138 @@
+# AIS API 레퍼런스
+
+기본 경로: `/api/v1/ais`
+
+---
+
+## 엔드포인트 목록
+
+| 메서드 | 경로                                | 인증        | 설명           |
+| ------ | ----------------------------------- | ----------- | -------------- |
+| `GET`  | [`/vessels`](#get-vessels)          |             | 선박 목록 조회 |
+| `GET`  | [`/vessels/:seq`](#get-vessels-seq) |             | 선박 단건 조회 |
+| `POST` | [`/sync`](#post-sync)               | 로그인 필요 | 수동 동기화    |
+
+---
+
+## GET /vessels
+
+선박 목록을 조회합니다. bbox 필터로 특정 해역의 선박만 조회할 수 있습니다.
+
+### 쿼리 파라미터
+
+| 파라미터    | 타입   | 설명                               |
+| ----------- | ------ | ---------------------------------- |
+| `mmsi`      | string | MMSI 완전 일치 필터                |
+| `name`      | string | 선박명 부분 검색 (LIKE)            |
+| `ship_type` | number | 선종 코드 필터                     |
+| `lat_min`   | number | 위도 하한 (bbox 필터)              |
+| `lat_max`   | number | 위도 상한 (bbox 필터)              |
+| `lon_min`   | number | 경도 하한 (bbox 필터)              |
+| `lon_max`   | number | 경도 상한 (bbox 필터)              |
+| `limit`     | number | 최대 결과 수 (기본 500, 최대 2000) |
+| `offset`    | number | 페이지 오프셋 (기본 0)             |
+
+### bbox 필터 예시 (부산 인근)
+
+```
+GET /api/v1/ais/vessels?lat_min=34.5&lat_max=35.5&lon_min=128.5&lon_max=129.5
+```
+
+### 응답 예시
+
+```json
+{
+    "ok": true,
+    "data": [
+        {
+            "seq": 1,
+            "mmsi": "440123456",
+            "name": "ELIM SPIRIT",
+            "callsign": "DS1234",
+            "imo": 9876543,
+            "ship_type": 70,
+            "lat": 35.12,
+            "lon": 129.05,
+            "sog": 12.3,
+            "cog": 180.0,
+            "heading": 179,
+            "nav_status": 0,
+            "destination": "KRPUS",
+            "snapshot_at": "2026-03-22T06:30:00Z"
+        }
+    ]
+}
+```
+
+---
+
+## GET /vessels/:seq
+
+단건 선박 정보를 조회합니다.
+
+```
+GET /api/v1/ais/vessels/1
+```
+
+### 응답 상태코드
+
+| 상태코드 | 조건              |
+| -------- | ----------------- |
+| 200      | 정상              |
+| 400      | seq가 숫자가 아님 |
+| 404      | 존재하지 않음     |
+
+---
+
+## POST /sync
+
+aisstream.io에서 즉시 스냅샷을 수집합니다. 로그인 필요.
+
+```
+POST /api/v1/ais/sync
+Authorization: Bearer <token>
+```
+
+### 응답 예시
+
+```json
+{
+    "ok": true,
+    "data": {
+        "collected": 15420,
+        "saved": 15380,
+        "errors": 40
+    }
+}
+```
+
+| 필드        | 설명                         |
+| ----------- | ---------------------------- |
+| `collected` | WebSocket에서 수신한 선박 수 |
+| `saved`     | DB에 upsert 성공한 선박 수   |
+| `errors`    | upsert 실패 건수 (로그 확인) |
+
+---
+
+## 부록
+
+### ship_type 코드표 (주요)
+
+| 코드  | 선종   |
+| ----- | ------ |
+| 30    | 어선   |
+| 36    | 요트   |
+| 37    | 레저선 |
+| 60–69 | 여객선 |
+| 70–79 | 화물선 |
+| 80–89 | 유조선 |
+| 90–99 | 기타   |
+
+### nav_status 코드표
+
+| 값  | 상태                             |
+| --- | -------------------------------- |
+| 0   | 항진 중 (Under way using engine) |
+| 1   | 닻 투하 정박 (At anchor)         |
+| 5   | 계류 중 (Moored)                 |
+| 15  | 미정의 (Default)                 |

package/src/app/plugins/ais/entities/ais_vessel.json

@@ -0,0 +1,64 @@
+{
+    "name": "ais_vessel",
+    "description": "AIS 선박 현재 위치 — aisstream.io 주기적 스냅샷 (MMSI 기준 최신 위치 1건)",
+    "fields": {
+        "mmsi": {
+            "type": "varchar(15)",
+            "unique": true,
+            "index": true,
+            "comment": "Maritime Mobile Service Identity (고유 식별자)"
+        },
+        "name": {
+            "type": "varchar(30)",
+            "index": true,
+            "comment": "선박명"
+        },
+        "callsign": {
+            "type": "varchar(10)",
+            "comment": "호출부호"
+        },
+        "imo": {
+            "type": "integer",
+            "index": true,
+            "comment": "IMO 선박 식별번호 (0이면 미확인)"
+        },
+        "ship_type": {
+            "type": "integer",
+            "index": true,
+            "comment": "선종 코드 (AIS Type of ship)"
+        },
+        "lat": {
+            "type": "double",
+            "comment": "위도 (WGS84 소수점)"
+        },
+        "lon": {
+            "type": "double",
+            "comment": "경도 (WGS84 소수점)"
+        },
+        "sog": {
+            "type": "double",
+            "comment": "대지속력 Speed Over Ground (knots)"
+        },
+        "cog": {
+            "type": "double",
+            "comment": "대지침로 Course Over Ground (degrees, 360=N/A)"
+        },
+        "heading": {
+            "type": "integer",
+            "comment": "선수방위 True Heading (degrees, 511=N/A)"
+        },
+        "nav_status": {
+            "type": "integer",
+            "comment": "항해 상태 (0=항진, 1=정박, 5=계류 등)"
+        },
+        "destination": {
+            "type": "varchar(30)",
+            "comment": "목적지 (ShipStaticData 메시지에서 수집)"
+        },
+        "snapshot_at": {
+            "type": "varchar(30)",
+            "index": true,
+            "comment": "AIS 메시지 수신 시각 (UTC ISO)"
+        }
+    }
+}

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

@@ -0,0 +1,88 @@
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, entityServer, BadRequestError, NotFoundError } from "@gateway/api";
+import type { AisService } from "./service.ts";
+
+const ENTITY = "ais_vessel";
+
+// ─── 목록 조회 (bbox 필터 지원) ──────────────────────────────────────────────
+
+interface ListQuery {
+    lat_min?: string;
+    lat_max?: string;
+    lon_min?: string;
+    lon_max?: string;
+    mmsi?: string;
+    name?: string;
+    ship_type?: string;
+    limit?: string;
+    offset?: string;
+}
+
+export async function listVessels(
+    req: FastifyRequest<{ Querystring: ListQuery }>,
+    reply: FastifyReply,
+) {
+    const {
+        lat_min,
+        lat_max,
+        lon_min,
+        lon_max,
+        mmsi,
+        name,
+        ship_type,
+        limit = "500",
+        offset = "0",
+    } = req.query;
+
+    const where: Record<string, unknown> = {};
+
+    if (mmsi) where.mmsi = mmsi;
+    if (name) where.name = { like: `%${name}%` };
+    if (ship_type) where.ship_type = Number(ship_type);
+
+    // bbox 필터
+    if (lat_min != null) where.lat = { gte: Number(lat_min) };
+    if (lat_max != null)
+        where.lat = {
+            ...(where.lat as object | undefined),
+            lte: Number(lat_max),
+        };
+    if (lon_min != null) where.lon = { gte: Number(lon_min) };
+    if (lon_max != null)
+        where.lon = {
+            ...(where.lon as object | undefined),
+            lte: Number(lon_max),
+        };
+
+    const result = await entityServer.find(ENTITY, {
+        where,
+        limit: Math.min(Number(limit), 2000),
+        offset: Number(offset),
+        orderBy: [{ field: "snapshot_at", direction: "desc" }],
+    });
+
+    return reply.send(ok(result));
+}
+
+// ─── 단건 조회 ───────────────────────────────────────────────────────────────
+
+export async function getVessel(
+    req: FastifyRequest<{ Params: { seq: string } }>,
+    reply: FastifyReply,
+) {
+    const seq = Number(req.params.seq);
+    if (!Number.isFinite(seq) || seq <= 0)
+        throw new BadRequestError("Invalid seq");
+
+    const result = await entityServer.get(ENTITY, seq);
+    if (!result) throw new NotFoundError("vessel not found");
+    return reply.send(ok(result));
+}
+
+// ─── 수동 동기화 ─────────────────────────────────────────────────────────────
+
+export async function triggerSync(req: FastifyRequest, reply: FastifyReply) {
+    const service = req.server.aisService as AisService;
+    const result = await service.syncSnapshot();
+    return reply.send(ok(result));
+}

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

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

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

@@ -0,0 +1,13 @@
+import type { FastifyInstance } from "fastify";
+import * as h from "./handlers.ts";
+
+export default async function aisRoutes(app: FastifyInstance) {
+    // GET /api/v1/ais/vessels  — 목록 조회 (bbox/mmsi/name 필터)
+    app.get("/vessels", h.listVessels);
+
+    // GET /api/v1/ais/vessels/:seq  — 단건 조회
+    app.get("/vessels/:seq", h.getVessel);
+
+    // POST /api/v1/ais/sync  — 수동 동기화 (관리자)
+    app.post("/sync", { preHandler: [app.authRequired] }, h.triggerSync);
+}