Sistemas de Ordem de Serviço: Modelagem e Boas Práticas para Manutenção

Introdução

Toda operação que envolve ativos físicos — esteiras, veículos, equipamentos, centros de distribuição — em algum momento precisa de manutenção. O registro formal desse trabalho é a Ordem de Serviço (OS): um documento (hoje, quase sempre digital) que descreve o problema, o ativo envolvido, o técnico responsável, o histórico de ações tomadas e o status atual. Parece simples, mas modelar isso bem é o que separa um sistema confiável de uma planilha glorificada.

1. As entidades principais do domínio

Ativo (Asset): o equipamento ou recurso que motivou a OS — uma esteira, um veículo de frota, um terminal de leitura. Cada ativo tem seu próprio histórico de manutenções.

Ordem de Serviço (Service Order): a entidade central, com tipo (corretiva, preventiva, preditiva), prioridade, ativo relacionado, técnico responsável, status e um histórico de mudanças.

Evento de Manutenção: cada ação registrada dentro da OS — diagnóstico, peça trocada, teste realizado — normalmente com timestamp e autor, formando uma trilha de auditoria.

Técnico/Equipe: quem executa o trabalho, com sua agenda, especialidade e localização.

class ServiceOrder {
    UUID id;
    Asset asset;
    ServiceOrderType type;      // CORRETIVA, PREVENTIVA, PREDITIVA
    ServiceOrderStatus status;  // ABERTA, EM_ANDAMENTO, CONCLUIDA, CANCELADA
    Priority priority;          // BAIXA, MEDIA, ALTA, CRITICA
    Technician assignedTo;
    List<MaintenanceEvent> history;
    Instant createdAt;
    Instant closedAt;
}

2. O ciclo de vida como máquina de estados

Um erro comum é tratar o campo status como um simples texto que qualquer parte do código pode sobrescrever. Isso abre espaço para estados inválidos — uma OS "concluída" que volta para "aberta" sem passar por "em andamento", por exemplo. A forma correta é modelar o status como uma máquina de estados explícita, com transições permitidas bem definidas.

ABERTA        -> EM_ANDAMENTO   (técnico inicia o atendimento)
EM_ANDAMENTO  -> CONCLUIDA      (serviço finalizado com sucesso)
ABERTA        -> CANCELADA      (chamado duplicado ou improcedente)
EM_ANDAMENTO  -> CANCELADA      (ativo indisponível, interrompido)

Cada transição pode disparar regras de negócio próprias: só é possível concluir uma OS se houver ao menos um evento de manutenção registrado; cancelar uma OS em andamento exige justificativa; etc. Isolar essas regras em um único lugar (a própria entidade ou um serviço de domínio dedicado) evita que estados inconsistentes apareçam espalhados pelo sistema.

3. Integrando com uma arquitetura orientada a eventos

Assim como discutido em Arquitetura Orientada a Eventos, cada mudança de status de uma OS é, na prática, um fato de negócio relevante para outras partes do sistema — e não só um UPDATE silencioso no banco.

@Transactional
public ServiceOrder transitionTo(UUID orderId, ServiceOrderStatus newStatus) {
    ServiceOrder order = repository.findById(orderId).orElseThrow();
    order.transitionTo(newStatus); // valida a transição internamente

    repository.save(order);
    eventPublisher.publish(
        new ServiceOrderStatusChangedEvent(order.getId(), newStatus, Instant.now())
    );

    return order;
}

Com o evento publicado, o time de campo pode ser notificado automaticamente, o dashboard de operações se atualiza em tempo real, e o time de analytics acumula dados de MTTR (tempo médio de reparo) sem que o serviço de ordens de serviço precise saber que essas integrações existem.

4. Boas práticas que evitam dor de cabeça

Nunca apague, sempre encerre: uma OS cancelada ou concluída deve permanecer no histórico. Ela é dado de auditoria e de análise futura, não lixo a ser removido.

Idempotência nas integrações: se o mesmo evento de sensor chegar duas vezes, o sistema não deve abrir duas ordens de serviço idênticas — normalmente resolvido com uma chave de deduplicação (ex: assetId + tipoDeFalha + janela de tempo).

SLA como dado, não como suposição: prioridade e tipo de OS devem estar associados a um prazo esperado de atendimento, para que atrasos sejam visíveis e mensuráveis — não descobertos apenas quando o cliente reclama.

Histórico imutável: cada evento de manutenção registrado (diagnóstico, peça trocada, teste) deve ser append-only. Corrigir um erro de registro deve gerar uma nova entrada explicando a correção, não sobrescrever a antiga.

Conclusão

Um sistema de Ordem de Serviço bem modelado é muito mais do que um CRUD com um campo de status: é uma máquina de estados bem definida, com histórico auditável e integrada ao restante da operação através de eventos. Quando esses fundamentos são respeitados, o sistema deixa de ser apenas um registro burocrático e passa a ser uma fonte confiável de dados para manutenção preditiva, indicadores de desempenho e decisões operacionais em tempo real.