Solucao de Problemas

A checklist canonica para quando algo no stack de compliance nao esta se comportando. Percorre endpoints MDS, o ingester de Policy, enforcement em tempo real, o portal da cidade e e-mails de digest -- nessa ordem, porque essa e aproximadamente a cadeia de dependencias.

Endpoints MDS

401 em toda requisicao

Sintomas: validador da cidade retorna 401 Unauthorized em /vehicles/status.

Verificacoes:

1. O token bearer esta ausente de Authorization: Bearer <token>. Cidades as vezes colam o token sem o prefixo Bearer .
2. O token foi revogado. Abra Configuracoes -> API e Integracoes -> Tokens MDS e confirme que o token esta ativo.
3. O token pertence a uma subconta diferente. Um token por subconta; cidades testando acidentalmente em multiplas jurisdicoes verao isso.

Validador falha no campo version

Sintomas: mds-provider-validator reclama que o envelope de resposta reporta uma versao diferente de 2.0.1.

Verificacoes: confirme que src/lib/mds/v2/response.ts tem const MDS_VERSION = '2.0.1'. Se voce fez deploy de um build velho, redeploye.

Header MDS-JWT ausente em uma resposta

Sintomas: a cidade espera que toda resposta carregue MDS-JWT: <jwt> e o header esta ausente.

Verificacoes:

1. mds_jwks_keys nao tem linha com is_active = true para a subconta. Acesse /api/mds/<subaccountId>/.well-known/jwks.json uma vez para forcar um lazy mint, depois tente novamente.
2. O par de chaves foi gerado mas a linha ativa tem private_key_pem corrompido (raro -- geralmente uma edicao manual mal feita). Olhe no Sentry por breadcrumbs MDS sign failed.

current_speed_limit_kph sempre 0

Sintomas: veiculos reportam current_speed_limit_kph: 0 mesmo quando deveriam estar em uma zona.

Verificacoes:

1. O veiculo nao tem posicao GPS conhecida. Inspecione vehicles.last_lat/last_lng e vehicles.last_seen.
2. Nenhuma zona de operador ou geofence de politica contem o ponto. Execute SELECT * FROM zones_containing_point('<subaccountId>', <lat>, <lng>) e confirme que pelo menos uma linha e retornada.
3. O rule_type da regra ativa e no_ride em vez de speed -- isso e um bloqueio, nao um limite de velocidade. A linha de status deve mostrar is_disabled = true em vez.

Ingester de Policy

Feed de politica da cidade retorna 404

Sintomas: entradas de log de auditoria com status = 'failed' e errors contendo HTTP 404.

Verificacoes:

1. A URL em mds_jurisdictions.policy_feed_url esta errada. Teste do seu terminal: curl -i <url>. Cidades as vezes mudam caminhos entre endpoints provisorios e producao.
2. O token de auth expirou. Tente com e sem token para isolar.

Feed valida mas nao produz policy_geofences

Sintomas: auditoria mostra status = 'success' e linhas mds_policies existem, mas policy_geofences esta vazio.

Verificacoes:

1. Toda regra referenciou geografias que a cidade nao publicou. Inspecione errors na linha de auditoria -- IDs de geografia nao resolvidos estao listados la.
2. A cidade publicou politicas para um tipo de veiculo que sua frota nao opera. Confirme que os vehicle_types das regras incluem pelo menos um tipo que voce tem.

A mesma politica continua aparecendo em cada diff

Sintomas: o diff de cada poll mostra a mesma politica em modified, mesmo quando nada significativo mudou.

Verificacoes:

1. A cidade esta regenerando o payload do feed em cada requisicao (diferente published_date, whitespace, ordenacao). O atalho sha256 dispara apenas em payloads byte-identicos. Peca a cidade para estabilizar sua serializacao.
2. A cidade muda published_date automaticamente -- alguns CMSes fazem isso. O diff e inofensivo mas ruidoso; pode ser filtrado na UI do log de auditoria.

Ativacao nunca dispara

Sintomas: uma politica esta pending, start_date passou, mas o status nunca vira active.

Verificacoes:

1. O cron mds-policy-activate esta falhando. Verifique /api/cron/mds-policy-activate nos logs de cron do Vercel.
2. O start_date esta no horario local da cidade mas armazenado como UTC sem conversao. O cron compara contra now() UTC; um fuso mal definido no feed faz ativacao disparar muito mais tarde do que o esperado.

Enforcement em tempo real

Regra ativada mas nenhum comando enviado

Sintomas: mds_policies.status = 'active' mas policy_enforcement_events tem zero linhas para a regra.

Verificacoes:

