# Runbook — Tarefas Cron (Fase 23.2) Tarefas automatizadas para operação da Lotérica Premiada. Podem ser executadas via API v2 (com token) ou via v1 legado. --- ## Autenticação API v2 (cron) Endpoints sob `/api/v2/cron/*` exigem header: - `Authorization: Bearer ` ou - `X-Cron-Token: ` Configure `CRON_SECRET` no `.env` da API (valor longo e aleatório). Exemplo no servidor: ```bash # Executar conferência em lote (v2) curl -X POST "https://seu-dominio.com/api/v2/cron/conferencia-lote" \ -H "Authorization: Bearer SEU_CRON_SECRET" \ -H "Content-Type: application/json" \ -d '{"id_concurso": 123}' ``` --- ## 1. Conferência de resultados (conferência em lote) **Objetivo:** Conferir bolões de um ou mais concursos após o sorteio (atualizar premiação, notificar premiados). **Via API v2 (recomendado):** - `POST /api/v2/cron/conferencia-lote` Body (opcional): `{ "id_concurso": 123 }` — se omitir, processa concursos com resultado cadastrado e bolões não conferidos. - Resposta: `{ "success": true, "concursos_processados": 1, "detalhes": [...] }` **Agendamento sugerido (cron):** Após a divulgação do resultado pela Caixa (ex.: diariamente às 21h ou conforme sorteios). ```cron 0 21 * * * curl -s -X POST "https://seu-dominio.com/api/v2/cron/conferencia-lote" -H "Authorization: Bearer $CRON_SECRET" -H "Content-Type: application/json" ``` **Alternativa (v1):** A lógica de conferência é a mesma; a API v2 reutiliza `ConcursoController` via `ConferenciaService`. Para chamar direto o v1, use a URL interna do módulo Admin (se existir rota de conferência em lote). --- ## 2. Checagem de pagamentos (Mercado Pago, PagSeguro, PIX) **Objetivo:** Atualizar status de pedidos de crédito (aprovar/cancelar) conforme retorno dos gateways. **Via v1 (atual):** O controller `src/Admin/Controller/TarefasCronController.php` contém: - `checarPagamentoMercadoPago()` — pedidos com cartão MP - `checarPedidosPix()` — PIX (ex.: OpenPix) - `checarPedidosPagSeguro()` — PagSeguro **Como executar:** Ajustar no v1 a URL de cada action (ex.: `/admin/cron/checar-pagamento-mp`) e chamar via cron ou agendador. Exemplo genérico (substituir BASE pela URL base do site v1 e garantir sessão admin ou restrição por IP): ```cron */15 * * * * curl -s "https://seu-dominio.com/?m=admin&c=TarefasCron&a=checarPagamentoMercadoPago" -H "Cookie: PHPSESSID=..." */10 * * * * curl -s "https://seu-dominio.com/?m=admin&c=TarefasCron&a=checarPedidosPix" */15 * * * * curl -s "https://seu-dominio.com/?m=admin&c=TarefasCron&a=checarPedidosPagSeguro" ``` **Via API v2 (Fase 28.2):** O endpoint `POST /api/v2/cron/checar-pagamentos` existe e exige `CRON_SECRET`. Por enquanto ele retorna instruções para usar o v1; quando a lógica for migrada para a v2, o mesmo endpoint passará a executar a checagem. ```bash curl -X POST "https://seu-dominio.com/api/v2/cron/checar-pagamentos" \ -H "Authorization: Bearer $CRON_SECRET" \ -H "Content-Type: application/json" \ -d '{"gateway": "all"}' ``` **Segurança v1:** Restringir acesso por IP (firewall/reverse proxy) ou usar autenticação admin (sessão) se a rota exigir. **Futuro:** Migrar as ações do TarefasCronController para a API v2 (CronController::checarPagamentos executar a lógica com os mesmos DAOs). --- ## 2.1 PIX esquecidos (Fase 35.4) **Objetivo:** Cancelar pedidos PIX que ficaram aguardando pagamento há mais de 48h (sem `numero_transacao`). Reduz pedidos órfãos. **Via API v2:** - `POST /api/v2/cron/pix-esquecidos` Body (opcional): `{ "horas_limite": 48 }` — padrão 48h; máximo 168h. - Resposta: `{ "success": true, "cancelados": N, "ids": [...], "erros": [...] }` ```bash curl -X POST "https://seu-dominio.com/api/v2/cron/pix-esquecidos" \ -H "Authorization: Bearer $CRON_SECRET" \ -H "Content-Type: application/json" \ -d '{"horas_limite": 48}' ``` **Agendamento sugerido:** Diariamente (ex.: 6h da manhã). ```cron 0 6 * * * curl -s -X POST "https://seu-dominio.com/api/v2/cron/pix-esquecidos" -H "Authorization: Bearer $CRON_SECRET" -H "Content-Type: application/json" ``` --- ## 3. Notificação de premiados **Objetivo:** Enviar e-mail (e push, se configurado) aos clientes premiados após a conferência. **Via API v2:** - Após rodar `POST /api/v2/cron/conferencia-lote`, pode-se chamar por concurso: - `POST /api/v2/conferencia/{id}/notificar` (requer sessão admin ou endpoint cron dedicado). **Inclusão no cron v2:** O endpoint `conferencia-lote` pode, por parâmetro, disparar notificações após conferir (ver implementação em `CronController`). --- ## 4. Envio de lembretes (Fase 41.4) **Objetivo:** Enviar e-mail e push para clientes com lembrete ativo quando o sorteio está dentro de X horas (ex.: 24h antes). **Via API v2:** - `POST /api/v2/cron/lembretes-sorteio` - Resposta: `{ "success": true, "enviados_email": N, "enviados_push": N, "lembretes_processados": N, "erros": [...] }` - Respeita preferências de comunicação (ClientePreferenciaComunicacaoCoreDAO) para e-mail e push. ```bash curl -X POST "https://seu-dominio.com/api/v2/cron/lembretes-sorteio" \ -H "Authorization: Bearer $CRON_SECRET" \ -H "Content-Type: application/json" ``` **Agendamento sugerido:** A cada hora (para capturar janelas de "X horas antes" do sorteio). ```cron 0 * * * * curl -s -X POST "https://seu-dominio.com/api/v2/cron/lembretes-sorteio" -H "Authorization: Bearer $CRON_SECRET" -H "Content-Type: application/json" ``` --- ## Resumo rápido | Tarefa | Onde executar | Frequência sugerida | |---------------------|----------------------|------------------------| | Conferência lote | API v2 /cron/conferencia-lote | Diária (após sorteios) | | Checar pagamentos | v1 TarefasCronController | A cada 10–15 min | | PIX esquecidos | API v2 /cron/pix-esquecidos | Diária (ex.: 6h) | | Notificar premiados | API v2 /conferencia/{id}/notificar ou no lote | Após conferência | | Lembretes sorteio | API v2 /cron/lembretes-sorteio | A cada hora | --- ## Variáveis de ambiente (API v2) - `CRON_SECRET`: token secreto para chamar `/api/v2/cron/*`. Gerar com `openssl rand -hex 32`.