Referência de aplicação. Esta é uma arquitetura ilustrativa e uma lista de verificação de escopo, não um projeto de cliente verificado nem uma implementação medida. As tecnologias, o escopo de integração e os itens de entrega são acordados para o briefing real.
Cenário e restrições
Uma operadora logística que substitui o despacho por planilhas e o faturamento manual. Duas restrições orientam o design: os motoristas trabalham em áreas sem sinal confiável, e cada linha da fatura deve ser justificável quando um cliente a contesta. Isso direciona o sistema para um registro de eventos somente para acréscimo como fonte de verdade, em vez de uma coluna de status que qualquer pessoa possa substituir.
Arquitetura
Camadas e responsabilidades
| Camada | Tecnologia | Pelo que é responsável |
|---|---|---|
| Web de operações | Vue 3 + Element Plus | Entrada de pedidos, painel de despacho, tratamento de exceções e revisão do faturamento. |
| Aplicativo do motorista | Android (Kotlin), com suporte offline | Lista de tarefas, leitura, foto, assinatura e captura de status. Tudo é gravado primeiro localmente e enviado quando há conexão disponível. |
| Portal do cliente | Mini programa do WeChat | Acompanhamento self-service; medir qualquer alteração no volume de consultas, em vez de presumir uma redução. |
| API | Go + Gin | Validação, regras de despacho, ingestão de eventos e cálculo de cobranças. |
| Armazenamento | MySQL | Remessas, eventos e liquidação. A tabela de eventos é somente para acréscimo e constitui o registro oficial do sistema. |
| Cache / fila | Redis | Cache do painel de despacho, deduplicação de uploads e tarefas em segundo plano para faturamento e notificações. |
| Arquivos | Armazenamento de objetos | Fotos e assinaturas de comprovantes de entrega, referenciadas por chave em vez de armazenadas no banco de dados. |
Modelo de dados
As tabelas abaixo contêm as regras das quais todo o restante depende. Errar aqui é o que transforma uma demonstração funcional em um sistema que não pode ser ampliado.
Entidades principais
| Entidade | Campos-chave, relações e regras |
|---|---|
| consignment | Registro da remessa: partes, endereços, tipo de serviço, janelas de horário, peso e volume declarados e a base de preços acordada na entrada. |
| shipment_event | Somente para acréscimo, com registro de data e hora, operador, localização, tipo de evento e payload. O status atual é derivado do evento mais recente, não armazenado separadamente — é isso que torna a linha do tempo defensável em uma contestação. |
| task / assignment | Designação de motorista e veículo com sequência de paradas, além do histórico de redistribuição quando uma tarefa é transferida. |
| pod_asset | Comprovante de entrega: chaves de fotos e assinaturas, registro de data e hora da captura e localização do dispositivo, mantidos como evidência por trás do faturamento. |
| charge / invoice | Linhas de cobrança geradas a partir de regras aplicadas aos eventos registrados, cada uma contendo o ID do evento que a justificou. Uma linha de fatura sem evento rastreável é rejeitada por definição. |
| rate_card | Regras de preços específicas por cliente, por peso, volume, distância, tempo de espera e sobretaxa, versionadas para que as faturas históricas continuem reproduzindo seus valores originais. |
Interfaces principais
Endpoints que transportam as regras de negócio
| Endpoint | Finalidade e observações sobre concorrência |
|---|---|
| POST /api/v1/consignments | Entrada do pedido com geocodificação do endereço e resolução do tarifário aplicável no momento da criação, para que a base de preços seja fixada antes da execução da tarefa. |
| POST /api/v1/events/batch | Upload em lote de eventos do aplicativo do motorista após uma interrupção de conectividade. Deduplicado por um UUID de evento do cliente e com o horário de captura armazenado separadamente do horário de recebimento, para que a linha do tempo permaneça fiel. |
| POST /api/v1/tasks/{id}/pod | Faz upload da assinatura e das fotos com o horário de captura, retornando chaves de armazenamento que são anexadas à remessa. |
| POST /api/v1/billing/run | Gera linhas de cobrança a partir dos eventos de um período. Idempotente por (cliente, período), para que uma reexecução corrija o resultado do faturamento, em vez de duplicá-lo. |
| GET /api/v1/track/{no} | Acompanhamento público, armazenado em cache, que expõe somente o subconjunto de eventos visível ao cliente. |
Decisões técnicas
- Eventos como fonte de verdade, status como valor derivado. Uma coluna de status editável perde o histórico do qual o tratamento de contestações depende. Derivar o status custa uma junção e proporciona uma trilha de auditoria completa e defensável.
- Horário de captura e horário de recebimento armazenados separadamente. A leitura feita por um motorista às 14:02 e enviada às 17:30 deve aparecer como 14:02, com um atraso de upload conhecido; caso contrário, toda área offline produzirá uma linha do tempo incorreta.
- UUIDs de eventos gerados pelo cliente. Reenvios são normais em conexões ruins, portanto a deduplicação precisa ocorrer com base em um identificador que o cliente controla.
- Tarifários versionados em vez de editados. Uma alteração de preço não deve reescrever silenciosamente as faturas do mês passado, portanto as versões antigas permanecem e as cobranças históricas continuam apontando para elas.
- Faturamento gerado, mas não emitido automaticamente. As regras abrangem os casos calculáveis; tudo que exige julgamento humano vai para uma fila de revisão, em vez de ser forçado à automação.
Metas hipotéticas de design
Os números abaixo são exemplos hipotéticos de planejamento de capacidade, não resultados medidos de clientes, uma recomendação de dimensionamento validada nem um SLA. Defina metas de aceitação específicas do projeto depois de determinar a carga de trabalho, os dispositivos, os dados, o hardware e as dependências de terceiros; verifique-as por meio de um piloto e de testes de carga antes de se comprometer com uma meta de produção.
Metas de capacidade e desempenho
| Meta | Valor e pressuposto |
|---|---|
| Ingestão de eventos | Lotes de até algumas centenas de eventos por upload, deduplicados e dimensionados para um motorista que retorna após várias horas offline. |
| Painel de despacho | Renderiza o conjunto de trabalho ativo em menos de 1 segundo, com filtragem e paginação no servidor, em vez de carregar tudo no navegador. |
| Execução do faturamento | Um mês de eventos de um cliente processado como tarefa em segundo plano com relatório de progresso; o tempo de execução varia conforme o volume de eventos e é medido com base nos seus dados reais durante a aceitação. |
| Upload de fotos | Comprimir e colocar em fila localmente antes do upload, repetir em caso de falha e verificar retenção, confirmação e recuperação nos dispositivos reais. |
O que a entrega inclui
- Código-fonte da web de operações, do backend Go, do aplicativo Android do motorista e do mini programa
- Esquema do banco de dados com as tabelas de eventos e liquidação documentadas, além do histórico de migrações
- Documentação da API, incluindo o contrato de upload offline e deduplicação
- Notas de implantação, configuração do armazenamento de objetos e procedimento de backup e restauração
- Plano de migração de dados das planilhas existentes, com relatório de reconciliação após a importação
Planejamento para sua empresa
Os módulos acima são um ponto de partida, não um pacote fixo. Normalmente reduzimos a primeira versão a um fluxo de trabalho principal e um fluxo administrativo, e depois ampliamos quando o uso real mostra onde a carga e os casos extremos realmente estão. Envie um briefing com escopo e nós o mapearemos nesta arquitetura e informaremos quais partes você ainda não precisa.
