Refactor and enhance documentation across multiple classes (Analysis through DashboardStatistics)

main/src/main/java/sd/dashboard/DashboardClientHandler.java

@@ -9,19 +9,42 @@ import sd.protocol.MessageProtocol;
 import sd.protocol.SocketConnection;
 
 /**
- * Processes statistics messages from a single client connection.
- * Runs in a separate thread per client.
+ * Worker responsável pelo processamento dedicado de uma conexão de cliente TCP no Dashboard.
+ * <p>
+ * Esta classe implementa o padrão <i>Thread-per-Client</i>. Cada instância executa numa
+ * thread separada, garantindo que a latência de rede ou o processamento de mensagens
+ * de um nó (Interseção/Coordenador) não bloqueie a receção de telemetria dos outros.
+ * <p>
+ * As suas principais funções são:
+ * <ol>
+ * <li>Manter a conexão persistente com o nó remoto.</li>
+ * <li>Desserializar mensagens de protocolo recebidas.</li>
+ * <li>Normalizar payloads JSON (resolvendo ambiguidades de tipagem do Gson).</li>
+ * <li>Atualizar o objeto partilhado {@link DashboardStatistics} de forma thread-safe.</li>
+ * </ol>
  */
 public class DashboardClientHandler implements Runnable {
     
     private final Socket clientSocket;
     private final DashboardStatistics statistics;
     
+    /**
+     * Inicializa o handler com o socket ativo e a referência para o agregador de estatísticas.
+     *
+     * @param clientSocket O socket TCP conectado ao nó remoto.
+     * @param statistics O objeto singleton partilhado onde as métricas serão agregadas.
+     */
     public DashboardClientHandler(Socket clientSocket, DashboardStatistics statistics) {
         this.clientSocket = clientSocket;
         this.statistics = statistics;
     }
     
+    /**
+     * Ciclo de vida da conexão.
+     * <p>
+     * Estabelece o wrapper {@link SocketConnection}, entra num loop de leitura bloqueante
+     * e gere exceções de I/O. Garante o fecho limpo do socket em caso de desconexão ou erro.
+     */
     @Override
     public void run() {
         String clientInfo = clientSocket.getInetAddress().getHostAddress() + ":" + clientSocket.getPort();
@@ -61,6 +84,16 @@ public class DashboardClientHandler implements Runnable {
         }
     }
     
+    /**
+     * Valida e extrai os dados estatísticos da mensagem.
+     * <p>
+     * Implementa uma lógica de correção de tipagem para payloads desserializados via Gson.
+     * Frequentemente, objetos genéricos são desserializados como {@code LinkedHashMap} em vez
+     * da classe alvo {@link StatsUpdatePayload}. Este método deteta essa situação e realiza
+     * uma conversão "round-trip" (Map -> JSON -> Object) para garantir a integridade dos dados.
+     *
+     * @param message A mensagem recebida da rede.
+     */
     private void processMessage(MessageProtocol message) {
         if (message.getType() != MessageType.STATS_UPDATE) {
             System.out.println("[Handler] Ignoring non-statistics message type: " + message.getType());
@@ -78,6 +111,7 @@ public class DashboardClientHandler implements Runnable {
             stats = (StatsUpdatePayload) payload;
         } else if (payload instanceof java.util.Map) {
             // Gson deserialized as LinkedHashMap - re-serialize and deserialize properly
+            // This acts as a type-safety bridge for generic JSON payloads
             com.google.gson.Gson gson = new com.google.gson.Gson();
             String json = gson.toJson(payload);
             stats = gson.fromJson(json, StatsUpdatePayload.class);
@@ -90,6 +124,15 @@ public class DashboardClientHandler implements Runnable {
         updateStatistics(senderId, stats);
     }
     
+    /**
+     * Aplica os dados recebidos ao modelo global de estatísticas.
+     * <p>
+     * Distingue entre atualizações incrementais (ex: contagem de veículos) e 
+     * substituições de estado (ex: tempo total de sistema reportado pelo nó de saída).
+     *
+     * @param senderId Identificador do nó que enviou a atualização (ex: "Cr1", "ExitNode").
+     * @param stats O objeto DTO contendo as métricas normalizadas.
+     */
     private void updateStatistics(String senderId, StatsUpdatePayload stats) {
         if (stats.getTotalVehiclesGenerated() >= 0) {
             statistics.updateVehiclesGenerated(stats.getTotalVehiclesGenerated());
@@ -134,4 +177,4 @@ public class DashboardClientHandler implements Runnable {
         
         System.out.println("[Handler] Successfully updated statistics from: " + senderId);
     }
-}
+}