# Daily Task Engine

This document covers the automatic daily plan that generates micro tasks for each operator using dynamic rules.

## Components

| Service/Job | Purpose |
|-------------|---------|
| `DailyIndicatorService` | Consolidates indicators per operator (meta diária, ticket médio por cliente, taxa de conversão, produção do dia). |
| `DailyTaskRuleEngine` | Reads the rule in category `motor_diario`, evaluates formulas and builds the plan. |
| `DailyTaskService` | Generates the micro-task sets at 01h, refreshes progress during the day and handles metadata. |
| `automation.php` jobs | `daily.tasks.generate` and `daily.tasks.refresh` run from cron. |
| Dashboard (`Minhas Tarefas`) | Displays the daily plan, indicators and progress for the current operator. |

## Indicators

`DailyIndicatorService::collect()` receives a reference date and returns, per operator:

- `meta_diaria`: daily target calculated from the monthly goal (fallback auto-distribution if not assigned).
- `ticket_medio`: average disbursed amount per unique client (last 30 days, fallback R$ 10.000,00).
- `taxa_conversao`: budgets sent vs proposals digitadas (histórico `orcamento_enviado` / `proposta_digitada`, fallback 10%).
- `orcamentos_dia`, `propostas_digitadas_dia`, `valor_dia`: metrics for the current business day.
- Bookkeeping data (meta mensal, produção acumulada, flags indicando fallback).

All calculations respect only business days (segunda a sexta) and consider the configured timezone (`config/timezone`).

## Rule payload (`motor_diario`)

Example:

```json
{
  "horario_execucao": "07:00",
  "reset_diario": true,
  "tarefas": [
    {
      "tipo": "enviar_orcamento",
      "formula": "(meta_diaria / ticket_medio) / taxa_conversao",
      "descricao": "Enviar {resultado} orçamentos para alcançar R$ {meta_diaria}",
      "arredondar": "cima"
    },
    {
      "tipo": "digitar_contrato",
      "formula": "(meta_diaria / ticket_medio)",
      "descricao": "Digitar pelo menos {resultado} contratos",
      "arredondar": "cima"
    }
  ]
}
```

Variables available in the formulas:

- `meta_diaria`, `meta_mensal`, `valor_realizado`
- `ticket_medio`
- `taxa_conversao` (0–1) and `taxa_conversao_percent`
- `orcamentos_dia`, `propostas_digitadas_dia`
- `valor_dia`

Descriptions support placeholders such as `{resultado}`, `{meta_diaria}`, `{ticket_medio}`.

## Job scheduling

| Hora        | Job                    | Observações                                                         |
|-------------|------------------------|---------------------------------------------------------------------|
| 01:00 (seg–sex) | `daily.tasks.generate` | Gera tarefas do dia, expira conjuntos anteriores, usa os indicadores coletados. |
| 09:00–18:00 (seg–sex, a cada 30 min) | `daily.tasks.refresh` | Recalcula produção parcial, atualiza status/progresso das tarefas. |

Implementation in cron (exemplo Linux):

```bash
0 1 * * 1-5  php /var/www/app/automation.php queue daily.tasks.generate
*/30 9-18 * * 1-5 php /var/www/app/automation.php queue daily.tasks.refresh
*/5 * * * *      php /var/www/app/automation.php run
```

> O runner (`automation.php run`) pode continuar no intervalo padrão de 5 minutos ou conforme sua infraestrutura.

## Persistência

Tarefas diárias utilizam `micro_task_sets`/`micro_tasks` com os seguintes metadados:

- `metadata.origin = "daily_rule"`
- `metadata.reference_date = "YYYY-MM-DD"`
- Cada tarefa mantém `target_quantity`, `metric_key`, `round_mode` e a última medição (`last_actual`).

As rotinas de geração/refresh removem conjuntos anteriores do dia, criam os novos e atualizam a barra de progresso (status `pending`, `in_progress`, `completed`).

## Interface do operador

O painel **Minhas Tarefas** exibe:

- Cartão “Plano diário” com resumo de indicadores (meta, ticket médio, taxa de conversão, produção do dia).
- Tabela com tarefas planejadas, meta x realizado, status e porcentagem concluída.
- Conjuntos tradicionais e alertas permanecem disponíveis logo abaixo.

## Requisitos de dados

- O histórico do lead (`lead_histories`) precisa registrar `orcamento_enviado` e `proposta_digitada` para alimentar a taxa de conversão.
- A meta mensal de cada operador deve estar configurada em `sales_goals` (ou redistribuição automática será aplicada).

## Operações diárias

1. Confirmar que o cron das 01h executou (`automation_job_logs`) e que novos conjuntos foram criados para o dia.
2. Monitorar o cron de refresh; verificar se as tarefas mudam de status conforme a produção real.
3. Se ajustes forem necessários, o time de negócio pode editar a regra `motor_diario` no painel ou via `storage/rules.json`.

## Falhas e troubleshooting

- Checar `storage/logs/rules.log` para fórmulas inválidas ou variáveis desconhecidas.
- Conferir `automation_job_logs` em caso de job travado.
- Verificar se o timezone e os dias úteis estão corretos (configuração afeta o cálculo da meta diária).