# ÁQUILA ORCHESTRATOR - Documentação Técnica

O **ÁQUILA ORCHESTRATOR** é o núcleo operacional (cérebro) do ÁQUILA Control Center. Ele não possui interface gráfica própria; sua função é coordenar toda a comunicação entre os módulos do sistema de forma assíncrona, desacoplada e resiliente.

## 1. Arquitetura

O Orchestrator é construído sobre 8 pilares principais:

1. **Event Bus**: Barramento interno para publicação e escuta de eventos do sistema (ex: `CLIENT_CREATED`, `PAYMENT_RECEIVED`).
2. **Queue System**: Sistema de filas para execução assíncrona de tarefas, com suporte a prioridades, retentativas e delays.
3. **Coordinators (Orquestradores)**: Classes responsáveis por intermediar a comunicação com serviços específicos (StreamCore, CRM, WhatsApp, PixGateway, Apps).
4. **Scheduler**: Gerenciador de tarefas agendadas (cron-like).
5. **Notification Service**: Centralizador de envios de mensagens (WhatsApp, Telegram, Email, Painel, Push).
6. **Audit Service**: Registro de todas as ações executadas no sistema (quem, quando, onde, resultado).
7. **Configuration & Feature Flags**: Centralização de configurações e controle de ativação/desativação de módulos em tempo real.
8. **Health Monitor**: Monitoramento contínuo da saúde dos serviços internos e externos.

---

## 2. Event Bus (Eventos do Sistema)

Todo acontecimento relevante no sistema gera um evento. Outros módulos podem "escutar" esses eventos para tomar ações.

### Eventos Disponíveis

| Evento | Descrição | Payload (exemplo) |
|--------|-----------|-------------------|
| `CLIENT_CREATED` | Novo cliente cadastrado no CRM | `job_id`, `name`, `phone` |
| `CLIENT_UPDATED` | Dados do cliente alterados | `job_id`, `client_id`, `fields_updated` |
| `LINE_CREATED` | Nova linha criada no StreamCore | `job_id`, `username`, `client_id` |
| `LINE_RENEWED` | Linha renovada no StreamCore | `job_id`, `line_id`, `plan_id` |
| `LINE_SUSPENDED` | Linha suspensa | `job_id`, `line_id`, `reason` |
| `LINE_DELETED` | Linha excluída | `line_id` |
| `PAYMENT_RECEIVED` | Pagamento confirmado | `job_id`, `client_id`, `amount`, `method` |
| `PIX_GENERATED` | Cobrança PIX gerada | `job_id`, `client_id`, `amount` |
| `PIX_PAID` | Webhook de PIX pago recebido | `transaction_id`, `amount`, `client_id` |
| `TEST_CREATED` | Linha de teste gerada | `job_id`, `client_id` |
| `MESSAGE_RECEIVED` | Mensagem recebida no WhatsApp | `phone`, `message`, `type` |
| `MESSAGE_SENT` | Mensagem enviada via WhatsApp | `job_id`, `phone`, `type` |
| `APP_UPDATED` | Nova versão de app liberada | `platform`, `version`, `force_update` |
| `TICKET_OPENED` | Novo ticket de suporte criado | `job_id`, `client_id`, `subject` |
| `SESSION_ESCALATED`| Atendimento transferido para humano | `phone`, `operator_id` |
| `CONFIG_CHANGED` | Configuração alterada no painel | `key`, `group` |
| `FEATURE_TOGGLED` | Feature flag ativada/desativada | `flag`, `enabled` |
| `HEALTH_CHECK_FAILED`| Serviço detectado como offline | `service`, `error` |

### Exemplo de Uso (Publicar)
```php
$eventBus->emit(Event::PAYMENT_RECEIVED, [
    'client_id' => 123,
    'amount' => 50.00,
    'method' => 'pix'
]);
```

### Exemplo de Uso (Escutar)
```php
$eventBus->on(Event::PAYMENT_RECEIVED, function(Event $event) {
    $payload = $event->getPayload();
    // Lógica para renovar a linha...
});
```

---

## 3. Queue System (Filas)

