# A Bíblia da Plataforma UaiSat
**O Guia Definitivo e Absoluto de Operação, Engenharia e Integração**

> **Versão:** 2.0 (Edição Completa — Março 2026)
> **Classificação:** Confidencial / Operação Interna e Masters
> **Autor:** Engenharia UaiSat (Antigravity AI)

---

![Arquitetura da Plataforma](/docs/images/uaisat_architecture.png)
*Figura 1: Representação gráfica do tráfego das 4 plataformas isoladas no banco de dados centralizado.*

---

## Índice Analítico

1. [Introdução e Filosofia da Arquitetura](#cap1)
2. [Infraestrutura Multi-Tenant](#cap2)
3. [Plataforma Zeus — O Painel Master](#cap3)
4. [Plataforma Hermes — O CRM Comercial](#cap4)
5. [Plataforma Iris — A Gestão Operacional](#cap5)
6. [Plataforma Apollo — O App do Assinante](#cap6)
7. [Integrações com o Mundo Externo](#cap7)
   - 7.1. CSMVNO (Telecomunicações)
   - 7.2. Asaas Bank (Financeiro / PIX / Boleto)
   - 7.3. Evolution API (WhatsApp Automatizado)
   - 7.4. Firebase (Notificações Push & Autenticação)
   - 7.5. Correios / Rastreamento Logístico
8. [Banco de Dados — Dicionário de Variáveis](#cap8)
9. [Segurança e Controle de Acesso (ACL)](#cap9)
10. [Operações e Cronjobs Automatizados](#cap10)
11. [Guia de Deploy e Publicação](#cap11)
12. [Troubleshooting Central](#cap12)

---

<br/>

# <a name="cap1"></a>CAPÍTULO 1: Introdução e Filosofia da Arquitetura

O ecossistema **UaiSat CRM** não é um sistema único. É uma confederação de **4 portais especializados** que trocam informações com um único backend PHP centralizado em milissegundos. Internamente, chamamos essa arquitetura de **"A Trindade + 1"**.

## 1.1 O Problema Resolvido

O maior desafio da indústria MVNO (Mobile Virtual Network Operator) é a **gestão simultânea de múltiplas operadoras** com dados completamente isolados. Na UaiSat isso é garantido pelo isolamento **Multi-Tenant rigoroso no Backend**:

- **Tenant A** nunca enxergará os clientes do **Tenant B**
- Cada operadora tem seu banco de dados lógico (mesmo banco físico, schema separado por `tenant_id`)
- O Zeus é o único nó que enxerga todos os tenants simultaneamente

## 1.2 A Metáfora do Shopping

Imagine que você é o dono de um Shopping Center (Zeus). Dentro do shopping há múltiplas lojas (tenants). Cada loja:
- Tem seu próprio caixa e estoque (Hermes CRM)
- Tem sua própria vitrine (Iris — loja online)
- Emite seu próprio cartão de fidelidade (Apollo — app do cliente)

Mas **você, dono do shopping**, controla a infraestrutura elétrica (servidores), define quem pode abrir loja (KYC), cobra o aluguel mensal (licença), e monitora o fluxo de caixa de todos (Zeus Dashboard).

## 1.3 Diagrama Funcional Completo

```
                    ┌──────────────────────────────────┐
                    │          ZEUS MASTER              │
                    │     zeus.uaisat.app.br            │
                    │   Porta :5173 | Mode: master      │
                    └────────────┬─────────────────────┘
                                 │
              ┌──────────────────┼──────────────────────┐
              │                  │                       │
   ┌──────────▼──────┐  ┌───────▼─────────┐  ┌────────▼──────────┐
   │    HERMES CRM    │  │   IRIS GESTÃO   │  │   APOLLO APP      │
   │hermes.uaisat.app │  │ iris.uaisat.app │  │apollo.uaisat.app  │
   │  Porta :5174     │  │  Porta :5175    │  │  Porta :5176      │
   └──────────┬───────┘  └───────┬─────────┘  └────────┬──────────┘
              │                  │                       │
              └──────────────────┼───────────────────────┘
                                 │  /api-proxy (Vite Proxy)
                                 ▼
                       ┌─────────────────────┐
                       │       api.php        │
                       │   (Backend PHP)      │
                       │ uaisat.app.br/api/   │
                       └─────────┬────────────┘
                                 │
               ┌─────────────────┼─────────────────┐
               │                 │                  │
        ┌──────▼──────┐  ┌───────▼──────┐  ┌───────▼──────┐
        │  MySQL DB   │  │   Asaas API  │  │  CSMVNO API  │
        │   Online    │  │  (Pagamentos)│  │ (Telecom SF) │
        └─────────────┘  └──────────────┘  └──────────────┘
```

---

<br/>

# <a name="cap2"></a>CAPÍTULO 2: Infraestrutura Multi-Tenant

## 2.1 Como o Sistema Identifica a Operadora

A detecção do tenant ocorre em **3 camadas**:

### Camada 1 — DNS / Subdomínio
Quando alguém acessa `minha-operadora.hermes.uaisat.app.br`, o Apache lê o `Host` header e o proxy passa o subdomínio como `X-Tenant-Domain` para o PHP.

### Camada 2 — PHP Backend (api.php)
O `api.php` extrai o `X-Tenant-Domain`, busca na tabela `tenants` o registro correspondente e valida se está ativo (`is_active = 1`). **Todas as queries subsequentes são filtradas por `tenant_id`.**

### Camada 3 — Frontend React (TenantContext)
O `TenantContext.tsx` detecta o modo da aplicação pela **porta** em localhost:
- `:5173` → modo `master` (Zeus — nenhum filtro de tenant)
- `:5174` → modo `crm` (Hermes — filtra por tenant logado)
- `:5175` → modo `crm` (Iris — filtra por tenant logado)
- `:5176` → modo `crm` (Apollo — acesso do assinante)

Em produção, o modo é detectado pelo subdomínio configurado no banco.

## 2.2 Ciclo de Vida de um Novo Tenant

```
1. Zeus cria operadora → INSERT INTO tenants
2. Sistema gera slug único (ex: 'uaimovel')
3. DNS é configurado: uaimovel.hermes.uaisat.app.br → servidor
4. Tenant recebe credenciais iniciais via e-mail
5. Operadora acessa Hermes → configura branding, planos, gateway
6. KYC é aprovado pelo Zeus → is_active = 1
7. Loja Iris e App Apollo ficam disponíveis
```

## 2.3 Hierarquia de Usuários

```
Zeus Master (Nível 0 — UaiSat)
└── Tenant Admin (Nível 1 — Operadora)
    ├── Vendedor (Nível 2 — Equipe da Operadora)
    └── Assinante (Nível 3 — Cliente Final)
```

| Nível | Login em | Acesso |
|-------|----------|--------|
| Zeus Master | `zeus.uaisat.app.br` | Todos os tenants + configurações globais |
| Tenant Admin | `slug.hermes.uaisat.app.br` | Apenas seus clientes e configurações |
| Vendedor | Hermes (usuário limitado) | Clientes, vendas, sem financeiro |
| Assinante | `apollo.uaisat.app.br` | Apenas seus dados pessoais e faturas |

---

<br/>

# <a name="cap3"></a>CAPÍTULO 3: Plataforma Zeus — O Painel Master

![Zeus Dashboard](/docs/images/zeus_dashboard.png)
*Figura 2: Dashboard central do Zeus com KPIs financeiros globais e status de saúde das operadoras.*

O Zeus é o **centro de comando absoluto** do ecossistema. Somente a equipe UaiSat (master) acessa este painel.

## 3.1 Dashboard Principal

O dashboard exibe métricas em tempo real agregadas de **todos os tenants**:

| Métrica | Descrição | API Action |
|---------|-----------|-----------|
| Operadoras Ativas | Total de tenants com `is_active = 1` | `get_zeus_dashboard` |
| Total de Linhas | Soma de todos os simcards ativados | `get_zeus_dashboard` |
| Receita Global (MRR) | Faturamento agregado do mês | `get_zeus_dashboard` |
| Status do Servidor | CPU, memória, uptime | `get_system_diagnostics` |

O gráfico de crescimento mostra o comparativo de **Receita vs. Ativações** mês a mês.

## 3.2 Gestão de Operadoras (Tenants)

### Criar Nova Operadora
1. Zeus → Menu lateral → **"Lista de Operadoras"** → `+ Nova Operadora`
2. Preencher:
   - **Nome da Empresa:** Nome comercial (ex: "UaiMovel Telecom")
   - **Slug:** Identificador único do subdomínio (ex: `uaimovel`)
   - **CNPJ/CPF:** Documento da empresa
   - **E-mail de Acesso:** Login do administrador do tenant
   - **Senha Inicial:** Será exigida troca no primeiro acesso
3. Clicar em **"Criar Operadora"**

> [!NOTE]
> O campo **Slug** é permanente e define o subdomínio. Exemplo: slug = `minha-op` → acesso via `minha-op.hermes.uaisat.app.br`

### Editar Operadora Existente
Todos os 12 abas da tela de edição do tenant cobrem:
- **Básico** — nome, CNPJ, status (ativo/inativo/manutenção)
- **Branding** — logo, cores primárias/secundárias, favicon
- **Financeiro** — token Asaas, plano de licença
- **Planos** — quais planos do catálogo master está disponível para este tenant
- **Comunicação** — configurações SMTP, Evolution API (WhatsApp)
- **App Mobile** — configurações do Apollo
- **KYC** — documentos enviados para aprovação
- **Limites** — máximo de linhas, usuários, funcionalidades disponíveis
- **ACL** — permissões do administrador do tenant
- **Site/Loja** — configurações da Iris
- **Distribuição** — configurações de atacado e revenda
- **Histórico** — log de alterações

## 3.3 Financeiro Master

### Cobrança de Licenças (`tenants-billing`)
O Zeus cobra mensalmente de cada operadora uma **taxa de licença** baseada no número de linhas ativas e no plano contratado. O fluxo:

1. Cronjob executa `action=run_master_billing` no dia 1 de cada mês
2. Para cada tenant ativo, gera uma `charge` no Asaas com o valor da licença
3. Tenant recebe boleto/PIX por e-mail
4. Ao pagar, webhook do Asaas confirma e atualiza `license_paid = true`
5. Se não pagar em 5 dias, tenant entra em **modo suspensão parcial**
6. Se não pagar em 15 dias, tenant é **desativado automaticamente**

### Receita Global (`master-revenue`)
Visão consolidada de todas as receitas: 
- Licenças pagas pelos tenants
- Split de transações (taxa por ativação/recarga)
- Receitas de atacado

### Gateway Asaas Master (`master-asaas`)
Configuração da conta Asaas **da UaiSat** (a conta mãe). Diferente dos tokens Asaas de cada tenant (que são das contas deles).

## 3.4 Sistemas Master

### KYC — Aprovação de Novos Operadores
O processo de Know Your Customer verifica:
- Documentos da empresa (contrato social, CNPJ)
- Identidade dos sócios
- Comprovante de endereço comercial
- Declaração de conformidade com regulação ANATEL

Status possíveis: `pending_docs` → `under_review` → `approved` | `rejected`

### System Health (`master-health`)
A tela de System Health executa `get_system_diagnostics` e retorna:

| Diagnóstico | Como verificar |
|-------------|----------------|
| Versão PHP | `phpversion()` |
| Extensões ativas | `get_loaded_extensions()` |
| Limite de upload | `ini_get('upload_max_filesize')` |
| Memória disponível | `memory_get_usage()` |
| Tabelas do banco com problemas | `CHECK TABLE` em todas as tabelas |

**Auto Healing:** Clicar em "Corrigir Estrutura" executa `action=auto_repair_tables` que restaura colunas faltando sem perda de dados.

### Controle de Acesso — ACL Master (`master-acl`)
Gerencia quais usuários internos da UaiSat têm acesso ao Zeus e com quais permissões.

### Logs Globais (`logs`)
Auditoria completa de todas as ações realizadas em todos os tenants e no Zeus.

---

<br/>

# <a name="cap4"></a>CAPÍTULO 4: Plataforma Hermes — O CRM Comercial

![Interface do Hermes](/docs/images/hermes_crm.png)
*Figura 3: Hermes CRM em modo escuro mostrando a gestão de chips e clientes.*

O Hermes é o **coração operacional de cada operadora**. É aqui que o time da operadora gerencia seus clientes, chips, cobranças e tudo mais do dia a dia.

## 4.1 Dashboard do Tenant (Hermes)

O dashboard do Hermes exibe KPIs específicos da operadora logada:
- Total de clientes ativos
- Linhas ativas vs. suspensas
- Receita do mês (faturas pagas)
- Faturas vencidas (inadimplência)
- Alertas de chips sem ativação há mais de 7 dias

## 4.2 Gestão de Clientes

### Cadastrar Novo Cliente
1. Hermes → **"Clientes"** → `+ Novo Assinante`
2. Dados obrigatórios:
   - **Nome completo**
   - **CPF** — validado pelo algoritmo de dígito verificador
   - **E-mail**
   - **Telefone de contato**
3. Dados opcionais:
   - Endereço completo (para envio de chip físico)
   - Data de nascimento (para KYC simplificado)

### Detalhes do Cliente (`cliente-detalhes`)
A tela de detalhes é a mais completa do Hermes. Contém **12 abas**:

| Aba | Conteúdo |
|-----|----------|
| **Resumo** | Foto, dados básicos, status, links rápidos |
| **Linhas** | Todos os simcards do cliente (ICCID, status, plano) |
| **Faturas** | Histórico de cobranças e pagamentos (Asaas) |
| **Consumo** | Uso de dados/minutos por período (CSMVNO) |
| **Documentos** | Fotos de documentos enviados |
| **Histórico** | Línea do tempo de todas as ações |
| **WhatsApp** | Conversa direta via Evolution API |
| **Notas** | Anotações internas da equipe |
| **Portabilidade** | Status de portabilidade ativa |
| **Indicações** | Se indicou outros clientes (fidelidade) |
| **App** | Dispositivos registrados no Apollo |
| **Configurações** | Ações avançadas (cancelar, suspender, transferir) |

### Busca e Filtros Avançados
- Busca por CPF, nome, e-mail, telefone, ICCID
- Filtros: status (ativo, suspenso, cancelado), plano, data de cadastro
- Exportação: CSV, Excel, PDF

## 4.3 Estoque de Chips (SIM Cards)

### Importação em Massa (CSV)
1. Hermes → **"Estoque"** → `Importar CSV`
2. Baixar o modelo `.csv` com as colunas: `iccid, msisdn, status, batch_id`
3. Preencher e fazer upload
4. O sistema valida cada ICCID (começa com `8955...`) e insere em lotes de 50

### Status dos Chips

| Status | Significado |
|--------|-------------|
| `available` | No estoque, pronto para ativação |
| `reserved` | Reservado para pedido em andamento |
| `active` | Ativado em nome de um cliente |
| `suspended` | Linha suspensa por inadimplência |
| `cancelled` | Cancelado definitivamente |
| `returned` | Devolvido ao estoque master |

### Ativar Linha (Fluxo Completo)
```
1. Operador seleciona chip disponível (ICCID)
2. Vincula ao cliente cadastrado
3. Escolhe o plano de dados
4. Sistema gera cobrança no Asaas (PIX ou Boleto)
5. Cliente paga
6. Webhook Asaas → api.php confirma pagamento
7. api.php chama CSMVNO: "Ativar ICCID X no plano Y"
8. CSMVNO retorna confirmação em <30 segundos
9. Status do chip muda para 'active'
10. WhatsApp automático manda boas-vindas ao cliente
```

## 4.4 Gestão de Planos

A tela de **Planos** (`planos`) mostra apenas os planos que o Zeus liberou para esse tenant. O tenant pode:
- **Ativar/desativar** um plano sem deletar
- **Customizar o preço** de venda (desde acima do custo mínimo)
- **Criar combos** agrupando planos existentes

> [!IMPORTANT]
> O tenant **não cria planos** — apenas reusa os planos do catálogo Master (CSMVNO). Isso garante que 100% dos planos existem fisicamente no backend da operadora de telefonia.

## 4.5 Financeiro do Tenant

### Cobrança (`cobranca`)
Gestão de todas as faturas geradas para os clientes do tenant:
- Listar faturas por status (pendente, paga, vencida, cancelada)
- Gerar cobrança manual (PIX ou Boleto via Asaas)
- Reenviar cobrança por WhatsApp ou e-mail
- Cancelar cobrança

### Banco (`banco`)
Dashboard financeiro do tenant mostrando:
- Saldo disponível na conta Asaas
- Transferências realizadas
- Extrato de recebimentos

### ERP Financeiro (`erp-financeiro`)
Para operadoras com operação mais sofisticada: controle de contas a pagar, fluxo de caixa, DRE simplificado.

## 4.6 Serviços

### WhatsApp Chat (`chat`)
Integração com Evolution API para responder clientes diretamente pelo Hermes, sem sair da plataforma.

### Tickets de Suporte (`ticket-support`)
Sistema de help desk interno: registrar, categorizar e resolver chamados de clientes.

### Portabilidade (`portabilidade`)
Acompanhamento do processo de portabilidade numérica (DDD e número do cliente migrando para a operadora).

### Marketing AI (`marketing`)
Ferramenta de campanhas alimentada por Gemini AI:
- Segmentar base de clientes por critérios
- Redigir mensagem de campanha com IA
- Disparar via WhatsApp (Evolution) ou e-mail
- Acompanhar métricas de abertura e conversão

### Rastreamento/Logística (`tracking`)
Para operadoras que enviam chips físicos pelos Correios: tracking automático dos pedidos.

## 4.7 Site Institucional

### Editor de Conteúdo (`editor-site`)
O tenant pode editar o conteúdo da página de apresentação da operadora (hospedada na Iris):
- Textos do hero, benefícios, depoimentos
- Upload de imagens e banners
- Gerenciar planos exibidos no site

### Monitoramento do Site (`site-data`)
Analytics básicos: visitantes, cliques nos planos, taxa de conversão.

---

<br/>

# <a name="cap5"></a>CAPÍTULO 5: Plataforma Iris — A Gestão Operacional

A Iris é o **portal público** da operadora — é o que o cliente vê quando acessa o site da operadora para contratar um plano ou verificar cobertura.

## 5.1 Funcionalidades da Iris

| Funcionalidade | Descrição |
|----------------|-----------|
| Landing page dinâmica | Exibe branding e planos do tenant automaticamente |
| Mapa de cobertura | Integrado com dados TIM/Vivo |
| Contratação online | Cliente contrata plano, paga PIX e recebe confirmação |
| Recarga | Widget de recarga online |

## 5.2 Como a Iris se Diferencia de Tenant para Tenant

A Iris é um **único build** que se adapta dinamicamente:
1. Lê o subdomínio → busca o tenant no banco
2. Aplica as cores primárias e secundárias do tenant
3. Exibe apenas os planos ativados para aquele tenant
4. Usa o logo e o nome da empresa do tenant

---

<br/>

# <a name="cap6"></a>CAPÍTULO 6: Plataforma Apollo — O App do Assinante

![Aplicativo Mobile Apollo](/docs/images/apollo_app.png)
*Figura 4: Apollo rodando em Android exibindo consumo em tempo real e QR Code PIX para recarga.*

O Apollo é o **app móvel** que o cliente final do tenant usa para gerenciar sua linha. Construído com **React + Capacitor** para funcionar como app nativo em Android.

## 6.1 Funcionalidades do Apollo

| Funcionalidade | Descrição |
|----------------|-----------|
| Extrato de consumo | Dados, minutos e SMS do mês atual |
| 2ª via de fatura | Boleto / QR Code PIX |
| Recarga online | Compra créditos diretamente no app |
| Notificações Push | Alertas de fatura, promoções, baixo saldo |
| Chat com suporte | Abertura de ticket diretamente no app |
| Indicar amigos | Programa de indicação integrado |
| Planos disponíveis | Comparativo e upgrade/downgrade |

## 6.2 Push Notifications (FCM)

Quando o Apollo inicia, ele registra o dispositivo no Firebase:
1. App chama Firebase → recebe `FCM Token` (string de 144 chars)
2. Apollo envia para `api.php?action=register_device` com:
   - `fcm_token` 
   - `platform` (android/ios)
   - `device_info` (modelo, versão OS)
3. Backend guarda em `device_tokens` vinculado ao `customer_id`

Para enviar push:
```
POST api.php?action=send_push_notification
{
  "tenant_id": 5,
  "customer_ids": [123, 456], // ou null para todos
  "title": "Promoção Relâmpago!",
  "body": "Aproveite o plano 10GB por R$ 39,90 só hoje.",
  "data": { "redirect": "plans" }
}
```

## 6.3 Biometria e Autenticação

O Apollo usa **Firebase Auth** para login seguro:
- Login por CPF + senha
- Opção de biometria (FaceID/TouchID via Capacitor)
- Token de sessão renovado automaticamente a cada 24h

---

<br/>

# <a name="cap7"></a>CAPÍTULO 7: Integrações com o Mundo Externo

Para que o sistema seja **autônomo** — sem necessidade de intervenção manual para 90% das operações — existem 5 integrações ativas.

## 7.1 CSMVNO — Surf Telecom (Telecomunicações)

A UaiSat **não é uma operadora de telecomunicações**. Ela é um MVNO (Mobile Virtual Network Operator) que **aluga** a antena da Vivo/TIM através da **Surf Telecom (CSMVNO)**.

### Endpoints Principais

| Ação | API Action | Parâmetros |
|------|-----------|-----------|
| Ativar linha | `activate_line` | `iccid`, `plan_id`, `customer_cpf` |
| Suspender linha | `suspend_line` | `iccid` |
| Reativar linha | `reactivate_line` | `iccid` |
| Cancelar linha | `cancel_line` | `iccid` |
| Consultar consumo | `fetch_mobile_consumption` | `iccid`, `period` |
| Listar planos | `sync_csmvno_catalog` | `token` |
| Portabilidade | `request_portability` | `iccid`, `donor_operator`, `phone_number` |

### Tokens de Acesso

Existem **2 tokens** para o CSMVNO:
1. **Token Operacional** (`csmvno_token`) — usado no dia a dia para ativar/suspender linhas. Configurado por tenant.
2. **Token Master** (`csmvno_master_token`) — exclusivo do Zeus para sincronizar o catálogo de planos.

### Consumo em Tempo Real

O consumo (dados usados, minutos de ligação) é atualizado a cada **24 horas** via cronjob:
```
Cronjob: 00:30 diariamente
→ action=sync_all_consumption
→ Para cada linha ativa, chama CSMVNO
→ Atualiza tabela consumption_logs
→ Verifica se franquia está abaixo de 20% → dispara WhatsApp de aviso
```

## 7.2 Asaas Bank — Gateway de Pagamentos

O Asaas é o **cérebro financeiro** do ecossistema. A UaiSat nunca toca em dinheiro diretamente — o Asaas gerencia as carteiras de cada tenant.

### Arquitetura de Split

```
Cliente paga R$ 49,90 (Plano Giga)
        │
        ▼
Conta Asaas do Tenant (operadora)
        │
        ├─ R$ 45,00 → Fica no tenant (receita do plano)
        └─ R$ 4,90 → Split automático para conta UaiSat (taxa)
```

### Fluxo de Cobrança (PIX)

```
1. api.php → POST https://api.asaas.com/v3/payments
   Headers: access_token: $ASAAS_KEY
   Body: {
     customer: "cus_xxx",
     billingType: "PIX",
     value: 49.90,
     dueDate: "2026-03-10"
   }
2. Asaas retorna QR Code PIX (base64) + código copia-e-cola
3. Frontend exibe QR Code para o cliente
4. Cliente paga no banco
5. Asaas detecta pagamento → POST para nosso webhook:
   POST https://uaisat.app.br/api/api.php?action=asaas_webhook
   Body: { event: "PAYMENT_RECEIVED", payment: {...} }
6. api.php valida o `$_GET['asaas_secret']`
7. Atualiza fatura, reativa linha (se suspensa), envia WhatsApp
```

### Configuração por Tenant

Cada tenant configura seu próprio Asaas:
1. Hermes → **Configurações** → aba **Financeiro**
2. Colar "Chave API Asaas" (começa com `$aact_...`)
3. Definir "Ambiente" (Sandbox para testes, Produção para real)
4. Salvar → sistema testa automaticamente com uma chamada de validação

### Webhooks — Eventos Suportados

| Evento Asaas | Ação no Sistema |
|-------------|----------------|
| `PAYMENT_RECEIVED` | Marca fatura paga, reativa linha, envia WhatsApp |
| `PAYMENT_OVERDUE` | Muda status para `overdue`, envia lembrete |
| `PAYMENT_DELETED` | Cancela fatura no sistema |
| `PAYMENT_REFUNDED` | Registra estorno, suspende linha |

## 7.3 Evolution API — WhatsApp Automatizado

Cada tenant tem um **número de WhatsApp dedicado** conectado via Evolution API.

### Como Conectar

1. Hermes → Configurações → **WhatsApp**
2. Clicar em "Conectar WhatsApp"
3. Escanear QR Code com o celular que terá o número
4. O sistema salva o `instance_id` no banco do tenant
5. A partir deste momento, todos os disparos automáticos usam esse número

### Disparos Automáticos

| Gatilho | Mensagem Enviada |
|---------|-----------------|
| Nova ativação | Boas-vindas + dados da linha |
| Fatura gerada | "Sua fatura de R$ X vence em 5 dias" |
| Fatura 1 dia antes | Lembrete com PIX |
| Linha suspensa | "Sua linha está suspensa. Regularize:" + link boleto |
| Linha reativada | "Sua linha foi reativada. Aproveite!" |
| Consumo < 20% | "Você usou 80% da sua franquia de dados" |
| Promoção (manual) | Campanha configurada no Marketing |

### Templates de Mensagem

Templates podem ser personalizados em **Hermes → Notificações**. Variáveis disponíveis:

```
{nome_cliente} — Nome da pessoa
{valor_fatura} — R$ 49,90
{vencimento} — 10/03/2026
{link_pix} — Link copia-e-cola
{saldo_dados} — 3.2GB restantes
{nome_operadora} — Nome da empresa
```

## 7.4 Firebase — Notificações Push & Autenticação

### Configuração no Projeto

O Firebase é configurado em `src/lib/firebase.ts` e `src/main.tsx`:
```typescript
const firebaseConfig = {
  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
  authDomain: "...",
  projectId: "uaisat-crm",
  ...
};
```

### Dois Usos Distintos

1. **Firebase Auth** — login seguro no Apollo (app do cliente)
2. **FCM (Firebase Cloud Messaging)** — notificações push no Android

### Service Worker (sw.js)

O Apollo registra um Service Worker (`/sw.js`) que:
- Intercepta mensagens FCM mesmo com app fechado
- Exibe notificação nativa do Android
- Ao clicar na notificação, abre o Apollo na tela correta

## 7.5 Correios / Rastreamento Logístico

Para operadoras que enviam chips físicos (SIM Card) pelo correio:

### Configuração (ShippingConfigPage)
- Token da API do Melhor Envio
- Dimensões padrão do envelope (peso ~15g, 15x10x1cm)
- Calcular frete automaticamente pelo CEP do cliente

### Fluxo de Envio

```
1. Pedido criado na loja Iris
2. Sistema calcula frete → exibe para cliente
3. Cliente paga (inclui frete)
4. Operadora gera etiqueta automática (Melhor Envio)
5. Imprime e posta
6. Sistema registra código de rastreio
7. Atualizações automáticas: Postado → Em Trânsito → Saiu para Entrega → Entregue
8. Ao ser entregue, chip fica "pronto para ativação"
```

---

<br/>

# <a name="cap8"></a>CAPÍTULO 8: Banco de Dados — Dicionário de Variáveis

O banco é único (MySQL online no cPanel da Locaweb). Todas as tabelas usam `tenant_id` como chave de isolamento.

## 8.1 Tabela `tenants` — Operadoras

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | INT PK | ID único da operadora |
| `company_name` | VARCHAR | Nome da empresa |
| `slug` | VARCHAR UNIQUE | Identificador do subdomínio |
| `cnpj` | VARCHAR | CNPJ da empresa |
| `email` | VARCHAR | E-mail de acesso do admin |
| `password_hash` | VARCHAR | Senha criptografada |
| `is_active` | TINYINT | 1=ativo, 0=inativo |
| `app_mode` | ENUM | `master` ou `crm` |
| `logo_url` | VARCHAR | URL do logo |
| `primary_color` | VARCHAR | Cor hex (ex: #1A73E8) |
| `secondary_color` | VARCHAR | Cor hex secundária |
| `asaas_key` | TEXT (encrypted) | Token da conta Asaas do tenant |
| `asaas_environment` | ENUM | `sandbox` ou `production` |
| `csmvno_token` | TEXT (encrypted) | Token CSMVNO deste tenant |
| `whatsapp_key` | VARCHAR | Instance ID do Evolution |
| `evolution_url` | VARCHAR | URL base do servidor Evolution |
| `smtp_host` | VARCHAR | Servidor de e-mail |
| `smtp_user` | VARCHAR | Usuário SMTP |
| `smtp_pass` | TEXT (encrypted) | Senha SMTP |
| `plan_id` | INT | Plano de licença contratado |
| `license_paid` | TINYINT | Se a licença do mês está paga |
| `max_lines` | INT | Limite de ativações |
| `created_at` | TIMESTAMP | Data de cadastro |
| `updated_at` | TIMESTAMP | Última atualização |

## 8.2 Tabela `customers` — Clientes dos Tenants

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | INT PK | ID único do cliente |
| `tenant_id` | INT FK | Operadora proprietária |
| `full_name` | VARCHAR | Nome completo |
| `cpf` | VARCHAR | CPF (armazenado sem formatação) |
| `email` | VARCHAR | E-mail |
| `phone` | VARCHAR | Telefone com DDD |
| `birthdate` | DATE | Data de nascimento |
| `address_street` | VARCHAR | Logradouro |
| `address_number` | VARCHAR | Número |
| `address_complement` | VARCHAR | Complemento |
| `address_city` | VARCHAR | Cidade |
| `address_state` | CHAR(2) | UF |
| `address_zip` | VARCHAR | CEP |
| `asaas_customer_id` | VARCHAR | ID do cliente no Asaas |
| `status` | ENUM | `active`, `suspended`, `cancelled` |
| `kyc_status` | ENUM | `pending`, `approved`, `rejected` |
| `created_at` | TIMESTAMP | Data de cadastro |

## 8.3 Tabela `simcards` — Chips/SIM Cards

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | INT PK | ID interno |
| `tenant_id` | INT FK | Operadora dona do chip |
| `iccid` | VARCHAR UNIQUE | Número do chip (começa com 8955...) |
| `msisdn` | VARCHAR | Número de telefone (DDD + número) |
| `customer_id` | INT FK nullable | Cliente que usa este chip |
| `plan_id` | INT FK | Plano ativo |
| `status` | ENUM | `available`, `reserved`, `active`, `suspended`, `cancelled` |
| `activation_date` | DATE | Quando foi ativado |
| `batch_id` | VARCHAR | Lote de importação |
| `csmvno_sid` | VARCHAR | ID do chip no sistema CSMVNO |

## 8.4 Tabela `invoices` — Faturas

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | INT PK | ID da fatura |
| `tenant_id` | INT FK | Operadora |
| `customer_id` | INT FK | Cliente |
| `asaas_payment_id` | VARCHAR | ID do pagamento no Asaas |
| `amount` | DECIMAL(10,2) | Valor em reais |
| `type` | ENUM | `monthly`, `activation`, `recharge` |
| `billing_type` | ENUM | `PIX`, `BOLETO`, `CREDIT_CARD` |
| `status` | ENUM | `pending`, `paid`, `overdue`, `cancelled`, `refunded` |
| `due_date` | DATE | Data de vencimento |
| `paid_at` | TIMESTAMP | Data do pagamento |
| `pix_qrcode` | TEXT | QR Code PIX em base64 |
| `boleto_url` | VARCHAR | URL do boleto PDF |

## 8.5 Tabela `master_plans` — Catálogo de Planos

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | INT PK | ID do plano |
| `name` | VARCHAR | Nome (ex: "Plano Giga 10GB") |
| `data_mb` | INT | Franquia em MB |
| `sms_count` | INT | SMS inclusos (0 = ilimitado) |
| `voice_minutes` | INT | Minutos de voz (0 = ilimitado) |
| `cost_price` | DECIMAL(10,2) | Custo de atacado (UaiSat paga à CSMVNO) |
| `suggested_price` | DECIMAL(10,2) | Preço sugerido de venda |
| `csmvno_plan_id` | VARCHAR | ID do plano no sistema CSMVNO |
| `is_active` | TINYINT | 1=disponível para tenants |
| `validity_days` | INT | Validade do plano em dias |

## 8.6 Tabela `device_tokens` — Dispositivos Apollo

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | INT PK | ID |
| `tenant_id` | INT FK | Operadora |
| `customer_id` | INT FK | Cliente |
| `fcm_token` | TEXT | Token Firebase (144 chars) |
| `platform` | ENUM | `android`, `ios` |
| `device_model` | VARCHAR | Modelo do aparelho |
| `os_version` | VARCHAR | Versão do Android/iOS |
| `last_seen` | TIMESTAMP | Último acesso |

## 8.7 Tabela `audit_logs` — Auditoria

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | INT PK | ID |
| `tenant_id` | INT FK nullable | Null se ação do Zeus |
| `user_id` | VARCHAR | ID do usuário |
| `action` | VARCHAR | Ação realizada (ex: `customer.update`) |
| `details` | TEXT | Detalhes em JSON |
| `ip_address` | VARCHAR | IP de origem |
| `user_agent` | TEXT | Browser/app |
| `created_at` | TIMESTAMP | Quando ocorreu |

---

<br/>

# <a name="cap9"></a>CAPÍTULO 9: Segurança e Controle de Acesso (ACL)

## 9.1 Camadas de Segurança

### Camada 1 — API Secret
Todo request ao `api.php` deve incluir o header ou parâmetro `api_secret = 'UAI_MASTER_SAFE_2026'`. Sem isso, a API retorna erro 403.

> [!CAUTION]
> **NUNCA** comite o `API_SECRET` no GitHub ou repositório público. Use variáveis de ambiente (`.env`) que são ignoradas pelo `.gitignore`.

### Camada 2 — Autenticação (Token de Sessão)
Após login, o sistema gera um `session_token` JWT-like armazenado no `localStorage`. Cada request inclui este token para validar identidade.

### Camada 3 — Isolamento Multi-Tenant
Todo endpoint que retorna dados filtra por `tenant_id`. Mesmo que alguém descubra um endpoint, sem o `session_token` correto do tenant correto, não obtém dados.

### Camada 4 — HTTPS + CORS
- Toda comunicação é via HTTPS
- O `api.php` aceita apenas origens autorizadas (dominios `*.uaisat.app.br`)

## 9.2 Estrutura de Permissões (ACL)

A tabela `acl_roles` define perfis com permissões granulares:

| Perfil | Acesso |
|--------|--------|
| `zeus_master` | Tudo — sem restrições |
| `tenant_admin` | Todos os módulos do próprio tenant |
| `tenant_financial` | Apenas módulos financeiros do tenant |
| `tenant_support` | Clientes, tickets, chat — sem financeiro |
| `tenant_sales` | Cadastrar clientes + vender planos |
| `subscriber` | Apollo apenas — próprios dados |

## 9.3 Boas Práticas de Segurança

- **Senhas**: Mínimo 8 caracteres, letras maiúsculas, minúsculas e números
- **Tokens Asaas**: Nunca exibir chaves completas na UI — use `****` mascarado
- **Logs de Acesso**: Toda ação é registrada em `audit_logs` com IP e timestamp
- **Timeout de Sessão**: Sessions expiram após 8 horas de inatividade

---

<br/>

# <a name="cap10"></a>CAPÍTULO 10: Operações Automatizadas (Cronjobs)

O servidor cPanel executa rotinas automáticas que mantêm o ecossistema funcionando sem intervenção humana.

## 10.1 Tabela de Cronjobs

| Horário | Comando | Função |
|---------|---------|--------|
| `0 0 1 * *` | `run_master_billing` | Gerar faturas de licença para todos os tenants (dia 1 do mês) |
| `30 0 * * *` | `sync_all_consumption` | Sincronizar consumo de dados de todas as linhas |
| `0 1 * * *` | `check_overdue_invoices` | Suspender linhas com fatura > 5 dias vencida |
| `0 2 * * *` | `send_billing_reminders` | WhatsApp para clientes com fatura vencendo em 3 dias |
| `0 6 * * 1` | `sync_csmvno_catalog` | Atualizar catálogo de planos do CSMVNO (toda segunda-feira) |
| `*/5 * * * *` | `check_pending_activations` | Verificar ativações pendentes a cada 5 minutos |
| `0 3 * * *` | `cleanup_expired_sessions` | Limpar tokens de sessão expirados |

## 10.2 Como Configurar no cPanel

1. Acessar cPanel em `uaisat.app.br:2083`
2. Menu **"Tarefas Agendadas (Cron Jobs)"**
3. Para cada linha da tabela acima, criar entrada:
   - Período: conforme coluna "Horário"
   - Comando: `curl -s "https://uaisat.app.br/api/api.php?action=ACAO&api_secret=UAI_MASTER_SAFE_2026"`

---

<br/>

# <a name="cap11"></a>CAPÍTULO 11: Deploy e Publicação

## 11.1 Estrutura de Publicação no Servidor

```
public_html/
├── api/
│   └── api.php          ← Backend principal
├── zeus/
│   └── [build zeus]     ← App Zeus (SPA React)
├── hermes/
│   └── [build hermes]   ← App Hermes (SPA React)
├── iris/
│   └── [build iris]     ← App Iris (SPA React)
└── apollo/
    └── [build apollo]   ← App Apollo (SPA React)
```

## 11.2 Build dos Apps

```bash
cd Source
npm install --legacy-peer-deps

# Build individual por app:
npm run build:zeus     # → dist-zeus/
npm run build:hermes   # → dist-hermes/
npm run build:iris     # → dist-iris/
npm run build:apollo   # → dist-apollo/

# Ou tudo de uma vez:
npm run build:all
```

## 11.3 Deploy via FTP (cPanel)

Credenciais FTP (conforme ARCHITECTURE.md):
- **Host:** `uaisat.app.br`
- **Usuário:** `uais8385`
- **Porta:** 21

Após build, enviar via FTP:
- `dist-zeus/*` → `/public_html/zeus/`
- `dist-hermes/*` → `/public_html/hermes/`
- `dist-iris/*` → `/public_html/iris/`
- `dist-apollo/*` → `/public_html/apollo/`
- `api.php` → `/public_html/api/api.php`

## 11.4 Arquivo .htaccess (Obrigatório para SPA)

Cada pasta de app precisa de um `.htaccess` para roteamento React:

```apache
Options -MultiViews
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.html [QR,L]
```

Sem este arquivo, ao apertar F5 em qualquer rota que não seja `/`, o servidor retorna 404.

---

<br/>

# <a name="cap12"></a>CAPÍTULO 12: Troubleshooting Central

## 12.1 Problemas Comuns e Soluções

### ❌ Erro 403 "Forbidden" na API

**Causa:** `api_secret` incorreto ou ausente.

**Solução:**
1. Verificar se o `API_SECRET` em `src/services/phpApiService.ts` é `'UAI_MASTER_SAFE_2026'`
2. Verificar no `api.php` se a constante `API_SECRET` tem o mesmo valor
3. Se mudou a senha, atualizar em **todos** os arquivos listados em `ARCHITECTURE.md`

---

### ❌ Tela branca / "Failed to Load Chunk" após deploy

**Causa:** Cache do navegador retendo arquivos JavaScript antigos com hash diferente.

**Solução:**
1. Pedir ao usuário para limpar cache: `Ctrl + Shift + R` (hard reload)
2. Ou navegar até **System Health** → "Limpar Cache e Service Workers"
3. Para prevenir: o build Vite usa hash nos nomes dos arquivos (`main.a3f7e91d.js`) — cada deploy gera nomes únicos

---

### ❌ CORS Error no localhost

**Causa:** Frontend local tentando chamar a API em produção sem proxy.

**Solução:**
1. Confirmar que está usando `npm run dev:zeus` (não abrindo o `index.html` diretamente)
2. Verificar que o `vite.config.zeus.ts` tem o proxy configurado:
   ```typescript
   proxy: {
     '/api-proxy': {
       target: 'https://uaisat.app.br',
       changeOrigin: true,
       rewrite: (path) => path.replace(/^\/api-proxy/, '/api')
     }
   }
   ```
3. Verificar que o `phpApiService.ts` usa `/api-proxy/api.php` em localhost (não a URL absoluta)

---

### ❌ Tenant não detectado — "Operadora não encontrada"

**Causa:** O subdomínio não está cadastrado no banco de dados.

**Solução:**
1. Zeus → "Lista de Operadoras" → verificar se o slug está correto
2. Verificar se `is_active = 1` na tabela `tenants`
3. Verificar se o DNS do subdomínio está apontando para o servidor correto

---

### ❌ Webhook Asaas não recebendo pagamentos

**Causa:** URL do webhook incorreta ou ambiente errado (sandbox vs. produção).

**Solução:**
1. No painel Asaas do tenant: Configurações → Integrações → Webhooks
2. Verificar que a URL é: `https://uaisat.app.br/api/api.php?action=asaas_webhook&asaas_secret=CHAVE_DO_TENANT`
3. Verificar que o ambiente (sandbox/produção) está correto
4. Testar manualmente: cPanel → `error.log` do PHP → procurar por erros na action `asaas_webhook`

---

### ❌ Linha não ativa após pagamento confirmado

**Causa:** Falha na chamada CSMVNO após confirmação do Asaas.

**Diagnóstico:**
1. Zeus → *Logs Globais* → filtrar por `action = asaas_webhook`
2. Verificar se o log mostra "CSMVNO call failed"
3. Verificar na tela de System Health se o token CSMVNO está válido

**Solução:**
1. Verificar token CSMVNO em Zeus → Configurações Zeus → Token Operacional
2. Tentar ativar manualmente: Hermes → cliente → linha → "Tentar Ativar Novamente"
3. Se persistir, contatar suporte CSMVNO com o `iccid` e timestamp da tentativa

---

### ❌ "Index of" aparece em vez do app React

**Causa:** Arquivo `.htaccess` ausente ou mod_rewrite não habilitado.

**Solução:**
1. Garantir que o `.htaccess` existe na pasta do app (conforme Capítulo 11.4)
2. No cPanel → "Gerenciador de Arquivos" → verificar presença do arquivo
3. Contactar suporte do servidor para confirmar que `mod_rewrite` está habilitado

---

### ❌ Evolution API não está enviando WhatsApp

**Diagnóstico:**
1. Hermes → Configurações → WhatsApp → verificar status da conexão
2. O QR Code pode ter expirado — reconectar escaneando novo QR
3. Verificar se o número de WhatsApp não foi banido (muito comum se enviar spam)

**Solução:**
1. Reconectar: Hermes → Configurações → WhatsApp → "Desconectar" → "Conectar Novamente"
2. Escanear QR Code com o celular da operadora
3. Aguardar 30 segundos para sincronização

---

## 12.2 Comandos de Diagnóstico Rápido

Execute estes endpoints para diagnóstico direto:

```bash
# Verificar se API está online
curl https://uaisat.app.br/api/api.php?action=health_check

# Verificar status do tenant (substituir SLUG)
curl "https://uaisat.app.br/api/api.php?action=get_tenant_by_domain&domain=SLUG.hermes.uaisat.app.br&api_secret=UAI_MASTER_SAFE_2026"

# Listar todos os tenants ativos (apenas Zeus)
curl "https://uaisat.app.br/api/api.php?action=get_tenants&api_secret=UAI_MASTER_SAFE_2026&session_token=SEU_TOKEN_ZEUS"
```

---

## 12.3 Escalada de Problemas

| Severidade | Critério | Resposta |
|------------|----------|----------|
| **P1 - Crítico** | API fora do ar, banco inacessível | Imediata — contato direto engenharia |
| **P2 - Alto** | Webhook Asaas parado, linhas não ativando | até 2 horas |
| **P3 - Médio** | Feature não funcionando para um tenant | até 8 horas |
| **P4 - Baixo** | Bug cosmético, lentidão pontual | Próxima sprint |

---

<br/>

## Palavras Finais da Engenharia

Esta é a sua **Máquina de Lucro Autônoma**. O código é veloz, seguro e resiliente — mas precisa de operadores responsáveis.

**Regras de Ouro:**
1. Nunca compartilhe o `API_SECRET` ou tokens de produção fora de canais seguros
2. Mantenha os cronjobs funcionando — eles são o coração da automação
3. Tenha um processo de backup semanal do banco MySQL
4. Monitore o `error.log` do PHP na pasta raiz do cPanel
5. Antes de qualquer deploy, sempre faça `npm run build` localmente e verifique erros

> **Ecossistema UaiSat — Versão 2.0 — Finalizado com Sucesso.**
> *Documento oficial de engenharia. Distribuição restrita.*