# ShipInfo Route Intelligence Module

## SPECIFICATION: Historical Route Graph & Port-to-Port Path Designer

Version: 1.0\
Target system: ShipInfo / TOPOS\
Environment: Debian + MariaDB + AIS historical database\
Agent executor: Codex 5.3 (semi-autonomous mode)

------------------------------------------------------------------------

# 1. Objective

Создать модуль проектирования маршрутов между портами на основе реальных
исторических данных AIS.

Система должна:

1.  Принимать:
    -   стартовый порт
    -   конечный порт
    -   (опционально) обязательный промежуточный порт
2.  Строить:
    -   реальные исторические маршруты (polyline)
    -   среднее время перехода
    -   альтернативные варианты
3.  Использовать:
    -   исторические треки судов
    -   кластеризацию маршрутов
    -   граф портов (ребра с весами)
    -   выявленные bottleneck-хабы

------------------------------------------------------------------------

# 2. High-Level Architecture

Module name: route_intelligence

Компоненты:

1.  Port Transition Extractor
2.  Route Cluster Builder
3.  Bottleneck Hub Detector
4.  Port Graph Builder
5.  Route Query Engine
6.  Polyline Generator
7.  Travel Time Estimator
8.  API + Map Layer

------------------------------------------------------------------------

# 3. Data Sources

Input: - Historical AIS positions (lat, lon, timestamp, speed) - Port
calls table - Vessel type (tanker, bulk, cargo, LNG etc.) - Draft (если
есть) - Port polygons

------------------------------------------------------------------------

# 4. Step 1 --- Extract Port-to-Port Transitions

## Definition

Переход = движение судна: - от выхода из порта A - до входа в порт B -
без захода в другие порты между ними

Таблица:

## port_transitions

id imo port_from_id port_to_id departure_time arrival_time
duration_hours vessel_type

------------------------------------------------------------------------

# 5. Step 2 --- Build Route Polylines

Для каждого transition:

1.  Взять AIS точки:
    -   timestamp ∈ \[departure_time, arrival_time\]
2.  Очистить:
    -   убрать заходы в сторонние порты
    -   удалить стоянки
3.  Сгладить:
    -   downsample
    -   Douglas-Peucker algorithm

## route_segments

transition_id polyline (encoded) distance_nm avg_speed

------------------------------------------------------------------------

# 6. Step 3 --- Build Port Graph

## port_graph_edges

port_from_id port_to_id transition_count tanker_count cargo_count
avg_duration_hours avg_distance_nm score

Score формула:

score = log(transition_count) \* vessel_weight

Оставить TOP \~5000 ребер по score.

------------------------------------------------------------------------

# 7. Step 4 --- Identify Bottleneck Hubs

Метод:

1.  Разбить мир на grid (0.2°)
2.  Посчитать плотность AIS точек
3.  Найти зоны с высокой betweenness centrality

## route_hubs

hub_id lat lon centrality_score flow_count

------------------------------------------------------------------------

# 8. Step 5 --- Route Query Engine

Scenario A: Direct Route\
Scenario B: Route With Mandatory Port

Использовать Dijkstra (вес = avg_duration или 1/score)

------------------------------------------------------------------------

# 9. Travel Time Estimation

Tanker_avg = 12--14 knots\
Cargo_avg = 14--17 knots

Time_estimate = distance / avg_speed

------------------------------------------------------------------------

# 10. API Endpoints

GET /api/routes/direct\
GET /api/routes/with-via

------------------------------------------------------------------------

# 11. Map Layer

-   Leaflet / MapLibre
-   Polyline overlay
-   Tooltip:
    -   Distance
    -   ETA tanker
    -   ETA cargo
    -   Frequency score

------------------------------------------------------------------------

# 12. Strategic Enhancements

-   Seasonal Route Variation
-   Canal Risk Flag
-   Route Confidence Score
-   Anomaly-Aware Routing

------------------------------------------------------------------------

# 13. Performance Constraints

-   Precompute graph offline
-   Route queries \< 500 ms
-   Индексы по port_from_id, port_to_id, score DESC

------------------------------------------------------------------------

# 14. Deliverables for Codex

1.  Create DB schema
2.  Write SQL transition extractor
3.  Build graph builder script
4.  Implement Dijkstra in PHP
5.  Create API endpoints
6.  Generate test route
7.  Output JSON sample

------------------------------------------------------------------------

# 15. Success Criteria

✔ 5000 strongest edges computed\
✔ 95% основных торговых маршрутов покрыты\
✔ Маршрут строится \< 1 секунды\
✔ Нет ложных ответвлений

------------------------------------------------------------------------

# 16. Long-Term Vision

-   База для freight index
-   Основа congestion analytics
-   Infrastructure layer for AI agents