Guide d'utilisation

À qui ça sert ?

• Traders matières premières (pétrole, LNG, chimie) — ETA précise et indices de congestion alimentent les modèles de prix. Cible primaire de la plateforme.
• Freight forwarders — anticipation des dépassements de séjour (demurrage), choix de routing.
• Assureurs maritimes— détection d'anomalies (loitering, dwell anormal), risk pricing.
• Data scientists / quants — feed historique pour backtesting de stratégies macro (activité portuaire = proxy économique).

Lire le dashboard en 30 secondes

1. Sélecteur de porten haut à droite — change le port observé. Le nom natif s'affiche entre parenthèses si la langue active diffère (ex : Anvers (Antwerpen), Hamburg, الفجيرة).
2. Sélecteur de langue à côté — 6 langues métier : FR, EN, NL, DE, ES, AR (avec RTL automatique).
3. Toggle Tous / Tankers — filtre instantanément la carte et les compteurs aux 5 sous-classes tanker (crude, product, chemical, LNG, LPG).
4. KPI ligne — total navires, stationnaires (proxy congestion), en route, à quai, entrants/h, voyages actifs trackés.
5. Carte — couleur = catégorie AIS, taille = état. Les rectangles pointillés sont les zones nommées (anchorage, berth, channel).
6. Voyages actifs— table triée par ETA prédite. La colonne "ETA broadcast" est l'heure que l'équipage a saisie ; comparer aux écarts du modèle.
7. ETA precision— RMSE de notre modèle vs RMSE de l'ETA broadcast. C'est l'indicateur principal de qualité.
8. Anomalies — navires au mouillage anormalement long pour leur classe. Critique à surveiller pour congestion ou bizarreries opérationnelles.
9. Flux 6h — entrants / sortants / stationnaires sur les 6 dernières heures. Tendance courte.

Page ETA precision

Accessible via le bouton ETA precision ou /precision. Vue publique destinée à démontrer aux prospects la qualité du modèle. Trois indicateurs clés : RMSE modèle, RMSE broadcast, écart en %. Liste des 50 derniers voyages clos avec erreur en heures (vert < 1h, ambre < 3h, rouge au-delà). Méthodologie en bas de page. Filtre fenêtre 7/30/90 jours.

Intégration API

API publique sous /api/v1, authentifiée par bearer token. Spécification OpenAPI à /api/v1/openapi.json.

# Configurer
echo "PORT_API_TOKENS=your-secret-token" >> .env.local

# Liste des ports
curl -H "Authorization: Bearer your-secret-token" \
  http://localhost:3000/api/v1/ports

# Snapshot Rotterdam
curl -H "Authorization: Bearer your-secret-token" \
  http://localhost:3000/api/v1/ports/rotterdam/snapshot

# Voyages tankers actifs
curl -H "Authorization: Bearer your-secret-token" \
  "http://localhost:3000/api/v1/ports/rotterdam/voyages/active?tankersOnly=1"

Endpoints disponibles : /ports, /ports/{id}/snapshot, /ports/{id}/vessels, /ports/{id}/voyages/active, /ports/{id}/voyages/closed, /ports/{id}/anomalies, /webhooks.

Webhooks (alertes)

Souscris à un événement pour recevoir un POST signé HMAC-SHA256 quand un seuil est franchi.

# Souscrire à congestion > 30 navires stationnaires à Rotterdam
curl -X POST -H "Authorization: Bearer your-secret-token" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://your-app.example/hooks/port-flow",
    "port": "rotterdam",
    "event": "congestion.threshold",
    "threshold": 30
  }' \
  http://localhost:3000/api/v1/webhooks

# Réponse — secret à conserver pour vérifier la signature
{ "id": "sub_…", "secret": "…", "url": "…", … }

Headers fournis sur chaque livraison : X-Port-Flow-Event et X-Port-Flow-Signature: t=<ts>,v1=<hex> (HMAC-SHA256 du payload préfixé par le timestamp). Vérification côté receveur : hmac_sha256(secret, "{ts}.{body}").

Événements supportés : congestion.threshold / congestion.cleared, anomaly.detected, voyage.arrived.

Limites connues

• Couverture AIS faible Méditerranée et Golfe Persique avec aisstream.io (réseau communautaire). Algeciras, Fujairah, Ras Laffan affichent souvent peu ou aucun navire en v1. Solution : passer à un fournisseur commercial (Spire, Orbcomm) — sur la roadmap.
• Classification cargaison à ~85 % (tankers) / ~95 % (containers). Faux positifs sur les navires non nommés.
• Au démarrage du worker, une grace period de 60 s évite de compter les navires déjà présents comme "entrants". Les KPIs entrants/h se calibrent ensuite naturellement.
• Modèle ETA v1 simple (distance/SOG + correction médiane). Bat l'ETA broadcast quand les voyages sont > 6h ; moins d'avance sur les voyages courts.
• Pas de filtrage sanctions intégré. Le client doit appliquer ses propres listes (OFAC, OFSI, EU).

Checklist de déploiement

1. Créer une clé aisstream.io.
2. cp .env.example .env.local, renseigner AISSTREAM_API_KEY et PORT_API_TOKENS.
3. npm install && npm run dev.
4. Vérifier le bandeau AIS Live en haut à droite (vert = flux entrant).
5. Attendre 60 s + quelques minutes pour voir les voyages s'ouvrir (selon le trafic).
6. La page /precision affichera des chiffres après les premiers voyages clos (ETA prédite + arrivée constatée).