create-entity-app-server 0.0.3 → 0.0.4

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

@@ -1,142 +0,0 @@
-# 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

@@ -1,138 +0,0 @@
-# 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

@@ -1,64 +0,0 @@
-{
-    "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

@@ -1,88 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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);
-}