# Cron e Tarefas Automatizadas (Fase 22.7)

Runbook para tarefas periódicas: verificação de pagamentos, conferência em lote e lembretes. A v1 concentra essas rotinas em `src/Admin/Controller/TarefasCronController.php`.

## Tarefas na v1

| Tarefa | Método | Descrição |
|--------|--------|-----------|
| Mercado Pago (cartão) | `checarPagamentoMercadoPago` | Pedidos do dia, status “aguardando”, pagamento cartão; consulta API MP por pagamentos aprovados e casa por valor + CPF. Aprova pedido e credita cliente. |
| PIX (OpenPix) | `checarPedidosPix` | Pedidos PIX com `numero_transacao` (últimos 2 dias); consulta OpenPix por charge; COMPLETED → aprova e credita; EXPIRED → cancela. |
| PagSeguro | `checarPedidosPagSeguro` | Pedidos com `numero_transacao` (últimos 5 dias); consulta API PagSeguro; status 3 → aprova e credita; 4/6/7 → cancela. |

## Como executar na v1

A aplicação legada é acionada por URL (front controller). Exemplo de base: `https://seu-dominio.com/index.php` (ou raiz com rewrite).

- **Mercado Pago:**  
  `GET https://seu-dominio.com/index.php?m=admin&c=TarefasCron&a=checarPagamentoMercadoPago`
- **PIX (OpenPix):**  
  `GET https://seu-dominio.com/index.php?m=admin&c=TarefasCron&a=checarPedidosPix`
- **PagSeguro:**  
  `GET https://seu-dominio.com/index.php?m=admin&c=TarefasCron&a=checarPedidosPagSeguro`

Recomendação: proteger essas URLs (ex.: query string com token secreto ou IP restrito), pois hoje não exigem autenticação.

## Script para cron (v1)

O script `scripts/cron-verificar-pagamentos.sh` chama as três rotinas acima via `curl`. Configure `BASE_URL` (e opcionalmente `CRON_SECRET`) antes de usar.

```bash
# Exemplo crontab (a cada 10 min)
*/10 * * * * CRON_SECRET=seu_token BASE_URL=https://seu-dominio.com /path/to/scripts/cron-verificar-pagamentos.sh
```

## API v2 e webhooks

A API v2 já cobre parte do fluxo por **webhooks** (sem necessidade de cron para esses casos):

- **Gerencianet (PIX):** `POST /api/v2/webhooks/gerencianet` — notificação push; aprovação ao receber `paid`.
- **Mercado Pago:** `GET/POST /api/v2/webhooks/mercadopago` — notificação por `topic=payment`; aprovação quando status `approved`.

Quando os gateways notificam em tempo real, o cron de “checagem” v1 pode ser usado apenas como **fallback** (ex.: uma vez por hora ou em horários definidos).

## Conferência em lote e lembretes

- **Conferência em lote:** hoje feita sob demanda (admin) ou ao acessar resultado. Um cron poderia chamar o fluxo de conferência por concurso (ex.: endpoint interno ou script que invoque `ConcursoController`/lógica equivalente). Ainda não há endpoint v2 dedicado; usar fluxo v1 se necessário.
- **Lembretes:** (ex.: pedidos pendentes, sorteios próximos) não estão implementados no `TarefasCronController`. Podem ser adicionados como novos métodos ou jobs separados (e-mail/notificação).

## Checklist operação

- [ ] Definir frequência de cada cron (ex.: MP/PagSeguro a cada 10–15 min; PIX a cada 5 min).
- [ ] Proteger URLs v1 com token ou acesso restrito.
- [ ] Garantir timezone do servidor (ex.: `America/Sao_Paulo`) para filtros de data.
- [ ] Logar saída dos crons (stdout/stderr) para diagnóstico.
- [ ] Manter credenciais (MP, PagSeguro, OpenPix) em config/env; não commitar tokens.

## Referências

- `src/Admin/Controller/TarefasCronController.php`
- `docs/v2/webhooks-pagamento.md`
- `api/src/Controller/WebhookGerencianetController.php`
- `api/src/Controller/WebhookMercadoPagoController.php`