부산항 AIS AI 플랫폼 (PORTIQ)

AIS(자동 선박 식별 시스템) 데이터를 기반으로 부산항 선박 입항시간(ETA)과 항만 혼잡도를 예측하고, 지도로 시각화하며, LLM 어드바이저가 운영 권고(JIT 감속 등)를 제공하는 웹 플랫폼입니다.

🔗 실제 데모 바로가기

🏆 제11회 부울경 AI 융합 해커톤 — 최우수상

프로젝트 개요

항만은 선박 도착 시점을 정확히 알기 어려워 불필요한 급항해·정박 대기가 발생하고, 이는 곧 연료 낭비와 혼잡으로 이어집니다. 이 프로젝트는 AIS 위치·속력 데이터와 Port-MIS 혼잡도 예보를 결합해, 선박이 미리 속도를 늦춰 정시에 도착하도록(JIT, Just-In-Time) 돕는 의사결정 도구입니다.

• 결정론적 계산(ETA·혼잡도)과 LLM 기반 운영 권고를 분리해, 예측은 재현 가능하게, 판단은 LLM이 보조하게 설계했습니다.
• 항만 설정(좌표·선석·구역·임계값)을 데이터 파일 한 곳에만 몰아넣어, 다른 항만으로도 이식 가능한 아키텍처를 목표로 했습니다.

주요 기능

기능	설명
ETA 예측	선박의 현재 위치·속력(SOG)으로 haversine 거리 기반 결정론적 도착 시간 계산
혼잡도 예측	시간대별 입항 예정 선박 수를 집계한 통계 기반 혼잡도(0~1) 곡선
지도 시각화	react-leaflet 기반 부산항 인근 선박 위치·상태 실시간 표시
LLM 어드바이저	현재 선박·혼잡도 상황을 바탕으로 한 운영 권고(JSON) 생성
JIT 감속 권고	ETA가 혼잡 예보 시간대에 포함될 때 감속 권고를 계산, forecast가 오래된 경우 fallback 처리
시나리오 시뮬레이션	가상 선박을 구성해 실제 데이터와 분리된 입항 시나리오 테스트

설계에서 고민한 점

• 결정론 vs LLM의 역할 분리: ETA·혼잡도처럼 재현성이 중요한 계산은 순수 함수(TypeScript, ML 없음)로 두고, 운영 권고처럼 판단이 필요한 부분만 LLM에 맡겼습니다. 또한 LLM 응답은 그대로 신뢰하지 않고 안전 파싱(backend/advisor/parse.ts)을 항상 거치도록 했습니다.
• 데이터-코드 분리: 항만 고유값(좌표·선석·임계값)을 backend/ports/seed-port.ts 한 파일에 집중시켜, 다른 항만에 적용할 때 이 파일만 교체하면 되도록 설계했습니다. CODE Medi 프로젝트에서도 동일한 원칙(증례·채점표를 데이터 파일로 분리)을 적용한 적이 있어, 재사용 가능한 개인 아키텍처 패턴으로 삼고 있습니다.
• Freshness 처리: Port-MIS 혼잡도 예보가 선박 ETA 범위를 포함하지 못할 때(fallback 상황)를 숨기지 않고 API 응답과 대시보드에 그대로 노출해, 예측 신뢰도를 사용자가 판단할 수 있게 했습니다.

