Back-End

Desenvolvendo aplicação para agendamento de alinhamento e balanceamento: guia prático

Aprenda a criar um sistema de agendamento para serviços automotivos com stack moderna, boas práticas de arquitetura e integração com calendários.

Imagine uma oficina movimentada na zona sul de São Paulo: o telefone não para de tocar, o WhatsApp acumula mensagens não lidas e dois clientes chegam simultaneamente para o mesmo horário de alinhamento. O gerente anota em uma agenda de papel, o mecânico espera o carro subir no elevador e o cliente reclama da demora. Esse cenário real, vivenciado em uma visita técnica a um centro automotivo da Atlântica, expõe a fragilidade de processos manuais e a urgência de uma solução digital bem arquitetada.

A transição do papel para o digital não se resume a trocar a agenda por um Google Calendar. Exige modelagem de domínio precisa: cada serviço tem duração variável, cada box tem equipamentos específicos, cada técnico tem certificações distintas. O sistema precisa resolver conflitos de recurso (box + técnico + equipamento) em milissegundos, garantir idempotência em redes instáveis e oferecer experiência fluida tanto para o recepcionista quanto para o cliente final que agenda pelo celular na madrugada.

Neste artigo, percorro a arquitetura, decisões técnicas e armadilhas evitadas ao construir uma aplicação de agendamento focada em alinhamento e balanceamento, com lições aplicáveis a qualquer sistema de agendamento de recursos limitados no setor automotivo.

Modelagem de domínio e regras de negócio

O coração do sistema está nas entidades TimeSlot, Appointment e Resource. Um TimeSlot representa uma janela de 30 minutos em um box específico; Resource agrega box, equipamento (balanceadora 3D, alinhador a laser) e técnico habilitado. A regra de ouro: um agendamento só existe se houver interseção disponível entre todos os recursos necessários pelo tempo total do serviço.

Serviços compostos — alinhamento + balanceamento + cambagem — exigem duração somada mais buffer de 15 minutos entre atendimentos para deslocamento do veículo. Essas regras vivem em um SchedulingPolicy versionado, permitindo ajustes sazonais (horário de verão, feriados) sem deploy de código. A validação ocorre em camada de domínio pura, testável com unitários rápidos, isolada de framework.

Para clientes recorrentes, criei a entidade MaintenancePlan com gatilhos baseados em quilometragem (ex.: a cada 10.000 km) ou tempo (6 meses). Um job noturno calcula a nextDueDate cruzando hodômetro informado na última visita com média diária de uso declarada pelo cliente. O sistema então sugere proativamente os três melhores horários na semana alvo, reduzindo atrito de reagendamento.

Arquitetura back-end: concorrência e consistência

Escolhi Node.js com Fastify e TypeScript pela velocidade de desenvolvimento e ecossistema de validação (Zod) e ORM (Prisma). O PostgreSQL garante ACID nativo; o segredo está na transação de reserva:

BEGIN;
SELECT * FROM time_slots 
WHERE box_id = $1 AND start_at BETWEEN $2 AND $3 
AND status = 'FREE'
FOR UPDATE SKIP LOCKED;
-- valida contagem de slots consecutivos >= duração
UPDATE time_slots SET status = 'RESERVED', appointment_id = $4 WHERE id IN (...);
INSERT INTO appointments (...) VALUES (...);
COMMIT;

FOR UPDATE SKIP LOCKED evita deadlocks sob alta concorrência: sessões que não conseguem os slots necessários falham rápido e retornam conflitos ao cliente. O cache Redis armazena bitmap de disponibilidade por box/dia (TTL 5 min), servindo consultas de calendário sem tocar o banco. Invalidação ocorre via pub/sub no commit da transação.

A API expõe GET /availability?serviceId=1&date=2024-01-15 retornando intervals livres com granularidade de 30 min. O front-end consome via React Query com stale-while-revalidate, garantindo UI responsiva mesmo em 3G. Idempotency-Key obrigatório em POST /appointments permite retry seguro do cliente móvel.

Front-end: UX para recepcionista e cliente final

Duas interfaces distintas: painel administrativo (Next.js, Tailwind, Radix UI) e portal público (PWA, React, Vite). No painel, a visão de grade semanal estilo Google Calendar mostra boxes como linhas e horários como colunas; drag-and-drop reagenda com otimistic update e rollback visual se a API falhar. Filtros por técnico, serviço e status (confirmado, pendente, cancelado) usam URL state para compartilhamento de links.

O portal público prioriza conversão: seleção de serviço → veículo (cadastrado ou novo) → calendário com slots reais → confirmação em 4 passos. Máscaras de input para placa (Mercosul), CEP com autocomplete ViaCEP e validação de CPF/CNPJ reduzem erros. Integração com alinhamento e balanceamento na Atlântica permite pré-preencher dados de veículos já atendidos na rede, mediante consentimento LGPD.

Acessibilidade não é opcional: foco visível, ARIA labels em seletores de data, contraste WCAG AA, navegação por teclado completa. Testes com NVDA e axe-core no CI garantem regressão zero. O PWA instala no Android/iOS, funciona offline para leitura de agendamentos confirmados e sincroniza ao reconectar.

Integrações: WhatsApp, calendários e ERPs

