# 🚀 PDV SaaS - Guia de Implementação Multi-Tenant

## 📋 Visão Geral

O PDV foi transformado em um **sistema SaaS multi-tenant** com isolamento completo de dados por empresa. Cada empresa tem seus próprios usuários, produtos, vendas e configurações.

---

## 🏗️ Arquitetura SaaS

### 1. Hierarquia de Usuários

```
┌─────────────────────────────────────────────┐
│        SUPER ADMIN (empresa_id = NULL)      │
│  - Gerencia todas as empresas do sistema    │
│  - Acesso ao dashboard global               │
│  - Relatórios de receita/métricas           │
│  - Controle de planos e assinaturas         │
└─────────────────────────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        │             │             │
   ┌─────────────┐ ┌─────────────┐ ┌──────────────┐
   │ EMPRESA 1   │ │ EMPRESA 2   │ │ EMPRESA N... │
   │ empresa_id=1│ │ empresa_id=2│ │ empresa_id=n │
   └─────────────┘ └─────────────┘ └──────────────┘
        │                │                │
        ├─ Admin         ├─ Admin         ├─ Admin
        │ (admin_empresa)│ (admin_empresa)│ (admin_empresa)
        │                │                │
        ├─ Gerentes      ├─ Gerentes      ├─ Gerentes
        │                │                │
        └─ Vendedores    └─ Vendedores    └─ Vendedores
```

### 2. Tipos de Usuários

| Tipo | Nível | Permissões |
|------|-------|-----------|
| **super_admin** | Global | Admin SaaS, todas as empresas, relatórios, planos |
| **admin_empresa** | Empresa | Dashboard empresa, gerenciar usuários, PDV, relatórios |
| **gerente** | Empresa | PDV, relatórios, gerenciar caixa |
| **vendedor** | Empresa | Apenas PDV (vender) |

---

## 📁 Arquivos Novos Criados

### Modelos

**`/models/Empresa.php`**
- `criar()` - Registrar nova empresa + plano básico
- `obterPorId()` - Buscar dados da empresa
- `atualizar()` - Editar dados
- `listar()` - Listar todas (super_admin)
- `obterUsuarios()` - Usuários da empresa
- `obterPlano()` - Plano ativo
- `atingiuLimiteUsuarios()` - Validar limite

### Páginas Públicas (Sem Login)

**`/registro.php`**
- Cadastro de nova empresa
- Criação do primeiro usuário (admin)
- Validação de CNPJ, emails, senhas
- Atribuição automática de plano básico

### Páginas Autenticadas

**`/auth/login.php`** (Atualizado)
- Login para todos os tipos de usuários
- Redirecionamento baseado em `tipo_usuario`
  - super_admin → `/pages/admin_saas.php`
  - outros → `/pages/dashboard.php`
- Armazenamento de `empresa_id` e `tipo_usuario` na sessão
- Log de acesso (tabela `log_acesso`)

**`/pages/admin_saas.php`** (Novo)
- Dashboard global para super_admin
- Estatísticas: empresas, usuários, vendas, receita
- Listagem de empresas com detalhes
- Abas: Empresas, Usuários, Planos, Relatórios

**`/pages/gerenciar_usuarios.php`** (Novo)
- Convite de novos usuários
- Validação de limite por plano
- Listagem de usuários ativos
- Remoção de usuários
- Verificação de segurança (manter admin)

**`/auth/logout.php`** (Atualizado)
- Log de logout (tabela `log_acesso`)
- Destruição de sessão
- Redirecionamento para login

---

## 🗄️ Schema do Banco de Dados

Arquivo: `/config/saas_schema.sql`

### Tabelas Novas

#### 1. **empresas**
```sql
- id (PK)
- nome, email, cnpj, razao_social
- responsavel_nome, responsavel_email, responsavel_telefone
- logo, ativa
- data_criacao, data_atualizacao
```

#### 2. **planos**
```sql
- id (PK)
- nome, descricao, preco_mensal
- limite_usuarios, limite_produtos
- suporta_multiplos_caixas, suporta_relatorios
- ativo
```

Planos pré-configurados:
- **Básico**: R$ 49,90 - 3 usuários, 500 produtos
- **Profissional**: R$ 99,90 - 10 usuários, 2000 produtos
- **Enterprise**: R$ 299,90 - 50 usuários, 10000 produtos

#### 3. **assinaturas**
```sql
- empresa_id (PK/FK)
- plano_id (FK)
- data_inicio, data_vencimento, data_renovacao
- status (ativa, cancelada, suspensa, vencida)
- ciclo_pagamento (mensal, anual)
```

#### 4. **log_acesso** (Auditoria)
```sql
- id (PK)
- empresa_id, usuario_id
- acao (login, logout, create, update, delete)
- tabela, registro_id
- dados_antes, dados_depois (JSON)
- ip, user_agent, timestamp
```

### Tabelas Modificadas

Todas as tabelas existentes receberam coluna **`empresa_id`** (FK → empresas.id):
- produtos
- vendas
- itens_venda
- caixa
- movimentacao_estoque
- grupos
- preco_pagamento

Coluna **`empresa_id`** é obrigatória (NOT NULL) em todas essas tabelas.

### Tabela usuarios (Redesenhada)

```sql
- id (PK)
- empresa_id (FK) - NULL se super_admin, obrigatório para outros
- nome, email, senha
- telefone
- tipo_usuario (ENUM: super_admin, admin_empresa, gerente, vendedor)
- token_convite, data_expiracao_token (para confirmação de email)
- ativo (0=pendente, 1=ativo)
- data_criacao, data_atualizacao
```