Todas as operações demoradas ou que dependem de APIs externas (StreamCore, WhatsApp, PIX) são enviadas para uma fila e processadas assincronamente por um `QueueWorker`.

### Status de um Job
- `pending`: Aguardando execução
- `processing`: Em execução neste momento
- `completed`: Executado com sucesso
- `failed`: Falhou definitivamente (excedeu tentativas)

### Exemplo de Uso
```php
$jobId = $queue->push('whatsapp', [
    'type' => 'whatsapp_send_text',
    'phone' => '5511999999999',
    'message' => 'Sua fatura vence amanhã.'
], priority: 10, delaySeconds: 0);
```

---

## 4. Coordinators (Orquestradores)

Os Coordinators abstraem a complexidade de interagir com os módulos específicos.

### StreamCoreCoordinator
- `createUser(array $data)`
- `renewUser(string $lineId, int $planId)`
- `suspendUser(string $lineId, string $reason)`
- `deleteUser(string $lineId)`
- `createTest(array $data)`

### CRMCoordinator
- `createClient(array $data)`
- `updateClient(int $clientId, array $data)`
- `registerPayment(int $clientId, array $paymentData)`
- `registerRenewal(int $clientId, array $renewalData)`
- `createTicket(int $clientId, array $ticketData)`

### WhatsAppCoordinator
- `sendMessage(string $phone, string $message)`
- `scheduleMessage(string $phone, string $message, string $scheduledAt)`
- `transferToHuman(string $phone, int $operatorId)`
- `sendFile()`, `sendImage()`, `sendQrCode()`

### PixGatewayCoordinator
- `generateCharge(array $chargeData)`
- `processWebhook(array $webhookData)`
- `confirmPayment(string $transactionId)`

### AppsCoordinator
- `sendDns(int $clientId, string $platform, string $dnsUrl)`
- `sendMessage(int $clientId, string $platform, string $title, string $body)`
- `sendVersionUpdate(string $platform, string $version, string $downloadUrl)`
- `broadcastToAll(string $title, string $message)`

---

## 5. Scheduler (Tarefas Agendadas)

Gerencia a execução de tarefas periódicas. Usa sintaxe Cron.

**Tarefas Padrão Registradas:**
- Verificar clientes vencendo (`0 8 * * *`)
- Verificar clientes vencidos (`0 9 * * *`)
- Limpar filas antigas (`0 3 * * *`)
- Health check geral (`*/5 * * * *`)
- Sincronizar cache TMDB (`0 2 * * *`)

---

## 6. Notification Service

Centraliza o envio de mensagens. Se o cliente tiver preferência por Telegram em vez de WhatsApp, o sistema ajusta automaticamente.

```php
// Envia para o WhatsApp
$notification->sendWhatsApp('5511999999999', 'Olá!');

// Envia para múltiplos canais ao mesmo tempo
$notification->broadcast('user_123', 'Aviso', 'Manutenção programada hoje.');
```

---

## 7. Audit Service

Mantém um log inalterável de tudo que acontece no sistema.

```php
$audit->log('streamcore.renew_user', ['line_id' => '123', 'plan_id' => 2], [
    'user_id' => 1,
    'ip' => '192.168.1.1'
]);
```

---

## 8. Feature Flags

Permite ligar/desligar partes do sistema instantaneamente, sem deploy.

**Flags Padrão:**
- `ai_core` (Inteligência Artificial)
- `pix_gateway` (Pagamentos PIX)
- `tmdb` (Integração TMDB)
- `auto_renewal` (Renovação Automática)
- `lg_app`, `samsung_app`, `roku_app`

```php
if ($featureFlags->isEnabled('tmdb')) {
    // Busca capa do filme no TMDB
}
```

---

## 9. Health Monitor

Monitora a saúde dos serviços a cada 5 minutos.

**Serviços Monitorados:**
- Banco de Dados MySQL
- API StreamCore
- API TMDB
- API WhatsApp
- API Gateway PIX
- Servidor SMTP
- Servidor DNS
- APIs de Aplicativos

Se um serviço ficar offline (status `down`), o evento `HEALTH_CHECK_FAILED` é disparado, permitindo que o sistema alerte os administradores via Telegram/WhatsApp.