# Gestão de Cobranças SaaS — Manual de Instalação

## Requisitos de Sistema

| Componente    | Versão Mínima |
|--------------|---------------|
| PHP          | 8.3+          |
| MySQL        | 8.0+ / PostgreSQL 15+ |
| Redis        | 7.x           |
| Composer     | 2.x           |
| Node.js      | 20.x          |
| Docker       | 24.x          |

---

## Instalação com Docker (Recomendado)

### 1. Clone o repositório

```bash
git clone https://github.com/seu-usuario/gestao-cobrancas.git
cd gestao-cobrancas
```

### 2. Configure o ambiente

```bash
cp .env.example .env
```

Edite o `.env` e configure as variáveis principais:

```env
APP_KEY=          # Será gerado automaticamente
DB_DATABASE=gestao_cobrancas
DB_USERNAME=gestao
DB_PASSWORD=senha_segura

# Mercado Pago
MERCADOPAGO_ACCESS_TOKEN=seu_access_token
MERCADOPAGO_WEBHOOK_SECRET=seu_webhook_secret

# PagSeguro
PAGSEGURO_TOKEN=seu_token

# WhatsApp Business
WHATSAPP_PHONE_NUMBER_ID=seu_phone_id
WHATSAPP_ACCESS_TOKEN=seu_token
WHATSAPP_VERIFY_TOKEN=token_verificacao
```

### 3. Suba os containers

```bash
docker-compose up -d
```

### 4. Configure a aplicação

```bash
# Gerar chave da aplicação
docker exec gestao_app php artisan key:generate

# Executar migrations + seeders
docker exec gestao_app php artisan migrate --seed

# Criar link de storage
docker exec gestao_app php artisan storage:link

# Otimizar para produção
docker exec gestao_app php artisan optimize
```

### 5. Acesse o sistema

- **Painel Super Admin**: http://localhost/admin
  - Email: `admin@gestaocobrancas.com.br`
  - Senha: `Admin@123456`

- **Painel Empresa Demo**: http://localhost/dashboard
  - Email: `admin@empresa.com`
  - Senha: `Demo@123456`

- **Mailhog** (emails dev): http://localhost:8025
- **Horizon** (filas): http://localhost/horizon

---

## Instalação em cPanel

### Pré-requisitos

1. PHP 8.3 configurado no MultiPHP Manager
2. MySQL 8.0 disponível
3. Extensões: `pdo_mysql`, `mbstring`, `exif`, `bcmath`, `gd`, `zip`, `opcache`, `redis` (opcional)

### Passo a Passo

#### 1. Upload dos arquivos

- Faça upload de todos os arquivos para `/home/usuario/public_html/` ou um subdiretório
- O **Document Root** deve apontar para a pasta `public/`

No `.htaccess` da raiz da conta, adicione:
```apache
RewriteEngine On
RewriteRule ^(.*)$ public/$1 [L]
```

#### 2. Configure o banco de dados

No cPanel > MySQL Databases:
1. Crie o banco `usuario_gestaocobrancas`
2. Crie o usuário e conceda todos os privilégios

#### 3. Configure o `.env`

```env
APP_ENV=production
APP_DEBUG=false
APP_URL=https://seudominio.com.br

DB_CONNECTION=mysql
DB_HOST=localhost
DB_DATABASE=usuario_gestaocobrancas
DB_USERNAME=usuario_db
DB_PASSWORD=senha_db

QUEUE_CONNECTION=database   # Se não tiver Redis
CACHE_STORE=file            # Se não tiver Redis
SESSION_DRIVER=file         # Se não tiver Redis
```

#### 4. Execute via SSH ou cPanel Terminal

```bash
cd /home/usuario/public_html

# Instalar dependências
composer install --no-dev --optimize-autoloader

# Gerar chave
php artisan key:generate

# Migrations
php artisan migrate --seed --force

# Storage link
php artisan storage:link

# Otimizar
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

#### 5. Configurar Cron (Scheduler)

Em cPanel > Cron Jobs, adicione:
```
* * * * * php /home/usuario/public_html/artisan schedule:run >> /dev/null 2>&1
```

#### 6. Queue Worker (sem Redis)

Crie um Cron Job adicional:
```
* * * * * php /home/usuario/public_html/artisan queue:work --sleep=3 --tries=3 --max-time=55 >> /home/usuario/logs/queue.log 2>&1
```

---

## Configuração dos Gateways de Pagamento

### Mercado Pago

1. Acesse [https://www.mercadopago.com.br/developers](https://www.mercadopago.com.br/developers)
2. Crie um aplicativo
3. Obtenha o **Access Token** e **Public Key**
4. Configure os webhooks para: `https://seudominio.com.br/webhook/mercadopago`
5. No painel da empresa, vá em **Configurações > Gateways** e adicione as credenciais

### PagSeguro

