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

Entender a decisão
→ Ler SERIALIZATION_DECISION.md
Ver exemplos de uso
→ Ler ../src/main/java/sd/serialization/README.md

Executar exemplo

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

Executar testes
```
mvn test -Dtest=SerializationTest
```

Para Arquitetos/Gestores

Resumo executivo
→ Ler SERIALIZATION_SUMMARY.md
Justificativa técnica
→ Ler SERIALIZATION_SPECIFICATION.md (Seção 4)
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

Código

Exemplos e Testes

Recursos Externos

🎯 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:

Consultar documentação relevante acima
Ver exemplos de código em SerializationExample.java
Executar testes: mvn test -Dtest=SerializationTest
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)