📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados na Matriz de 20 Capítulos de Aplicações Full Stack. Recomendado revisar antes de iniciar a execução.

🛵 PI 06 — QuickDrop (DeliveryExpress): Roteamento & Logística

v1.0 — Projeto Integrador Full Stack para despacho expresso de encomendas, cálculo de distância geográfica via fórmula de Haversine, tarifação dinâmica e alocação de entregador por proximidade.

Trilha de Especialização Pedagógica — Série Projetos Integradores (PI 6 de 6)

• PI 01: ParkManager (Gestão de Vagas, Tarifação e Caixa)
• PI 02: SafePass Corporate (Cofre de Senhas, Criptografia e LGPD)
• PI 03: ChefPoint (Comanda Digital e KDS Restaurante)
• PI 04: TechBorrow (Empréstimo de Dispositivos de TI)
• PI 05: StockFlow (Almoxarifado e Ponto de Pedido)
• PI 06 (este): QuickDrop (Roteamento Expresso e Alocação de Couriers)

🎓 Nível Profissional Simulado: Engenheiro de Otimização Logística / Arquiteto de Sistemas. Em serviços de entrega expressa (Last-Mile Delivery), a eficiência de roteamento e despacho afeta diretamente o custo por entrega e o cumprimento do SLA. Dominar trigonometria esférica (Haversine), heurísticas de vizinho mais próximo e modelagem concorrente de rotas capacita para desafios de engenharia em escala de mercado.

🏛️ Galeria Arquitetural & Diagramas de Engenharia

Arquitetura de Roteamento e Despacho de Encomendas

Diagrama de Casos de Uso Formal (UML)

📁 Estrutura Canônica de Pastas Anti-Colisão

O projeto adota a convenção padronizada de subpastas por camada e tecnologia <camada>-<tecnologia>:

catalogo_projetos/fullstack_pi_06_quickdrop/
├── api-java/                   # Core de regras e modelos de domínio em Java
│   └── main/java/com/deliveryexpress/
│       ├── model/
│       │   ├── Entregador.java # Entidade de entregador com coordenadas e status
│       │   └── Pedido.java     # Pedido com geolocalização e SLA de entrega
│       └── service/
│           └── RoteamentoService.java # Algoritmo de roteirização e cálculo de taxa
├── tests/                      # Bateria de testes de contratos e precisão
│   └── test_quickdrop.py       # Testes unitários Haversine e alocação de courier
├── assets/                     # Galeria de diagramas vetoriais SVG autorais
├── main.py                     # CLI orquestrador e runner do laboratório
├── README.md                   # Resumo do projeto integrador
└── DeliveryExpress_Documentacao_Final.md # Especificação acadêmica de engenharia

🧑‍💼 Especificação Formal de Engenharia de Software

1. Histórias de Usuário (User Stories)

• US-QD01: Como despachante de pedidos, quero cadastrar entregas com endereço de coleta e destino calculando automaticamente a distância e a estimativa de tempo.
• US-QD02: Como cliente solicitante, quero visualizar o valor exato da taxa de entrega baseado na distância em quilômetros com tarifa base transparente.
• US-QD03: Como entregador (courier), quero receber a notificação do pedido com mapa de trajeto otimizado até o ponto de entrega.
• US-QD04: Como despachante, quero que o sistema aloque automaticamente o entregador disponível mais próximo do ponto de coleta (Nearest Neighbor).
• US-QD05: Como gerente de logística, quero monitorar o SLA de tempo total desde a criação do pedido até a confirmação de entrega.

2. Requisitos Funcionais (RF)

• RF-QD01: O sistema deve calcular a distância geodésica entre duas coordenadas (latitude/longitude) utilizando a fórmula de Haversine com precisão decimal.
• RF-QD02: A taxa de entrega deve ser calculada pela fórmula: $Taxa = R$\ 5,00 + (Distância_{km} \times R$\ 2,50)$.
• RF-QD03: O algoritmo de alocação deve filtrar apenas couriers com status disponivel == True antes de determinar a menor distância.
• RF-QD04: O sistema deve atualizar o status do pedido para as etapas sequenciais: CRIADO, DESPACHADO, EM_TRANSITO e ENTREGUE.
• RF-QD05: A CLI interativa (main.py) deve permitir executar a suíte completa de testes unitários e exibir o extrato do roteamento.

3. Requisitos Não-Funcionais (RNF)

• RNF-QD01 (Precisão Geográfica): O erro de cálculo de distância do algoritmo Haversine não deve ultrapassar 0.5% em distâncias urbanas de até 50km.
• RNF-QD02 (Velocidade de Despacho): A seleção do entregador ideal entre 1.000 profissionais cadastrados deve ser computada em menos de 10 milissegundos.
• RNF-QD03 (Modularidade): O núcleo de cálculo de rotas em Java deve ser desacoplado da interface permitindo reutilização via microserviço ou API REST.
• RNF-QD04 (Testabilidade): Toda a lógica matemática de roteamento deve ter cobertura de 100% por testes unitários automatizados.
• RNF-QD05 (Compatibilidade Multiplataforma): Os scripts de teste e execução devem operar indistintamente em Windows, Linux e macOS sem dependências de compilação nativa externa.

📐 Diagrama de Casos de Uso (Mermaid)

flowchart LR
    subgraph Atores
        Cliente["👤 Cliente Solicitante"]
        Despachante["🏢 Despachante Logístico"]
        Entregador["🛵 Entregador (Courier)"]
    end

    subgraph "Sistema QuickDrop (DeliveryExpress)"
        UC01["UC01: Cotar Taxa de Entrega"]
        UC02["UC02: Calcular Distância Haversine"]
        UC03["UC03: Alocar Courier Mais Próximo"]
        UC04["UC04: Despachar e Rastrear Pedido"]
        UC05["UC05: Auditar Cumprimento de SLA"]
    end

    Cliente --> UC01
    UC01 -.-> UC02
    Despachante --> UC03
    Despachante --> UC04
    Entregador --> UC04
    Despachante --> UC05

📊 Matriz de Rastreabilidade de Requisitos (RTM)

🚀 Roteiro de Execução & Homologação no Laboratório

1. Execução Automatizada via CLI Python (main.py)

cd catalogo_projetos/fullstack_pi_06_quickdrop

# Execução do menu interativo
python main.py

• Digite 1 para rodar a suíte de testes de cálculo de distância e alocação.
• Digite 2 para visualizar o extrato da documentação de engenharia.

2. Execução Direta da Suíte de Testes Unitários

python -m unittest tests/test_quickdrop.py

🧪 Matriz de Checkpoints de Homologação (CP-01 a CP-05)