SD/main/docs/README.md

📚 Índice da Documentação de Serialização

Visão Geral

Esta pasta contém toda a documentação relacionada ao design e implementação do formato de serialização para o sistema de simulação de tráfego distribuído.

---

📄 Documentos Disponíveis

1. SERIALIZATION_SPECIFICATION.md

📖 Especificação Completa

Documento técnico detalhado contendo:

• Análise completa de requisitos
• Comparação Java Serialization vs JSON
• Justificativa da decisão
• Estrutura de mensagens
• Plano de implementação
• Considerações de segurança e performance

Quando usar: Para entender a fundo todo o processo de decisão e detalhes técnicos.

---

2. SERIALIZATION_DECISION.md

⚡ Guia Rápido de Decisão

Documento executivo com:

• TL;DR (resumo executivo)
• Tabela de decisão rápida
• Critérios por cenário
• Análise de impacto
• Checklist de implementação

Quando usar: Para referência rápida ou ao explicar a decisão a outros.

---

3. SERIALIZATION_SUMMARY.md

✅ Resumo de Implementação

Sumário executivo contendo:

• Status de implementação
• Arquivos criados
• Métricas de performance
• Exemplos de uso
• Próximos passos

Quando usar: Para ver o que foi implementado e como usar.

---

4. SERIALIZATION_ARCHITECTURE.md

🏗️ Diagramas de Arquitetura

Documentação visual com:

• Diagramas ASCII da arquitetura
• Fluxos de serialização
• Comparação de formatos
• Integração com o sistema
• Cenários de uso

Quando usar: Para entender visualmente a arquitetura e fluxos.

---

🗂️ Estrutura do Projeto

docs/
├── SERIALIZATION_SPECIFICATION.md   # Especificação completa
├── SERIALIZATION_DECISION.md        # Guia de decisão
├── SERIALIZATION_SUMMARY.md         # Resumo de implementação
├── SERIALIZATION_ARCHITECTURE.md    # Diagramas
└── README.md                         # Este arquivo (índice)

src/main/java/sd/serialization/
├── MessageSerializer.java           # Interface
├── SerializationException.java      # Exceção
├── JsonMessageSerializer.java       # Implementação JSON
├── JavaMessageSerializer.java       # Implementação Java
├── SerializerFactory.java           # Factory
├── SerializationExample.java        # Exemplo de uso
└── README.md                         # Guia do pacote

src/test/java/sd/serialization/
└── SerializationTest.java            # Testes unitários

---

🚀 Início Rápido

Para Desenvolvedores

1. Entender a decisão
   → Ler SERIALIZATION_DECISION.md

2. Ver exemplos de uso
   → Ler ../src/main/java/sd/serialization/README.md

3. Executar exemplo

   mvn exec:java -Dexec.mainClass="sd.serialization.SerializationExample"
   

4. Executar testes

   mvn test -Dtest=SerializationTest
   

Para Arquitetos/Gestores

1. Resumo executivo
   → Ler SERIALIZATION_SUMMARY.md

2. Justificativa técnica
   → Ler SERIALIZATION_SPECIFICATION.md (Seção 4)

3. Arquitetura visual
   → Ler SERIALIZATION_ARCHITECTURE.md

---

📊 Decisão Final

✅ JSON (Gson) - Recomendado

Justificativa em uma frase:
JSON oferece 54% menos tamanho, debugging superior e extensibilidade futura, com overhead de performance desprezível (7 μs) para nosso caso de uso.

Métricas chave:

• Tamanho: 300 bytes (vs 657 Java)
• Latência: 40.79 μs (vs 33.34 Java)
• Legibilidade: Alta (vs Baixa Java)
• Impacto no sistema: < 0.1%

---

🔗 Links Rápidos

Documentação

• Especificação Completa
• Guia de Decisão
• Resumo
• Arquitetura

Código

• Package README
• MessageSerializer.java
• JsonMessageSerializer.java
• SerializerFactory.java

Exemplos e Testes

• SerializationExample.java
• SerializationTest.java

Recursos Externos

• Gson User Guide
• Java Serialization Spec
• JSON Schema

---

🎯 Casos de Uso

Cenário 1: Transferir Veículo entre Cruzamentos

MessageSerializer serializer = SerializerFactory.createDefault();
Message msg = new Message(MessageType.VEHICLE_TRANSFER, "Cr1", "Cr2", vehicle);
byte[] data = serializer.serialize(msg);
socket.getOutputStream().write(data);

Documento relevante: Package README

Cenário 2: Enviar Estatísticas para Dashboard

MessageSerializer serializer = new JsonMessageSerializer(false);
StatsUpdate stats = collectStats();
byte[] data = serializer.serialize(stats);
sendToDashboard(data);

Documento relevante: SERIALIZATION_ARCHITECTURE.md - Seção "Integração Futura"

Cenário 3: Debugging de Mensagens

MessageSerializer serializer = new JsonMessageSerializer(true); // Pretty print
byte[] data = serializer.serialize(message);
logger.debug("Sent: " + new String(data)); // Legível!

Documento relevante: SERIALIZATION_DECISION.md - Seção "Debugging"

---

❓ FAQ

Por que não Protocol Buffers ou MessagePack?

R: Para este projeto, JSON oferece o melhor balanço entre simplicidade, debugging e performance. Protobuf seria overkill para o volume de mensagens esperado.

Posso mudar de JSON para Java Serialization depois?

R: Sim! A interface MessageSerializer permite trocar a implementação mudando apenas uma linha de código.

Como debug mensagens binárias (Java)?

R: Não é trivial. Por isso JSON é recomendado. Veja SERIALIZATION_DECISION.md para detalhes.

JSON é suficientemente rápido?

R: Sim. A diferença de 7 μs é desprezível comparado à latência de rede (~1000 μs). Veja SERIALIZATION_SPECIFICATION.md - Seção 3.2.

Como adicionar novo tipo de mensagem?

R: Basta criar a classe com getters/setters. JSON funciona automaticamente. Veja Package README.

---

📝 Histórico de Versões

Versão	Data	Alterações
1.0	2025-10-22	Implementação inicial completa
		- Especificação de design
		- Implementação JSON e Java
		- Testes unitários (14/14)
		- Documentação completa

---

👥 Contribuidores

• Design e Implementação: Equipa SD - Trabalho Prático
• Revisão Técnica: GitHub Copilot
• Testes: Suite automatizada JUnit 5

---

📧 Suporte

Para questões ou problemas:

1. Consultar documentação relevante acima
2. Ver exemplos de código em SerializationExample.java
3. Executar testes: mvn test -Dtest=SerializationTest
4. Contactar equipa do projeto

---

Última atualização: 22 de outubro de 2025
Status: ✅ Completo e Pronto para Uso
Próximo passo: Integração com camada de comunicação (sockets)