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 implantação mensurada. 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 fábrica que está substituindo o acompanhamento da produção em planilhas. O requisito decisivo é a rastreabilidade bidirecional: dado um número de série acabado, listar cada lote de material utilizado nele e, dado um lote de material defeituoso, listar cada unidade acabada afetada. Esse requisito determina o modelo de dados — ele não pode ser simplesmente acrescentado posteriormente sem reprocessar o histórico.
Arquitetura
Camadas e responsabilidades
| Camada | Tecnologia | Responsável por |
|---|---|---|
| Web do escritório | Vue 3 + Element Plus | Liberação de ordens, manutenção da BOM, programação, revisão da qualidade e relatórios. |
| Cliente do chão de fábrica | Dispositivo portátil / tablet Android (Kotlin), com capacidade offline | Apontamento orientado por leitura em cada estação. Projetado para mãos com luvas e Wi-Fi ruim: alvos grandes, poucos toques, fila local. |
| API | Go + Gin | Validação dos apontamentos em relação ao roteiro, regras de consumo de materiais e consultas de rastreabilidade. |
| Armazenamento | MySQL | Ordens, roteiro, registros de apontamento e genealogia dos lotes. |
| Gateway de dispositivos | Ponte MQTT ou OPC UA (opcional) | Obtém contagens ou medições dos equipamentos quando o fornecedor expõe uma interface, normalizadas nas mesmas tabelas de apontamentos. |
| Relatórios | Jobs de agregação programados | Rendimento, tempo de ciclo e carga das estações pré-calculados, pois essas consultas percorrem um histórico grande demais para serem executadas em tempo real a cada carregamento do painel. |
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 |
|---|---|
| item / bom | Lista de materiais multinível com datas de vigência e regras de substituição. As versões da BOM são mantidas, não sobrescritas, para que uma ordem criada no mês passado ainda seja resolvida com base na BOM que realmente utilizou. |
| work_order / routing_step | A ordem e sua lista ordenada de operações, cada uma vinculada a um centro de trabalho com tempo padrão e as regras de apontamento dessa etapa. |
| production_report | Produção por estação: operador, horário de início e término, quantidade boa, retrabalho e refugo com códigos de motivo. Esta é a entrada da qual toda métrica deriva, portanto suas regras de validação são mais importantes que os painéis. |
| material_lot / lot_consumption | Lotes recebidos e seu consumo em uma ordem de produção. lot_consumption é a relação que possibilita a genealogia — sem ela, a rastreabilidade se reduz a suposições. |
| serial / genealogy | Unidades acabadas serializadas vinculadas aos lotes consumidos, formando o grafo que responde às duas direções de rastreabilidade. |
| inspection / defect | Pontos de inspeção, regra de amostragem, códigos de defeito e disposição (aceitar, retrabalhar, sucatear), cada um vinculado novamente ao apontamento que produziu a unidade. |
Interfaces principais
Endpoints que transportam as regras de negócio
| Endpoint | Finalidade e observações sobre concorrência |
|---|---|
| POST /api/v1/reports | Apontamento da estação. Valida se a etapa anterior do roteiro foi concluída, se a quantidade apontada não excede a quantidade liberada e se o consumo de materiais está dentro da tolerância da BOM — rejeitar entradas inválidas aqui é o que mantém os dados de apontamento confiáveis. |
| POST /api/v1/reports/batch | Upload da fila offline dos dispositivos portáteis, com deduplicação por UUID do cliente e preservação do horário de captura. |
| GET /api/v1/trace/forward/{lot} | Dado um lote de material, retorna todos os números de série acabados afetados — a consulta da qual um recall depende. |
| GET /api/v1/trace/backward/{serial} | Dado um número de série acabado, retorna a genealogia completa dos lotes de material. |
| POST /api/v1/work-orders/{id}/release | Libera uma ordem, criando um snapshot da BOM e da versão do roteiro para que futuras edições dos dados mestres não possam reescrever o histórico. |
Decisões técnicas
- Genealogia modelada desde o início. Adaptar a rastreabilidade posteriormente significa que os dados históricos nunca poderão ser rastreados. Se a rastreabilidade for uma possível exigência futura, a relação lot_consumption deverá existir desde a primeira versão, mesmo que os relatórios venham depois.
- BOM e roteiro capturados em snapshot na liberação da ordem. Os dados mestres mudam constantemente; as ordens devem continuar sendo resolvidas com base na versão com a qual foram liberadas, ou a variação de custo e consumo perde o significado.
- Validação no endpoint de apontamento, não no painel. Métricas calculadas a partir de entradas não validadas produzem números aparentemente confiáveis, mas incorretos. Rejeitar um apontamento impossível na entrada é mais barato que explicar posteriormente um número de rendimento incorreto.
- Fila offline no dispositivo portátil. O Wi-Fi da fábrica tem zonas sem cobertura próximas a metais e máquinas. Apontamentos que falham nessas zonas simplesmente não serão realizados, e o conjunto de dados pode acabar desenvolvendo lacunas silenciosamente.
- Coexistência com o ERP existente em vez de substituí-lo. Compare uma interface de escopo definido para ordens e movimentações de estoque com uma migração de ERP, usando as dependências, os custos e os riscos reais; confirme o fluxo financeiro antes de escolher.
Metas de design hipotéticas
Os números abaixo são exemplos hipotéticos de planejamento de capacidade, não resultados mensurados de clientes, uma recomendação de dimensionamento validada nem um SLA. Defina metas de aceitação específicas do projeto após definir 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 assumir uma meta de produção.
Metas de capacidade e desempenho
| Meta | Valor e premissa |
|---|---|
| Leitura até confirmação | Meta hipotética: retorno local inferior a 1 segundo para um apontamento e dispositivo definidos. Persista os registros enfileirados e diferencie o reconhecimento local da aceitação pelo servidor; teste atrasos e falhas de rede. |
| Consulta de rastreabilidade | As duas direções retornam em poucos segundos para uma profundidade genealógica típica, usando relações indexadas de lotes e números de série; conjuntos multinível profundos devem ser validados com seus dados reais durante a aceitação. |
| Painel de relatórios | Servido a partir de agregações pré-calculadas, atualizadas conforme uma programação acordada com as operações, em vez de percorrer apontamentos brutos a cada carregamento de página. |
| Tolerância offline | Um turno completo de apontamentos enfileirados localmente e enviados na reconexão, com deduplicação pelo UUID do cliente. |
O que a entrega inclui
- Código-fonte do web do escritório, do backend Go e do cliente Android do chão de fábrica no seu repositório
- Esquema do banco de dados com versionamento da BOM e tabelas de genealogia documentados, além do histórico de migrações
- Documentação da API, incluindo o contrato de upload offline e as regras de validação dos apontamentos
- Especificação da interface com o ERP e o formato de intercâmbio acordado
- Notas de implantação, procedimento de backup e restauração e notas de configuração do hardware de etiquetagem ou dos leitores
Planejando isso 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 mais um fluxo administrativo e, depois, ampliamos quando o uso real mostra onde a carga e os casos extremos de fato estão. Envie um briefing com escopo definido e nós o compararemos com esta arquitetura e informaremos quais partes você ainda não precisa.