아키텍처

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#f5f5f5',
  'primaryTextColor': '#1a1a1a',
  'primaryBorderColor': '#8a8a8a',
  'lineColor': '#8a8a8a',
  'secondaryColor': '#e5e5e5',
  'tertiaryColor': '#ffffff',
  'clusterBkg': '#fafafa',
  'clusterBorder': '#bdbdbd',
  'fontFamily': 'ui-sans-serif, system-ui'
}}}%%
flowchart TB
    subgraph Client["🖥️ Frontend"]
        UI["frontend/components<br/>지도 · 차트 · 어드바이저 패널"]
        Pages["app/*<br/>dashboard · vessel · simulation · congestion"]
    end

    subgraph API["🌐 API Layer"]
        Route["app/api/*/route.ts<br/>HTTP 경계"]
    end

    subgraph Backend["⚙️ Backend (순수 로직)"]
        Prediction["backend/prediction<br/>ETA · 혼잡도 (결정론적 계산)"]
        Advisor["backend/advisor<br/>LLM 프롬프트 생성 · 응답 안전 파싱"]
        AIS["backend/ais<br/>AIS 데이터 소스"]
        Ports["backend/ports/seed-port.ts<br/>항만 좌표 · 선석 · 임계값 (★단일 데이터 소스)"]
    end

    subgraph External["☁️ External"]
        Supabase[("Supabase")]
        OpenAI["OpenAI API<br/>(Vercel AI SDK)"]
    end

    Pages --> UI
    UI --> Route
    Route --> Prediction
    Route --> Advisor
    Prediction --> AIS
    Prediction --> Ports
    Advisor --> Ports
    Advisor --> OpenAI
    Route --> Supabase

    classDef default fill:#f5f5f5,stroke:#8a8a8a,stroke-width:1px,color:#1a1a1a;
    classDef ext fill:#e5e5e5,stroke:#8a8a8a,stroke-width:1px,color:#1a1a1a,stroke-dasharray: 3 3;
    class Supabase,OpenAI ext;

• HTTP 경계(app/api)와 순수 로직(backend)을 분리해, 예측·권고 로직을 API 구현과 독립적으로 테스트할 수 있게 했습니다.
• seed-port.ts가 유일한 항만 데이터 소스로, 예측·어드바이저 양쪽이 같은 데이터를 참조합니다 — 다른 항만 적용 시 이 파일만 교체하면 됩니다.
• LLM(OpenAI)은 어드바이저 영역에만 관여하며, 그 결과는 그대로 신뢰하지 않고 안전 파싱을 거쳐 클라이언트로 전달됩니다.

기술 스택

• Frontend: Next.js (App Router) + TypeScript + TailwindCSS
• 지도/차트: react-leaflet(지도), recharts(차트)
• AI: Vercel AI SDK(generateText) + OpenAI(gpt-4o-mini 기본)
• DB: Supabase
• 예측 로직: Python/ML 의존성 없이 TypeScript로 직접 구현 (결정론적 계산)

실행 방법

npm install
cp .env.example .env.local   # OPENAI_API_KEY 채우기 (없어도 지도/차트/목록은 동작)
npm run dev

http://localhost:3000 → 랜딩, /dashboard → 지도+차트+목록+어드바이저.

키 없이도 api/ships, api/congestion은 목업 데이터로 끝까지 동작합니다. api/advisor는 OPENAI_API_KEY가 있어야 실제 LLM 응답을 받습니다.

페이지 / API 구조

• /dashboard: 실제 AIS/Supabase 선박, Port-MIS 혼잡도, JIT 감속 권고, AI 어드바이저를 표시합니다.
• /vessel: 선박 목록과 상세 상태를 조회합니다.
• /simulation: 브라우저 localStorage에 저장한 가상 선박으로 입항 시나리오를 구성하고 JIT 계산을 실행합니다. 실제 AIS/Port-MIS 선박과 섞지 않습니다.
• /congestion: 부산항 권역별 혼잡도를 표시합니다.
• /api/energy-decisions GET: 실제 선박과 Port-MIS 기반 혼잡도로 JIT 감속 권고를 계산합니다.
• /api/energy-decisions POST: /simulation의 가상 선박 입력을 기준으로 JIT 감속 권고를 계산합니다.

폴더 구조

app/                        페이지(App Router)와 API 라우트
frontend/components/        UI 컴포넌트 (지도, 차트, 목록, 어드바이저 패널)
backend/
 ├─ ports/seed-port.ts      부산항 좌표·선석·구역·임계값 (★ 다른 항만 적용 시 이 파일만 교체)
 ├─ ais/                    AIS 목업 데이터 생성
 ├─ prediction/             ETA·혼잡도 계산 (순수 함수)
 └─ advisor/                LLM 프롬프트·응답 파싱

자세한 설계 원칙은 CLAUDE.md 참고.