---

## 🔒 Isolamento de Dados (Segurança)

### Middleware SaaS (Próxima Implementação)

Todos os modelos devem implementar filtro `empresa_id`:

```php
// ❌ Inseguro
SELECT * FROM produtos WHERE id = $id

// ✅ Seguro
SELECT * FROM produtos 
WHERE id = $id AND empresa_id = $_SESSION['empresa_id']
```

---

## 🚀 Fluxo de Uso

### 1️⃣ Novo Cliente Registra Empresa

```
/registro.php
├─ Preenche dados da empresa (nome, CNPJ, responsável)
├─ Cria primeiro usuário (admin_empresa)
├─ Inserts em: empresas, usuarios, assinaturas (plano básico)
└─ Redireciona para /auth/login.php
```

### 2️⃣ Admin Faz Login

```
/auth/login.php
├─ Busca usuário por email
├─ Valida senha com password_verify()
├─ Armazena em $_SESSION:
│  - user_id
│  - empresa_id
│  - tipo_usuario
│  - nome, email, empresa_nome
├─ Insere log em log_acesso
└─ Redireciona para /pages/dashboard.php (ou admin_saas.php se super_admin)
```

### 3️⃣ Admin Convida Usuários

```
/pages/gerenciar_usuarios.php
├─ Valida limite de usuários do plano
├─ Cria usuário com tipo_usuario (vendedor/gerente/admin)
├─ Gera token_convite
├─ TODO: Envia email com link de aceitar convite
└─ Usuário faz login quando confirma
```

### 4️⃣ PDV Isolado por Empresa

```
/pages/pdv.php
├─ Busca: SELECT * FROM produtos WHERE empresa_id = $_SESSION['empresa_id']
├─ Vendas: INSERT INTO vendas (empresa_id, ...) VALUES ($_SESSION['empresa_id'], ...)
├─ Caixa: Isolado por empresa
└─ Relatórios: Apenas dados da empresa
```

---

## 📊 Estatísticas Globais (Super Admin)

Dashboard `/pages/admin_saas.php` mostra:

```sql
-- Empresas ativas
SELECT COUNT(*) FROM empresas WHERE ativa = 1

-- Usuários globais
SELECT COUNT(*) FROM usuarios WHERE ativo = 1

-- Vendas do dia (todas as empresas)
SELECT SUM(total) FROM vendas WHERE DATE(data_venda) = CURDATE()

-- Receita mensal (assinaturas ativas)
SELECT SUM(valor_mensal) FROM assinaturas a 
JOIN planos p ON a.plano_id = p.id 
WHERE a.status = 'ativa'
```

---

## 🔧 Próximas Implementações

### Críticas (Segurança)

- [ ] **Middleware SAAS** - Filtro automático `empresa_id` em todos os modelos
- [ ] **Validação de Plano** - Bloquear ações se fora do limite (usuários, produtos)
- [ ] **Proteção de Dados** - Criptografia de senhas com token_convite

### Funcionalidades

- [ ] **Email de Convite** - Usar PHPMailer/SendGrid
- [ ] **Página Aceitar Convite** - Confirmar email + definir senha
- [ ] **Upgrade de Plano** - Interface para mudar plano/billing
- [ ] **Cancelamento** - Desativar empresa, preservar dados
- [ ] **Relatórios Avançados** - Gráficos de crescimento, MRR, churn
- [ ] **Backup Automático** - Por empresa
- [ ] **API para Integrações** - Webhooks, OAuth

### SLA/Suporte

- [ ] **Sistema de Tickets** - Suporte por empresa
- [ ] **Status Page** - Monitoramento de uptime
- [ ] **Alertas** - Email de eventos (plano vencido, limite atingido)

---

## 🧪 Dados de Teste

No banco de dados, foram inseridos:

### Empresa
```
ID: 1
Nome: Loja Matriz
CNPJ: 12.345.678/0000-90
Plano: Básico (1 mês grátis a partir de hoje)
```

### Usuários
```
1. Super Admin
   Email: super@saas.com
   Senha: senha
   Tipo: super_admin
   
2. Admin Empresa
   Email: admin@lojamatriz.com.br
   Senha: senha
   Tipo: admin_empresa
   Empresa: Loja Matriz
```

---

## 🚨 Checklist de Segurança

- [x] Senhas hasheadas com PASSWORD_BCRYPT
- [x] Prepared statements (PDO)
- [ ] CSRF tokens em formulários
- [ ] Rate limiting no login
- [ ] Validação de email (token_convite)
- [ ] Logs de auditoria (log_acesso)
- [ ] HTTPS obrigatório em produção
- [ ] Backup automático
- [ ] Encriptação de dados sensíveis

---

## 📚 Arquivos de Referência

- `/config/saas_schema.sql` - Schema completo
- `/models/Empresa.php` - Classe modelo
- `/registro.php` - Registrar empresa
- `/auth/login.php` - Login multi-tenant
- `/pages/admin_saas.php` - Dashboard super_admin
- `/pages/gerenciar_usuarios.php` - Gerenciar usuários

---

## 🎯 Próximo Passo

**Implementar Middleware SaaS** para garantir isolamento automático de dados em todas as queries. Isso protege contra vazamento de dados entre empresas.

Ver `/auth/saas_middleware.php` (a criar).