Troubleshooting de Ordens de Servico

Quando algo parece errado no quadro de ordens de servico, a causa quase sempre cai em um dos padroes abaixo. Percorra esta lista antes de abrir um chamado de suporte.

Uma task esta travada em Created e a regra deveria te-la criado

Tres coisas para checar:

1. A regra esta ativa? Abra /dashboard/task-rules e confirme que o toggle esta ligado. Regras desativadas nao disparam.
2. O cron rodou de fato? Olhe a entrada mais recente da regra em task_rule_runs. Se for mais antiga que o schedule, o cron nao disparou - cheque vercel.json para a config do cron e sua pagina de deployments na Vercel por falhas.
3. A regra casou com zero veiculos? Aperte o botao Test. Se o dry-run retorna zero matches, sua config de trigger esta apertada demais.

O veiculo nao virou para maintenance quando criei uma task critica

Duas causas:

• Corrida ativa - O trigger de auto-flip recusa interromper uma corrida. Se vehicles.status = 'in_use', a virada espera o fim. A task e criada normalmente; o veiculo so vai para maintenance quando a corrida fechar.
• Priority abaixo de high - Apenas high e critical disparam o flip. Se voce setou medium, o veiculo continua disponivel.

Um tecnico diz que nao consegue tocar em Start

O botao Start exige foto. O tecnico precisa capturar ou anexar uma foto before primeiro. Se ele esta tocando em modo offline, o upload da foto pode estar enfileirado - ele precisa ver a foto na secao "Photos" do task detail antes do botao ativar.

Se ele tem foto anexada e o botao continua cinza, cheque:

• Ele e o assignee atual? Se um manager reatribuiu a task sem o tecnico saber, so o novo assignee pode apertar Start.
• A task esta em assigned? Se esta created (sem assignee), o botao fica escondido.

Um tecnico tentou Resolve e recebeu "already closed by ___"

Essa e a resolucao de conflito da fila offline. O tecnico resolveu offline, mas o manager forcou close no servidor primeiro. O cliente ve 409 no sync e mostra a mensagem. As fotos do tecnico continuam salvas na task fechada (cliente vence em fotos e notas), entao nenhuma evidencia se perde.

O botao Verify esta cinza para um manager

Dois motivos:

1. A task nao esta em resolved - verify exige resolve antes. A state machine recusa pular.
2. O papel do manager esta errado - so ops_manager e lead_tech podem verificar. Um tech ou junior_tech comum nao consegue, nem no proprio trabalho.

Tasks duplicadas no mesmo veiculo

O sistema bloqueia duplicatas do mesmo task_type, nao entre types. Entao um veiculo pode ter um repair aberto, um battery_swap aberto e um cleaning aberto ao mesmo tempo. E intencional.

Se voce ve duplicatas do mesmo type, cheque:

• Uma esta verified mas nao closed - tasks verified contam como fechadas para deduplicacao. Se voce ve as duas, refresh; uma esta a caminho de closed.
• Uma regra disparou antes da task existente carregar - race condition, muito rara. Feche a duplicata manualmente.

Tasks nao estao sendo auto-atribuidas por proximidade

assign_by_proximity le users.last_lat e users.last_lng para escolher o tecnico mais proximo. Duas coisas para checar:

1. Seus tecnicos estao compartilhando localizacao? O operator-app faz POST em /api/operator/location a cada poucos minutos quando em foreground. Se um tecnico esta com Location Services desligado, ele e invisivel para proximity assignment.
2. As colunas estao preenchidas? Query SELECT last_lat, last_lng, last_lat_at FROM users WHERE id IN (your tech IDs). Se last_lat_at for mais antigo que uma hora, esse tecnico nao sera escolhido.

O fallback quando nenhum tecnico esta no raio e deixar a task sem assignee (Created) para qualquer tecnico pegar.

Um vendor nao esta recebendo o email do magic link

Tres coisas para checar:

1. Entrega de email - emails de magic link saem pela Resend. Cheque o dashboard da Resend por status de entrega e bounces.
2. Linha do vendor sem email - vendors.contact_email e o destino. Se for NULL, nenhum email e enviado.
3. Token ja usado - magic links sao tokens de 7 dias, um por task. Se o vendor ja aceitou, o link nao e mais "novo" - ele deveria favoritar a URL apos o primeiro acesso.

Fotos nao sobem do operator-app

Fotos ficam em cache local primeiro em ${FileSystem.documentDirectory}task-photos/<task_id>/ e sobem na reconexao. Se um tecnico relata "fotos travadas":

1. Cheque a barra de progresso de upload na tela de detalhe da task
2. Force um sync por Settings -> Sync Pending Items no operator-app
3. Se falhar, cheque as permissoes Supabase Storage do aparelho - o bucket task-photos exige upload autenticado

O fallback e o tecnico mandar as fotos por SMS ao ops manager, que anexa pelo dashboard.

"Cannot create task - duplicate" da API

O POST em /api/tasks retorna 200 com skipped_duplicate: true quando existe uma task aberta do mesmo type. Isso e feature, nao bug. Para criar uma segunda task contra o mesmo veiculo:

• Feche a primeira, ou
• Use outro task_type, ou
• Espere a primeira ficar verified (que conta como fechada para dedup)

Notificacoes de breach de SLA estao barulhentas

Tres botoes:

1. Afrouxar SLAs low/medium - se low esta em 24h e voce tem 200 tasks de baixa priority, voce vai entrar muito em breach. Defaults sao 7 dias para low, 72h para medium.
2. Desligar Slack em regras de baixa priority - em regras que nao merecem Slack, set action_config.notify_slack: false.
3. Esperar o batching - Expo push agrupa breaches em digests no limite de 5-em-10-minutos. Slack nao agrupa.