# ÁQUILA CONTROL CENTER - Fluxo MVP

Este documento descreve a implementação do primeiro fluxo funcional completo (MVP) do sistema. O objetivo deste fluxo é demonstrar a orquestração ponta a ponta, desde o recebimento de uma mensagem do cliente até a resposta final, passando por IA, CRM, StreamCore, PIX e Dashboard.

A arquitetura foi implementada de forma estritamente desacoplada, utilizando **Interfaces** e **Injeção de Dependência**, garantindo que nenhum módulo conheça a implementação concreta do outro.

---

## 1. Arquitetura de Contratos (Interfaces)

Para garantir o desacoplamento, foram criadas as seguintes interfaces no diretório `app/Contracts/`:

| Interface | Responsabilidade |
|-----------|------------------|
| `AIProviderInterface` | Detecção de intenção, geração de resposta e decisão de escalação. |
| `WhatsAppProviderInterface` | Envio de mensagens, normalização de webhooks e status de conexão. |
| `StreamCoreInterface` | Criação de testes, vendas, renovações e consultas de status no painel IPTV. |
| `PaymentGatewayInterface` | Geração de cobranças PIX, validação de webhooks e consulta de status. |
| `CRMInterface` | Gestão de clientes, registro de interações, eventos e histórico financeiro. |
| `DashboardInterface` | Registro e incremento de métricas operacionais. |

Todas as implementações concretas atuais (Mocks) implementam estas interfaces, permitindo substituição futura por integrações reais sem alterar a lógica de negócio.

---

## 2. O Orquestrador (FlowOrchestrator)

O coração do fluxo é a classe `FlowOrchestrator`. Ela recebe as 6 interfaces injetadas no construtor via `ServiceContainer` e coordena o fluxo em 8 etapas síncronas:

1. **Normalização:** Recebe o payload do WhatsApp e valida os dados básicos.
2. **CRM (Cliente):** Busca o cliente pelo telefone. Se não existir, cria um novo registro. Registra a interação de entrada.
3. **IA (Intenção):** Envia a mensagem para o motor de IA detectar a intenção (ex: `test_request`, `renewal_request`).
4. **Escalação:** Verifica se a IA tem baixa confiança. Se sim, transfere para um humano imediatamente.
5. **Ação:** Executa a lógica de negócio correspondente à intenção (ex: criar linha no StreamCore ou gerar PIX).
6. **IA (Resposta):** Pede para a IA gerar a resposta final formatada com os dados da ação (ex: usuário/senha ou código PIX).
7. **WhatsApp:** Envia a resposta gerada de volta para o cliente. Registra a interação de saída no CRM.
8. **Dashboard:** Incrementa as métricas de negócio (`messages_received`, `intents_detected`, `tests_created`, etc.).

---

## 3. Intenções Suportadas

O `MockAIProvider` (motor de regras baseado em palavras-chave) detecta as seguintes intenções:

| Intenção | Gatilhos (Exemplos) | Ação Executada |
|----------|---------------------|----------------|
| `test_request` | "Quero testar", "Teste grátis" | StreamCore cria linha de 24h. |
| `renewal_request` | "Quero renovar", "Pagar" | Gateway PIX gera cobrança de R$ 35,00. |
| `purchase_request` | "Quero comprar", "Assinar" | Exibe planos e gera PIX. |
| `support_request` | "App não abre", "Travando" | CRM abre ticket de suporte. |
| `status_query` | "Meu status", "Quando vence" | StreamCore consulta status da linha. |
| `expired_access` | "Meu acesso venceu" | Oferece renovação e gera PIX. |
| `greeting` | "Olá", "Bom dia" | Retorna menu de opções. |

---

## 4. Testes e Simulação

Foram implementadas ferramentas para testar o fluxo sem necessidade de um servidor web ou integrações reais.

### CLI Runner (Demonstração)
Um script de linha de comando permite testar mensagens individuais ou rodar uma demonstração completa de todas as intenções.

```bash
# Testar mensagem específica
php bin/run_flow.php "Quero testar"

# Rodar demonstração completa (todas as intenções)
php bin/run_flow.php --demo
```

### Testes Automatizados (PHPUnit/Custom)
Uma suíte de testes de integração (`FlowOrchestratorTest`) cobre todos os cenários possíveis, validando se os Mocks registram as ações corretamente.

```bash
# Executar os 26 testes de integração
php bin/run_tests.php
```

---

## 5. Próximos Passos

Como a arquitetura de interfaces já está validada pelo MVP, o próximo passo natural é substituir os Mocks por integrações reais:

1. Substituir `MockWhatsAppProvider` pela integração real com a **Evolution API**.
2. Substituir `MockAIProvider` pela integração real com a **OpenAI (GPT-4)**.
3. Substituir `MockStreamCore` por chamadas HTTP para o **painel real**.
4. Mover a execução do fluxo para o sistema de **Filas (QueueService)** para processamento assíncrono.

## Auditoria e correções - versão revisada

- Corrigido `WhatsAppMessage` que estava com bloco PHP incompleto.
- Removida a dependência obrigatória de `mbstring` no motor de regras de teste; há fallback seguro para ambientes sem a extensão.
- Adicionada abstração `PanelProviderInterface` para permitir múltiplos painéis.
- Adicionado adaptador configurável para QPanel.
- Adicionado `PanelRegistry` e `PanelCoordinator` para seleção de painel por conexão.
- Endpoints QPanel não são tratados como universais: devem ser confirmados para a instalação/versão real antes de produção.
- Credenciais devem ficar em ambiente/secret manager, nunca hardcoded.