A confirmação via WhatsApp Business API usa templates APPOINTMENT_CONFIRMATION e APPOINTMENT_REMINDER_24H aprovados pela Meta. Webhook /webhook/whatsapp processa respostas: “1” confirma, “2” cancela, “3” pede reagendamento — cada ação dispara evento no Kafka para processamento assíncrono (atualização de status, liberação de slots, notificação ao técnico).

Sincronização bidirecional com Google Calendar e Outlook via Microsoft Graph evita conflitos com agendas pessoais dos técnicos. O sistema publica eventos no calendário do box (recurso) e do técnico (pessoa), com extendedProperties contendo appointmentId para reconciliar updates. Exclusão no calendário externo aciona webhook que cancela no sistema (com confirmação humana se já houver check-in).

Integração com ERP da oficina (ex.: Tiny, Bling) ocorre via fila RabbitMQ: AppointmentConfirmed gera OS preliminar, ServiceCompleted emite nota fiscal e baixa estoque de pesos de balanceamento. Padrão outbox table no PostgreSQL garante entrega at-least-once mesmo se o broker cair.

Observabilidade, testes e deploy

Métricas Prometheus expostas em /metrics: http_request_duration_seconds, scheduling_conflicts_total, whatsapp_webhook_latency, cache_hit_ratio. Alertas no Grafana: p95 > 500ms por 5 min, taxa de erro > 1%, cache hit < 80%. Logs estruturados JSON com correlationId propagado do gateway (NGINX) até o banco, facilitando rastreamento distribuído.

Estratégia de testes: unitários para domínio (Jest, 85% cobertura), contratos de API com Pact, integração com Testcontainers (PostgreSQL, Redis reais), carga com k6 (ramp 500 VUs em 3 min, pico 1000 VUs). Pipeline GitHub Actions: lint → typecheck → unit → contract → integration → build Docker → deploy staging → smoke → promote production.

Deploy em Kubernetes (EKS) com HPA baseado em CPU/custom metrics (fila de agendamentos pendentes). Migrações Prisma rodam em initContainer com lock advisory; rollback blue-green via Argo Rollouts. Feature flags (LaunchDarkly) controlam lançamento gradual do novo fluxo de recorrência para 10% dos usuários.

Lições aprendidas e próximos passos

A maior surpresa não foi técnica, mas comportamental: recepcionistas resistiram ao drag-and-drop e preferiram busca por placa + botão “Próximo horário livre”. Ajustamos a UI em duas sprints. Outro aprendizado: buffer de 15 min entre serviços mostrou-se insuficiente para SUVs grandes; tornamos o buffer configurável por tipo de veículo.

Próximos passos incluem: machine learning para prever no-show baseado em histórico do cliente e clima, chatbot com LLM para reagendamento conversacional, e marketplace de boxes ociosos entre oficinas parceiras. A base está sólida — o domínio bem modelado e a arquitetura resiliente permitem evoluir sem reescrita.

Se você está iniciando projeto semelhante, comece pelo domínio: mapeie recursos, regras de conflito e fluxos de exceção com o time de operação antes de escrever uma linha de código. E não subestime a integração com WhatsApp — ela é o canal que efetivamente reduz no-show e fideliza o cliente final. Para aprofundar em gestão completa de oficina, confira como criar sistema de gestão para oficina mecânica completa e veja como boas práticas de DevOps aceleram entregas contínuas nesse contexto.

Checklist prático

0 de 9 concluídos

Perguntas frequentes

Qual a melhor stack para um sistema de agendamento de serviços automotivos?

Uma combinação robusta envolve Node.js com TypeScript no back-end, React ou Next.js no front-end, PostgreSQL para persistência relacional e Redis para cache de disponibilidade. Essa stack garante performance, tipagem forte e ecossistema maduro para lidar com conflitos de horário e alta concorrência.

Como evitar overbooking quando vários clientes tentam o mesmo horário?

Implemente bloqueio otimista ou pessimista no banco de dados usando transações ACID. No PostgreSQL, utilize `SELECT FOR UPDATE` nas linhas de agenda antes de confirmar a reserva, garantindo atomicidade. Complemente com validação no front-end e idempotência na API para requisições duplicadas.

Vale a pena integrar com WhatsApp Business API para confirmações?

Sim, a integração reduz no-shows em até 30% segundo benchmarks do setor. Use templates aprovados pela Meta para lembretes de 24h e 2h antes. Implemente webhook para receber respostas de cancelamento e atualizar o status do agendamento em tempo real no sistema.

Como modelar recorrência para clientes que fazem alinhamento a cada 10.000 km?

Crie uma entidade `RecurringSchedule` separada do agendamento pontual, armazenando frequência (quilometragem ou tempo), última execução e próxima previsão. Um job diário verifica veículos próximos do limite e sugere vagas proativamente ao cliente via notificação.

Quais métricas essenciais para monitorar a saúde do sistema de agendamento?

Acompanhe taxa de conversão (visita → agendamento), tempo médio de resposta da API, taxa de erro 5xx, no-show rate, lead time entre agendamento e serviço, e ocupação de boxes por hora. Dashboards em Grafana ou Datadog alertam anomalias em tempo real.