1. Acesse [https://dev.pagbank.com.br](https://dev.pagbank.com.br)
2. Crie uma conta sandbox para testes
3. Obtenha o **Token** de autenticação
4. Configure os webhooks para: `https://seudominio.com.br/webhook/pagseguro`

---

## Configuração do WhatsApp Business

### Meta Cloud API

1. Acesse [https://developers.facebook.com](https://developers.facebook.com)
2. Crie um aplicativo do tipo **Business**
3. Adicione o produto **WhatsApp**
4. Obtenha:
   - `WHATSAPP_PHONE_NUMBER_ID`
   - `WHATSAPP_ACCESS_TOKEN` (permanente via System User)
   - `WHATSAPP_BUSINESS_ACCOUNT_ID`
5. Configure o Webhook URL: `https://seudominio.com.br/webhook/whatsapp`
6. Selecione eventos: `messages`, `message_status_updates`

### Templates necessários

Crie os seguintes templates no Meta Business Manager:

| Template             | Categoria | Uso |
|---------------------|-----------|-----|
| `cobranca_vencendo`  | UTILITY   | Lembretes 7d e 3d antes |
| `cobranca_vence_hoje` | UTILITY  | No dia do vencimento |
| `cobranca_vencida`   | UTILITY   | Após vencimento |
| `pagamento_confirmado` | UTILITY | Confirmação de pagamento |

---

## Estrutura Multi-Tenant

O sistema usa **single-database multi-tenancy** com isolamento por `empresa_id`:

- Cada empresa tem um **subdomínio único**: `empresa.gestaocobrancas.com.br`
- Suporte a **domínio customizado**: `app.suaempresa.com.br`
- **White Label**: logo, cores e nome próprios por empresa
- Todos os dados são isolados automaticamente via Eloquent Global Scope

### Wildcard DNS

Para funcionar com subdomínios, configure no DNS:
```
*.gestaocobrancas.com.br  CNAME  gestaocobrancas.com.br
```

---

## Planos SaaS

| Recurso                | Básico   | Profissional | Empresarial |
|------------------------|----------|-------------|------------|
| Clientes               | 500      | 5.000       | Ilimitado  |
| Cobranças/mês          | 2.000    | 20.000      | Ilimitado  |
| WhatsApp               | ❌       | ✅          | ✅         |
| API REST               | ❌       | ✅          | ✅         |
| White Label            | ❌       | ❌          | ✅         |
| Domínio Próprio        | ❌       | ❌          | ✅         |
| Preço mensal           | R$ 49    | R$ 99       | R$ 249     |

---

## API REST

Base URL: `https://seudominio.com.br/api/v1`

### Autenticação

```bash
# Login
POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "admin@empresa.com",
  "password": "senha"
}

# Response
{
  "success": true,
  "data": {
    "token": "1|abc123...",
    "usuario": { ... }
  }
}
```

Use o token em todas as requisições:
```
Authorization: Bearer 1|abc123...
```

### Endpoints Principais

```
GET    /api/v1/clientes              Lista clientes (paginado)
POST   /api/v1/clientes              Criar cliente
GET    /api/v1/clientes/{uuid}       Detalhes do cliente
PUT    /api/v1/clientes/{uuid}       Atualizar cliente
DELETE /api/v1/clientes/{uuid}       Excluir cliente

GET    /api/v1/cobrancas             Lista cobranças
POST   /api/v1/cobrancas             Criar cobrança
GET    /api/v1/cobrancas/{uuid}      Detalhes da cobrança
DELETE /api/v1/cobrancas/{uuid}      Cancelar cobrança
GET    /api/v1/cobrancas/{uuid}/pix  Dados do PIX
GET    /api/v1/cobrancas/{uuid}/boleto Dados do boleto

POST   /api/v1/auth/logout           Logout
GET    /api/v1/auth/me               Dados do usuário autenticado
```

### Exemplo: Criar cobrança PIX

```bash
POST /api/v1/cobrancas
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "cliente_id": 1,
  "descricao": "Mensalidade Janeiro/2025",
  "valor": 15000,
  "data_vencimento": "2025-01-31",
  "metodo_pagamento": "pix"
}
```

---

## Automações de Notificação

O scheduler executa diariamente e processa:

| Quando | Ação |
|--------|------|
| 7 dias antes do vencimento | Lembrete por e-mail + WhatsApp |
| 3 dias antes do vencimento | Lembrete por e-mail + WhatsApp |
| No dia do vencimento | Aviso de vencimento hoje |
| 1 dia após vencimento | Cobrança de atraso |
| 3 dias após vencimento | Segunda cobrança |
| 7 dias após vencimento | Cobrança escalada |

Flags de controle evitam duplo envio: `notificado_7d`, `notificado_3d`, etc.

---

## Filas e Workers

O sistema usa **Laravel Horizon** para gerenciar as filas Redis:

| Fila          | Prioridade | Uso |
|---------------|-----------|-----|
| `critical`    | Máxima    | Webhooks, confirmações de pagamento |
| `payments`    | Alta      | Processamento de pagamentos |
| `notifications` | Média   | WhatsApp, e-mail |
| `reports`     | Baixa     | Geração de relatórios |
| `default`     | Baixa     | Demais jobs |

Acesse o Horizon em: `https://seudominio.com.br/horizon`
(Requer login como Super Admin)

---

## Segurança

- Credenciais de gateways criptografadas com `encrypted:array` (chave `APP_KEY`)
- Senhas de usuários com bcrypt
- Validação de assinatura de webhooks (HMAC)
- Multi-tenancy com Eloquent Global Scope (3 camadas de proteção)
- UUIDs em todas as URLs públicas (não enumeráveis)
- Rate limiting: API 60req/min, Login 10req/min, Webhooks 600req/min
- Auditoria completa de todas as ações

---

## Suporte

- Documentação da API: `/api/v1/docs` (em desenvolvimento)
- Logs: `storage/logs/laravel.log`
- Horizon Dashboard: `/horizon`
- E-mail: suporte@gestaocobrancas.com.br