Ordens de Serviço da Oficina

O problema do Seu Renato

O Seu Renato tem uma oficina mecânica de bairro e até hoje controla tudo em planilha: qual cliente trouxe qual carro, o que foi feito em cada visita e quanto ficou pronto. Ele quer parar de perder informação e ter um sistema onde ele controla tudo, os mecânicos veem só as ordens de serviço deles, e os clientes conseguem consultar o status do próprio carro pelo celular.

Modelagem dos dados

• Cliente: dados de contato do dono do veículo.
• Veiculo: placa, modelo e ano, sempre vinculado a um cliente, relação 1:N entre cliente e veículos (um cliente pode ter vários carros).
• OrdemDeServico: registro de uma visita à oficina, vinculada a um veículo e a um mecânico responsável, com status (aberta, em andamento, concluída).
• Servico: catálogo de serviços que a oficina oferece (troca de óleo, alinhamento, revisão de freios etc.), com preço.
• Uma ordem de serviço pode incluir vários serviços do catálogo, e um mesmo serviço aparece em várias ordens diferentes, isso é uma relação N:N entre OrdemDeServico e Servico, que precisa de uma tabela associativa.

Todo esse modelo deve ser implementado com ORM (models, sessões e queries), e a criação/evolução das tabelas deve ser controlada por migrações versionadas, nada de alterar o banco na mão.

Quem pode fazer o quê

A API precisa de autenticação com JWT e três perfis de acesso, cada um com permissões diferentes nos mesmos endpoints:

• Dono (admin): acesso total, cadastra mecânicos, clientes, serviços e vê todas as ordens.
• Mecânico: só vê e atualiza as ordens de serviço atribuídas a ele.
• Cliente: só consegue consultar o status das ordens dos próprios veículos, sem editar nada.

Isso exige autorização por escopo nos endpoints protegidos: a mesma rota de "listar ordens de serviço" deve devolver resultados diferentes dependendo de quem está autenticado.

Requisitos de rotas

• Rotas para clientes, veículos, serviços e ordens de serviço, usando parâmetros de URL (ex: buscar veículo por id), query params (ex: filtrar ordens por status) e corpo de requisição (ex: criar uma nova ordem).
• Respostas customizadas com status codes corretos (201 ao criar, 404 quando não encontra, 403 quando o perfil não tem permissão etc.).
• Lógica repetida entre rotas (como "pegar o usuário autenticado" ou "verificar se o veículo pertence ao cliente logado") deve ser extraída em dependências reutilizáveis, não copiada e colada em cada endpoint.
• Erros da API (validação, autenticação, não encontrado) devem passar por um tratamento centralizado, sempre devolvendo o mesmo formato padronizado de resposta de erro.
• CORS deve estar configurado para liberar só as origens que vão consumir a API (o futuro painel web e o app do cliente).
• A API deve gerar documentação interativa automaticamente, para o próprio Seu Renato conseguir testar as rotas sem precisar de Postman.

Rodando e publicando a oficina

Toda a aplicação (API + banco PostgreSQL) deve rodar via Docker Compose, subindo os dois serviços juntos localmente com um único comando. Para o ambiente de produção, a oficina real vai rodar numa VPS, com Nginx como proxy reverso na frente da aplicação e um gerenciador de processo garantindo que a API reinicie sozinha se cair.

Garantindo que nada quebre

Escreva testes de integração que simulem requisições reais contra os endpoints principais: criar uma ordem de serviço, tentar acessar uma ordem de outro cliente (deve barrar), e mudar o status de uma ordem como mecânico. Os testes devem cobrir tanto os casos de sucesso quanto os de permissão negada.

Conceitos técnicos praticados

• Roteamento avançado: parâmetros de URL, query, corpo de requisição, respostas customizadas e status codes.
• Injeção de dependências: reutilização de lógica de autenticação e permissão entre rotas.
• ORM: models, sessões e queries para clientes, veículos, serviços e ordens.
• Migrações: controle de versão do esquema do banco.
• JWT: autenticação de dono, mecânicos e clientes.
• Autorização e escopos: permissões diferentes por perfil nos mesmos endpoints.
• Middlewares e CORS: segurança e liberação de origens da API.
• Tratamento centralizado de erros: padronização das respostas de exceção.
• Documentação automática: interface interativa para testar a API.
• Testes de integração: simulação de requisições reais nos endpoints.
• Docker e Docker Compose: containerização da API e do banco.
• Relacionamentos 1:N e N:N: cliente-veículo e ordem-serviço.
• Deploy em VPS com Nginx: proxy reverso e gerenciamento do processo em produção.

Para ir além

• Adicionar histórico de preços dos serviços ao longo do tempo.
• Criar um relatório de faturamento mensal por mecânico.
• Implementar renovação automática de token JWT antes de expirar.