# 📚 Í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](./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](./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](./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](./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](./SERIALIZATION_DECISION.md)

2. **Ver exemplos de uso**  
   → Ler [../src/main/java/sd/serialization/README.md](../src/main/java/sd/serialization/README.md)

3. **Executar exemplo**  
   ```bash
   mvn exec:java -Dexec.mainClass="sd.serialization.SerializationExample"
   ```

4. **Executar testes**  
   ```bash
   mvn test -Dtest=SerializationTest
   ```

### Para Arquitetos/Gestores

1. **Resumo executivo**  
   → Ler [SERIALIZATION_SUMMARY.md](./SERIALIZATION_SUMMARY.md)

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

3. **Arquitetura visual**  
   → Ler [SERIALIZATION_ARCHITECTURE.md](./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](./SERIALIZATION_SPECIFICATION.md)
- [Guia de Decisão](./SERIALIZATION_DECISION.md)
- [Resumo](./SERIALIZATION_SUMMARY.md)
- [Arquitetura](./SERIALIZATION_ARCHITECTURE.md)

### Código
- [Package README](../src/main/java/sd/serialization/README.md)
- [MessageSerializer.java](../src/main/java/sd/serialization/MessageSerializer.java)
- [JsonMessageSerializer.java](../src/main/java/sd/serialization/JsonMessageSerializer.java)
- [SerializerFactory.java](../src/main/java/sd/serialization/SerializerFactory.java)

### Exemplos e Testes
- [SerializationExample.java](../src/main/java/sd/serialization/SerializationExample.java)
- [SerializationTest.java](../src/test/java/sd/serialization/SerializationTest.java)

### Recursos Externos
- [Gson User Guide](https://github.com/google/gson/blob/master/UserGuide.md)
- [Java Serialization Spec](https://docs.oracle.com/javase/8/docs/platform/serialization/spec/serialTOC.html)
- [JSON Schema](https://json-schema.org/)

---

## 🎯 Casos de Uso

### Cenário 1: Transferir Veículo entre Cruzamentos
```java
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](../src/main/java/sd/serialization/README.md)

### Cenário 2: Enviar Estatísticas para Dashboard
```java
MessageSerializer serializer = new JsonMessageSerializer(false);
StatsUpdate stats = collectStats();
byte[] data = serializer.serialize(stats);
sendToDashboard(data);
```

**Documento relevante**: [SERIALIZATION_ARCHITECTURE.md](./SERIALIZATION_ARCHITECTURE.md) - Seção "Integração Futura"

### Cenário 3: Debugging de Mensagens
```java
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](./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](./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](./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](../src/main/java/sd/serialization/README.md).

---

## 📝 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)