# Fase 1 - Fundamentos do Modulo de Metas

## Modulo 1.1 - Modelagem de Dados Basica

### Visao Geral

Objetivo: suportar um catalogo flexivel de metas e indicadores que possam ser atribuados a organizacao, brokers ou vendedores individuais, guardando valores diarios por colaborador.

### Modelo Entidade-Relacionamento (ASCII)

```
┌────────────────────┐        ┌───────────────────────┐
│   goal_indicators  │1──────*│ goal_indicator_values │
└────────────────────┘        └───────────────────────┘
        ▲                              ▲
        │                              │
        │                              │
        │                              │
        │                              │
        │                ┌────────────────────────────┐
        │                │        advanced_goals       │
        │                └────────────────────────────┘
        │                              │
        │                              │ owner_type / owner_id
        │                              ▼
        │                      ┌──────────────┐
        └──────────────────────┤    users     │
                               └──────────────┘
```

- `goal_indicator_values.goal_id` permanece opcional para permitir captura de indicadores antes mesmo de vincular uma meta especifica.

### Campos Principais

- `advanced_goals`: tipo (`goal_type`), periodicidade, modo de alvo (`target_mode`), valor alvo padrao, janela movel (`rolling_window_days`), status.
- `goal_indicators`: `slug`, `name`, descricao, formula, peso, unidade, flag de ativo.
- `goal_indicator_values`: referencia ao indicador, vendedor (`user_id`), valor diario (`captured_on`), deltas e metadados.

### Fluxo de Dados

1. **Cadastro de Indicadores**: administradores mantem a tabela `goal_indicators` (seed inicial + CRUD).
2. **Definicao de Metas**: metas avancadas sao registradas em `advanced_goals`, associando indicadores relevantes.
3. **Coleta/Atualizacao**: jobs diarios calculam valores por vendedor e salvam em `goal_indicator_values`.
4. **Historico**: dados acumulados alimentam dashboards e o motor de micro tarefas nas fases seguintes.

### Consideracoes

- Indices agilizam consultas por status, periodo e combinacao indicador/usuario/data.
- Campos `metadata` e `notes` guardam detalhes de calculo ou excecoes.
- Preparado para rotinas agendadas (cron/queue) e normalizacao historica.

## Modulo 1.2 - CRUD Administrativo

- Rotas `/goals` e `/goals/indicators` protegem operacoes exclusivas de administradores.
- `AdvancedGoalController` usa `GoalService` para criar/atualizar metas, atribuicoes e indicadores vinculados.
- Views `goals/index`, `goals/create` e `goals/edit` seguem o layout glassmorphism existente.

## Modulo 1.3 - Coleta de Dados

- `IndicatorCalculator` consolida dados de leads, propostas, historicos (`lead_histories`) e lembretes (`lead_reminders`).
- `IndicatorSnapshotService` grava agregados em `goal_indicator_values` com deltas frente ao alvo.
- Job `indicator.snapshot.daily` e `php automation.php schedule:daily` automatizam a captura.

## Fase 2 - Motor de Micro Tarefas

- `MicroTaskEngine` gera conjuntos (`micro_task_sets`) e tarefas (`micro_tasks`) com base na diferenca entre alvo e resultado atual.
- `MicroTaskController` permite operadores acompanhar, adicionar notas, registrar minutos e marcar status.
- `BadgeService` recalcula o progresso, finaliza conjuntos e dispara regras de selo automaticamente.

## Fase 3 - Selos, Bonificacoes e Relatorios

- `BadgeController` e `badges/index.php` cuidam do CRUD de selos.
- `user_badges` e `monthly_bonus_payouts` armazenam historico para dashboards e controle de pagamento.
- `governance_logs` registra alteracoes sensiveis (metas, indicadores, selos).

## Scheduler e Jobs

Consulte `docs/automation-scheduler.md` para configuracao do runner CLI (`automation.php`) e para as boas praticas de cron.