1. Nenhum veiculo esta dentro da geometria. SELECT COUNT(*) FROM vehicles WHERE ST_Contains('<rule_geometry>', ...) -- se zero, nao ha nada para aplicar.
2. Todos os veiculos tem GPS velho (>5 min). O skip e por design. Procure por eventos error = 'stale_gps' na tabela.
3. Os veiculos nao tem linha iot_devices ligada. Pulados com error = 'no_iot_device'.

Comandos enviados mas veiculos nao reduzem velocidade

Sintomas: policy_enforcement_events mostra command_sent_at mas nenhum command_ack_at, e o veiculo continua em velocidade total.

Verificacoes:

1. OEM offline ou adormecido. Abra o veiculo no dashboard e inspecione last_seen.
2. O formato de comando errado chegou ao OEM. Inspecione command_response para um codigo de erro -- a maioria dos OEMs retorna codigos de rejeicao em texto plano.
3. A senha IoT do veiculo esta errada. Confirme que iot_devices.iot_password corresponde ao que o OEM espera (veja Integracao OKAI, Integracao Queclink, etc.).

Sub-frota ve comandos, outra sub-frota nao

Sintomas: veiculos OKAI obedecem a slow zone, veiculos Segway nao (ou vice-versa).

Verificacoes:

1. O ramo do despachador especifico do OEM esta ausente ou velho para o OEM. Confirme que src/lib/iot/dispatch.ts tem um case para esse OEM e o formato de comando corresponde a versao do protocolo do OEM.
2. Latencia Segway BLE-relay -- o comando foi enviado mas ainda nao confirmado porque o veiculo esta longe de qualquer telefone. Esta e uma lacuna conhecida; latencia para Segway pode exceder 30 segundos.

Portal da cidade

Magic link retorna "token invalido"

Sintomas: contato clica no link enviado e cai em uma pagina de erro.

Verificacoes:

1. O token expirou (15 minutos). Pecam para solicitarem um novo.
2. A linha do contato foi deletada ou portal_access = false.
3. Dois links foram gerados em sucessao rapida; o primeiro consumido, o segundo parece velho.

E-mail de magic link nunca chega

Sintomas: contato envia o formulario, ve a mensagem "verifique seu e-mail", nenhum e-mail chega.

Verificacoes:

1. Pasta de spam.
2. O e-mail nao corresponde a uma linha city_contacts exatamente (insensivel a caixa). Inspecione a linha.
3. A infra de e-mail rejeitou o envio (Sentry tera o bounce). Procure por gatilhos de filtro de spam no assunto ou corpo.

Portal nao mostra veiculos mesmo com frota implantada

Sintomas: contato municipal faz login, o mapa de frota esta vazio.

Verificacoes:

1. mds_jurisdictions.bbox esta errado -- muito apertado ou apontando para outro lugar. Confirme contra uma previa do mapa.
2. Todos os veiculos tem last_lat/last_lng nulos. Inspecione pelo menos um.

E-mails de digest

Digest nao chegou no dia esperado

Sintomas: contato municipal esperava um digest semanal de segunda, nao recebeu.

Verificacoes:

1. last_digest_sent_at esta na semana atual -- o cron decidiu que a janela de cadencia nao tinha expirado. Provavelmente um digest anterior disparou na mesma janela.
2. O cron nao rodou. Logs de cron do Vercel para /api/cron/compliance-digest.
3. O digest disparou mas o envio de e-mail deu erro. Verifique city_compliance_reports -- se a linha existe mas nenhum e-mail chegou, a falha e a jusante.

Digest mostra uma condicao falhando que voce ja consertou

Sintomas: scoreboard no digest mostra vermelho em complaint_sla mesmo que todas as reclamacoes tenham sido respondidas.

Verificacoes:

1. O digest cobre um periodo fechado (ontem para diario, semana passada para semanal). Nao recomputara retroativamente. O scoreboard atual em /dashboard/compliance/{id} e a visao ao vivo.

Anexo PDF ausente em digest mensal

Sintomas: digest mensal chega mas pdf_url e null e o anexo esta ausente.

Verificacoes:

1. O renderizador PDF deu erro. Sentry tera o stack trace. O corpo HTML/texto ainda dispara; o PDF e best-effort.

Onde procurar no banco de dados

Quando tudo mais falha

Envie e-mail para support@levyelectric.com com:

• ID da subconta
• Slug da jurisdicao
• O run_id de auditoria se o problema esta no ingester
• O policy_enforcement_events.id se o problema esta em enforcement
• O city_compliance_reports.id se o problema esta em um digest

Temos acesso direto aos logs e geralmente podemos localizar a falha em uma hora.