# Cron operacional e notificacoes

## Objetivo
Este documento resume como ativar e operar o cron do sistema para manter notificacoes, mailbox, performance, KPI e alertas de metas, tarefas e financeiro funcionando de forma recorrente.

## Pre-requisitos
- Configurar `APP_CRON_TOKEN` no ambiente da aplicacao.
- Garantir acesso HTTP ao projeto para o agendador externo.
- Rodar os SQLs necessarios antes de ativar em producao:
  - obrigatorio: `sql/2026-04-13-create-metas-alert-dispatches.sql`
  - obrigatorio: `sql/2026-04-13-create-tarefas-alert-dispatches.sql`
  - obrigatorio: `sql/2026-04-13-create-finance-alert-dispatches.sql`
  - obrigatorio para lembretes: `sql/2026-04-14-create-app-reminders.sql`
  - opcional: `sql/2026-04-13-seed-metas-alertas-padrao.sql`

## Formas de execucao

### 1. Endpoint de API
Rotas reescritas pelo `.htaccess` para `api_v3.php`.

Exemplos:
- `GET /adm/api/Cron/run?token=SEU_TOKEN&scope=daily`
- `GET /adm/api/Cron/run?token=SEU_TOKEN&scope=hourly`
- `GET /adm/api/Cron/run?token=SEU_TOKEN&scope=hourly&id_contrato=123`

Tambem e aceito o header `X-App-Cron-Token`.

Escopos atuais:
- `daily`: KPI diario, sync diario de performance, alertas de metas e alertas financeiros
- `hourly`: sync de mailbox, alertas de metas, alertas de vencimento de tarefas e disparo de lembretes operacionais

### 2. Runner interno
Endpoint:
- `GET /tools/cron-runner.php?token=SEU_TOKEN`

Esse fluxo usa o `CronKernel` e executa apenas tarefas vencidas conforme `frequency` e `min_interval`.

Tarefas registradas hoje:
- `kpi_daily_snapshot`
- `performance_daily_sync`
- `mailbox_sync`
- `metas_alerts`
- `tasks_due_soon`
- `finance_alerts`
- `reminders_due`

## Recomendacao de agendamento
- Rodar `tools/cron-runner.php` a cada 15 minutos.
- Rodar `scope=daily` uma vez por dia, preferencialmente entre `05:00` e `07:00`.
- Se o volume de mailbox for alto, monitorar o tempo da chamada `hourly` e dividir por contrato, se necessario.

Exemplo de agenda externa:

```text
*/15 * * * * https://seu-dominio.com.br/tools/cron-runner.php?token=SEU_TOKEN
0 6 * * * https://seu-dominio.com.br/adm/api/Cron/run?token=SEU_TOKEN&scope=daily
```

## O que esperar dos alertas
- Metas: respeitam janela de repeticao e assinatura de estado em `wpjy_metas_alert_dispatches`.
- Tarefas: alertam vencimento proximo para responsavel e atribuidos, com deduplicacao em `wpjy_tarefas_alert_dispatches`.
- Financeiro: alerta faturas vencidas e assinaturas proximas do vencimento, com deduplicacao em `wpjy_fin_notification_dispatches`.
- Lembretes: notificam eventos operacionais agendados em `wpjy_app_reminders`, com status local do lembrete e entrega pela central de notificacoes.
- Mailbox: notifica novas mensagens para usuarios vinculados a contas sincronizadas.
- Performance: badges e risco operacional sao avaliados no sync diario.

## Checklist de ativacao
1. Rodar os SQLs obrigatorios.
2. Confirmar `APP_CRON_TOKEN` no ambiente.
3. Testar manualmente `scope=hourly` e `scope=daily`.
4. Verificar insercoes em `wpjy_app_notifications` e nos logs de canal.
5. So depois disso habilitar o agendamento externo definitivo.

## Testes manuais sugeridos
- Criar uma meta com alerta ativo e executar `scope=hourly`.
- Criar uma tarefa com `data_fim_prevista` para hoje ou amanha e executar `scope=hourly`.
- Criar uma fatura `pending` com `due_date` anterior a hoje e executar `scope=daily`.
- Criar uma assinatura `active` com `next_due_date` para os proximos 7 dias e executar `scope=daily`.
- Criar um lembrete com `remind_at` para os proximos minutos e executar `scope=hourly`.
- Sincronizar uma conta de mailbox com nova mensagem pendente.
- Conferir a central de notificacoes e os canais em `wpjy_app_notification_channels`.