Solucao de Problemas Levy Cover

Esta pagina cobre os modos de falha mais comuns do Levy Cover e como diagnostica-los. A maioria dos problemas cai em um de quatro baldes: configuracao, falha da seguradora, lacunas de webhook ou desvio contabil.

Cartao opt-in nunca aparece no desbloqueio

Sintoma: Ciclista desbloqueia um veiculo, nenhum cartao Levy Cover aparece, a viagem prossegue sem uma oferta.

Causas mais provaveis (em ordem):

1. Toggle de subconta desligado. Verifique /dashboard/insurance/settings. Confirme que o Levy Cover esta ativado para a subconta.
2. Jurisdicao nao coberta. O local de desbloqueio resolve para uma regiao marcada como available: false na matriz. Veja Matriz de Jurisdicao. Verifique /api/admin/insurance/jurisdiction-matrix para o estado atual da matriz.
3. Credenciais da seguradora ausentes. CoverGeniusClient lanca CarrierNotConfiguredError. Em producao isso esconde o cartao completamente. Confirme que COVER_GENIUS_API_KEY e COVER_GENIUS_PARTNER_ID estao definidos no ambiente implantado.
4. Seguradora nao retornou niveis. A seguradora pode recusar oferecer cobertura em perfis de risco especificos (por ex. um ciclista novo sem historico em uma zona de alto risco). Verifique a resposta de cotacao em logs.
5. Cotacao expirou. O orcamento de 2 segundos no desbloqueio expirou. A viagem prossegue sem a oferta, que e o comportamento de falha aberta pretendido.
6. Preferencia do ciclista definida como "sempre recusar". Se o ciclista alternou a preferencia persistente para desligada, o cartao fica oculto ate que ele a reabilite.

Consultas diagnosticas:

• SELECT * FROM insurance_offerings WHERE subaccount_id = '<id>' - confirmar linhas habilitadas.
• SELECT * FROM ride_insurance_policies WHERE ride_id = '<ride id>' - confirmar se uma cotacao/vinculo realmente aconteceu.
• Logs: pesquisar eventos quote.requested e quote.failed em torno do timestamp de desbloqueio.

Vinculacao retornou 200 mas sem apolice no DB

Sintoma: Logs mostram uma chamada POST /bookings bem-sucedida, mas ride_insurance_policies nao tem linha.

Causas provaveis:

1. URL de webhook nao registrada. Algumas integracoes da seguradora confirmam a vinculacao via webhook booking.confirmed de entrada. Se esse webhook nunca chegar, a Levy registra a solicitacao como em voo indefinidamente.
2. Assinatura de webhook falhou. O evento chegou mas signature_verified = false. Verifique insurance_webhook_log.
3. A vinculacao foi bem-sucedida na seguradora mas o payload de resposta estava malformado. Raro; geralmente um problema apenas de sandbox.

Correcao: Execute o cron de reconciliacao da seguradora manualmente:

curl -X POST https://fleets.levyelectric.com/api/cron/insurance-carrier-reconciliation

O cron verifica apolices vinculadas contra a seguradora e repara carimbos de seguro de viagem ausentes. Se a seguradora reportar a apolice como valida, a linha e criada com bound_at retroativo ao tempo de vinculacao original.

Premio nao no recibo da viagem

Sintoma: O ciclista optou, a apolice foi vinculada, mas o recibo nao mostra o item de linha Levy Cover.

Causas:

1. applyRideInsuranceToPricing nao foi chamado. Verifique se src/lib/rides/process-ride-completion.ts e o caminho que a conclusao tomou. Os caminhos mobile-end, admin-force-end, internal-ride-end e auto-end todos aplicam este helper - se um novo caminho de fim de viagem foi adicionado, ele tambem deve aplicar o helper.
2. A vinculacao aconteceu mas a seguradora invalidou a apolice antes do fim da viagem. Verifique ride_insurance_policies.voided_at. Se definido, o premio foi corretamente excluido do recibo.
3. Cobranca Stripe Connect falhou. O premio e parte do total da viagem; se o total falhou ao cobrar, nenhum item de linha e gerado. Tentativa padrao de pagamento se aplica.

Diagnostico: SELECT id, total_cost, insurance_premium_amount FROM rides WHERE id = '<ride>'. Se insurance_premium_amount esta populado mas total_cost nao o inclui, o pipeline de conclusao nao aplicou o helper.

Fotos de sinistro falham ao carregar

Sintoma: Ciclista tenta carregar uma foto na tela de sinistro, o upload da erro.

Causas:

