Track ports of interest, log infractions if transiting

Author: tristanbudd

app/Http/Controllers/Api/VesselController.php

@@ -593,9 +593,25 @@ public function activities(string $mmsi): JsonResponse
             ->orderBy('started_at', 'desc')
             ->get();
 
+        $data = $activities->map(function ($activity) {
+            $details = $activity->details;
+            $source = $details['source'] ?? 'FleetLeaks';
+
+            return [
+                'id' => $activity->id,
+                'type' => $activity->type,
+                'severity' => $activity->severity,
+                'description' => $activity->description,
+                'details' => $details,
+                'source' => $source,
+                'started_at' => $activity->started_at,
+                'ended_at' => $activity->ended_at,
+            ];
+        });
+
         return response()->json([
             'mmsi' => (int) $mmsi,
-            'data' => $activities,
+            'data' => $data,
         ]);
     }
 
@@ -711,6 +727,7 @@ public function infractionsList(Request $request): JsonResponse
                 'infractions_count' => (int) $vessel->activities_count,
                 'highest_severity' => $highestSeverity,
                 'risk_score' => min(100, (int) $vessel->raw_score),
+                'source' => 'FleetLeaks',
             ];
         });
 
@@ -724,4 +741,34 @@ public function infractionsList(Request $request): JsonResponse
             ],
         ]);
     }
+
+    /**
+     * List Ports of Interest
+     *
+     * Retrieve the list of high-risk maritime hubs and ports being monitored by SIST.
+     *
+     * @response 200 scenario="Success" {
+     * "data": [
+     * {
+     * "name": "CPC Marine Terminal",
+     * "lat": 44.6300,
+     * "lng": 37.6400,
+     * "severity": "high",
+     * "type": "Major export hub",
+     * "source": "FleetLeaks"
+     * }
+     * ]
+     * }
+     */
+    public function portsOfInterest(): JsonResponse
+    {
+        $path = resource_path('data/ports_of_interest.json');
+        if (! file_exists($path)) {
+            return response()->json(['data' => []]);
+        }
+
+        $zones = json_decode(file_get_contents($path), true);
+
+        return response()->json(['data' => $zones]);
+    }
 }

app/Services/VesselAnalysisService.php

@@ -13,6 +13,9 @@
 
 class VesselAnalysisService
 {
+    /** @var array|null */
+    private $monitoredZones = null;
+
     /**
      * Perform behavioral analysis on vessels with pending updates.
      *
@@ -50,8 +53,9 @@ public function rebuildAll(): void
             Vessel::query()->update(['last_analyzed_at' => null]);
         });
 
-        Vessel::chunk(100, function ($vessels) {
+        Vessel::query()->chunk(100, function ($vessels) {
             foreach ($vessels as $vessel) {
+                /** @var Vessel $vessel */
                 $this->processVesselMetrics($vessel);
             }
         });
@@ -69,6 +73,7 @@ public function processVesselMetrics(Vessel $vessel): void
             $this->detectTransmissionGaps($vessel);
             $this->detectLoiteringPatterns($vessel);
             $this->detectKinematicAnomalies($vessel);
+            $this->detectPortInteractions($vessel);
 
             $vessel->update(['last_analyzed_at' => now()]);
             DB::commit();
@@ -201,6 +206,60 @@ private function detectKinematicAnomalies(Vessel $vessel): void
         }
     }
 
+    /**
+     * Detects interactions with monitored ports of interest.
+     */
+    private function detectPortInteractions(Vessel $vessel): void
+    {
+        if ($this->monitoredZones === null) {
+            $path = resource_path('data/ports_of_interest.json');
+            if (file_exists($path)) {
+                $this->monitoredZones = json_decode(file_get_contents($path), true);
+            } else {
+                $this->monitoredZones = [];
+            }
+        }
+
+        if (empty($this->monitoredZones)) {
+            return;
+        }
+
+        $positions = $vessel->positions()
+            ->where('recorded_at', '>=', now()->subDays(30))
+            ->orderBy('recorded_at', 'desc')
+            ->get();
+
+        if ($positions->isEmpty()) {
+            return;
+        }
+
+        foreach ($this->monitoredZones as $zone) {
+            $matchingPositions = $positions->filter(function ($pos) use ($zone) {
+                // Radius of 2km for high accuracy (visit detection)
+                return $this->calculateDistance($pos->lat, $pos->lng, $zone['lat'], $zone['lng']) <= 2.0;
+            });
+
+            // If we have 3 or more points within the radius, it's a high-confidence visit/interaction
+            if ($matchingPositions->count() >= 3) {
+                $start = $matchingPositions->min('recorded_at');
+                $end = $matchingPositions->max('recorded_at');
+                $durationMinutes = $start->diffInMinutes($end);
+
+                // Only flag if they stayed for at least 30 minutes to filter out slow bypasses
+                if ($durationMinutes >= 30) {
+                    $this->persistActivity($vessel, 'port_of_interest', $zone['severity'], [
+                        'port_name' => $zone['name'],
+                        'port_type' => $zone['type'],
+                        'source' => $zone['source'] ?? 'Unknown',
+                        'visit_duration_minutes' => $durationMinutes,
+                        'point_count' => $matchingPositions->count(),
+                        'coordinates' => ['lat' => $zone['lat'], 'lng' => $zone['lng']],
+                    ], $start, $end);
+                }
+            }
+        }
+    }
+
     /**
      * Logs or updates a detected behavioral event.
      */
@@ -251,6 +310,7 @@ private function resolveDescription(string $type, array $details): string
             'ais_gap' => 'AIS transmission interruption detected ('.MaritimeFormatter::formatDuration($details['duration_minutes'] ?? 0).').',
             'loitering' => 'Stationary residency pattern in open-sea transit area.',
             'speed_anomaly' => 'Kinematic violation: speed exceeds physical capability ('.round($details['reported_speed'] ?? 0, 1).' kn).',
+            'port_of_interest' => 'Vessel interaction detected at high-risk maritime hub: '.($details['port_name'] ?? 'Unknown Port').'.',
             default => 'Anomalous behavioral event detected.',
         };
     }