1. Bucket de armazenamento insurance-claims ausente. Confirme que o bucket existe com politicas de upload + leitura do ciclista e politica de gerenciamento de papel de servico. A migracao 20270601120100_09_* o cria.
2. URL assinada expirou. URLs assinadas para upload de foto tem um TTL curto. Se o ciclista sentou na tela por muito tempo, a URL expira. O aplicativo deve buscar novamente automaticamente; se nao, reinicie o fluxo de sinistro.
3. Tamanho ou tipo de arquivo rejeitado. A politica do bucket restringe a tipos MIME de imagem ate 25 MB por arquivo.

Sinistro travado em submitted por dias

Sintoma: Um sinistro e apresentado, o operador o ve na lista, mas ele nunca se move para under_review ou alem.

Causas:

1. Webhook perdido. A seguradora moveu o sinistro mas o webhook nunca alcancou a Levy. Verifique insurance_webhook_log para quaisquer entregas falhadas em torno do tempo de mudanca de status esperada.
2. Atraso do avaliador do lado da seguradora. A Cover Genius tipicamente revisa dentro de 48-72 horas. Slice pode levar mais tempo em algumas jurisdicoes.
3. Informacoes necessarias ausentes. Algumas seguradoras enviam um webhook claim.requires_info que solicita dados adicionais. Verifique o detalhe do sinistro para uma nota "seguradora solicitando".

Acao: Operadores podem escalar para o suporte Levy, que pode perseguir a seguradora atraves do canal do parceiro. Operadores nao podem apresentar apelacoes ou consultas de status diretamente com a seguradora.

Falhas de assinatura de webhook

Sintoma: insurance_webhook_log mostra signature_verified = false.

Causas:

1. Incompatibilidade de COVER_GENIUS_WEBHOOK_SECRET. Mais comum. Busque novamente o segredo atual do portal Cover Genius e atualize a variavel de ambiente.
2. A URL de webhook do ambiente errado esta registrada. Eventos sandbox chegando no endpoint de producao, ou vice-versa. Registre novamente a URL correta no portal da seguradora.
3. Replay ou entrega fora de ordem. O tratamento de chave duplicada em UNIQUE (carrier, event_id) retorna { duplicate: true }. Falhas genuinas de assinatura sao diferentes do tratamento de duplicatas - verifique o campo signature_verified da linha.

Falha da seguradora

Sintoma: Chamadas de cotacao expiram, chamadas de vinculacao retornam 5xx, o cartao opt-in para de aparecer.

Comportamento:

• Cotacoes expiram -> falha aberta, viagem prossegue sem oferta, insurance_offered = false.
• Apolices vinculadas existentes permanecem validas. A seguradora ainda as honra quando sinistros sao eventualmente apresentados.
• Sinistros pendentes ficam em seu status atual ate que a seguradora se recupere e os processe.

Acao:

• Confirme a falha na pagina de status da Cover Genius ou via canal do parceiro.
• Comunique aos operadores afetados se a falha exceder 1 hora.
• Nao vincule apolices manualmente durante a falha. Nao ha caminho para fazer isso com seguranca - se a seguradora nao recebeu de fato a vinculacao, a viagem nao esta segurada.

Premio cobrado mas o ciclista afirma que nao optou

Sintoma: Ticket de suporte do ciclista diz "Eu nao optei pelo seguro mas fui cobrado."

Diagnostico:

• Verifique ride_insurance_policies para a viagem. Se uma linha existe com um timestamp bound_at, um evento de opt-in foi registrado.
• Verifique o campo policy_wording_version para o texto que o ciclista viu.
• Verifique a preferencia persistente do ciclista - "Lembrar minha escolha" definido como aceitar significa que viagens futuras vinculam automaticamente.

Resolucao:

• Se o ciclista genuinamente nao optou (um bug de UI ou uma preferencia de inclusao automatica desatualizada), siga o caminho de reembolso de premio. Veja Reembolsos de Premio via Viagem.
• Se o ciclista optou mas esqueceu - o texto era claro e o carimbo de vinculacao esta intacto - explique o item de linha do recibo e o toggle de preferencia. Sem reembolso.

Testes estao falhando

A suite de testes completa esta em src/lib/insurance/__tests__/. Existem 8 arquivos e 36 testes. Para executa-los:

npx vitest run src/lib/insurance/__tests__/ src/lib/rides/__tests__/durable-completion-jobs.test.ts

Falhas comuns:

• Vars de ambiente definidas durante execucoes de teste. Se o ambiente de teste tem COVER_GENIUS_API_KEY definido, o registro pode escolher o cliente real em vez do mock. Use setCarrierRegistryForTests para fixar.
• Desvio de migracao. Se um desenvolvedor edita os arquivos de migracao localmente, os fixtures de teste podem se desviar do esquema. Redefina o DB local e execute novamente.

---