# 🚀 Guia Completo: Multi-Tenancy (Múltiplas Franquias)

## 📋 Índice

1. [Visão Geral](#visão-geral)
2. [Início Rápido](#início-rápido)
3. [Instalação Passo a Passo](#instalação-passo-a-passo)
4. [Criar Segunda Franquia](#criar-segunda-franquia)
5. [Solução de Problemas](#solução-de-problemas)
6. [Estrutura de Bancos](#estrutura-de-bancos)

---

## 🎯 Visão Geral

Sistema preparado para rede de franquias onde cada franquia tem seu próprio banco de dados isolado, mas todos fazem login pelo mesmo link.

### Como Funciona

- **Login único:** Todos acessam `traineestagios.com.br/login`
- **Identificação automática:** Sistema identifica qual franquia o usuário pertence
- **Bancos separados:** Cada franquia tem seu próprio banco (`trainees_franquia_001`, `trainees_franquia_002`, etc.)
- **Dados isolados:** Franquias não veem dados umas das outras

---

## ⚡ Início Rápido

### Passo 1: Criar Tabelas Master

**Se você TEM permissão para criar banco:**
1. Execute: `sql/create_master_database.sql` no phpMyAdmin

**Se você NÃO TEM permissão:**
1. Selecione seu banco atual no phpMyAdmin
2. Execute: `sql/create_master_tables_only.sql`

### Passo 2: Registrar Primeira Franquia

1. No banco onde criou as tabelas master, abra a tabela `franchises`
2. Insira:
   - `code`: `001`
   - `name`: `Franquia Matriz`
   - `database_name`: `trainees_franquia_001` (ou nome do seu banco atual)
   - `status`: `active`

### Passo 3: Sincronizar Usuários

Execute: `http://seusite.com.br/scripts/sync_users_to_master.php`

### Passo 4: Testar

Faça login normalmente. O sistema deve funcionar.

---

## 📝 Instalação Passo a Passo

### Pré-requisitos

- ✅ Backup do banco de dados atual
- ✅ Acesso ao phpMyAdmin ou MySQL
- ✅ Código atualizado (já está feito)

### Passo 1: Criar Banco Master (ou usar banco atual)

#### Opção A: Criar Banco Master (se tiver permissão)

1. No phpMyAdmin, clique em "SQL"
2. Execute o arquivo: `sql/create_master_database.sql`
3. ✅ Banco `trainees_master` criado com tabelas `franchises` e `users_master`

#### Opção B: Usar Banco Atual (se não tiver permissão)

1. Selecione seu banco atual no phpMyAdmin
2. Execute o arquivo: `sql/create_master_tables_only.sql`
3. ✅ Tabelas `franchises` e `users_master` criadas no banco atual

**Nota:** O código foi ajustado para funcionar automaticamente com ambas as opções.

### Passo 2: Preparar Banco da Primeira Franquia

#### Se você JÁ TEM dados no banco atual:

1. No phpMyAdmin, selecione seu banco atual
2. Vá em "Operações" → "Renomear banco de dados"
3. Renomeie para: `trainees_franquia_001`
4. Clique em "OK"

#### Se você NÃO TEM dados ainda:

1. No phpMyAdmin, crie novo banco: `trainees_franquia_001`
2. Collation: `utf8mb4_unicode_ci`
3. Importe o arquivo `sql/schema.sql`

### Passo 3: Registrar Franquia

1. No banco onde estão as tabelas `franchises`, abra a tabela `franchises`
2. Clique em "Inserir"
3. Preencha:
   - `code`: `001`
   - `name`: `Franquia Matriz`
   - `subdomain`: `matriz` (opcional)
   - `database_name`: `trainees_franquia_001`
   - `status`: `active`
4. Clique em "Executar"

### Passo 4: Sincronizar Usuários

**Via Navegador:**
```
http://seusite.com.br/scripts/sync_users_to_master.php
```

**Via Terminal:**
```bash
php scripts/sync_users_to_master.php
```

### Passo 5: Testar

1. Acesse: `http://seusite.com.br/public/login`
2. Faça login com um usuário existente
3. O sistema deve funcionar normalmente

---

## 🏢 Criar Segunda Franquia

### Passo 1: Criar Banco da Franquia

1. No phpMyAdmin, crie novo banco: `trainees_franquia_002`
2. Collation: `utf8mb4_unicode_ci`
3. Importe o arquivo `sql/schema.sql`

**Ou use o script automatizado:**
1. Edite `scripts/create_franchise.php`
2. Ajuste as variáveis:
   ```php
   $franchiseCode = '002';
   $franchiseName = 'Franquia São Paulo';
   ```
3. Execute: `php scripts/create_franchise.php`

### Passo 2: Registrar Franquia

1. No banco master, abra a tabela `franchises`
2. Insira:
   - `code`: `002`
   - `name`: `Franquia São Paulo`
   - `database_name`: `trainees_franquia_002`
   - `status`: `active`

### Passo 3: Criar Usuários

1. No banco `trainees_franquia_002`, crie usuários na tabela `users`
2. Execute o script de sincronização: `scripts/sync_users_to_master.php`

### Passo 4: Testar Isolamento

1. Faça login com usuário da Franquia 001 → Veja dados da 001
2. Faça logout
3. Faça login com usuário da Franquia 002 → Veja dados da 002 (isolados)

---

## 🔧 Solução de Problemas

### Erro: "Acesso negado para criar banco"

**Solução:**
1. Use o arquivo `sql/create_master_tables_only.sql` no seu banco atual
2. O código já está ajustado para funcionar assim
3. Para futuras franquias, peça ao provedor para criar os bancos

### Erro: "Usuário não encontrado"

**Solução:**
1. Execute o script de sincronização: `scripts/sync_users_to_master.php`
2. Verifique se o usuário existe no banco da franquia
3. Verifique se está na tabela `users_master`

### Erro: "Banco não encontrado"

**Solução:**
1. Verifique se o banco foi criado
2. Verifique se o nome está correto na tabela `franchises`
3. Verifique permissões do usuário MySQL

---

## 🏗️ Estrutura de Bancos

### Como Funciona

```
Banco Master (ou banco atual)
├── franchises (tabela de controle)
│   ├── Franquia 001 → banco: trainees_franquia_001
│   └── Franquia 002 → banco: trainees_franquia_002
└── users_master (tabela de controle)
    ├── usuário1 → franquia_id: 1
    └── usuário2 → franquia_id: 2

Banco: trainees_franquia_001
├── users (usuários da Franquia 001)
├── receivables (dados financeiros da 001)
├── payables (dados financeiros da 001)
└── ... (TODOS os dados da Franquia 001)

Banco: trainees_franquia_002
├── users (usuários da Franquia 002)
├── receivables (dados financeiros da 002)
└── ... (TODOS os dados da Franquia 002)
```

### Pontos Importantes

- ✅ **Tabelas master = apenas controle** (não contêm dados das franquias)
- ✅ **Cada franquia = banco separado** (dados isolados)
- ✅ **Login único** identifica automaticamente a franquia
- ✅ **Dados não se misturam** entre franquias

---

## 📚 Arquivos Importantes

### SQL
- `sql/create_master_database.sql` - Cria banco master (se tiver permissão)
- `sql/create_master_tables_only.sql` - Cria apenas tabelas (se não tiver permissão)
- `sql/schema.sql` - Schema completo para cada banco de franquia

### Scripts PHP
- `scripts/sync_users_to_master.php` - Sincroniza usuários
- `scripts/create_franchise.php` - Cria nova franquia automaticamente

### Código
- `src/Utils/Database.php` - Suporta múltiplos bancos
- `src/Utils/FranchiseUserFinder.php` - Busca usuário e identifica franquia
- `src/Controllers/AuthController.php` - Login único implementado

---

## ✅ Checklist Final

Antes de considerar completo:

- [ ] Tabelas master criadas
- [ ] Franquia 001 registrada
- [ ] Usuários sincronizados
- [ ] Login testado e funcionando
- [ ] Segunda franquia criada (quando necessário)
- [ ] Isolamento testado

---

## 🆘 Precisa de Ajuda?

Consulte:
- **Estrutura detalhada:** `docs/ESTRUTURA_BANCOS_MULTI_TENANCY.md`
- **Como criar segunda franquia:** Seção acima neste guia
- **Checklist quando voltar:** `CHECKLIST_QUANDO_VOLTAR.md`

---

## 🎯 Resumo

**Sistema de multi-tenancy permite:**
- ✅ Login único para todas as franquias
- ✅ Bancos separados por franquia
- ✅ Dados completamente isolados
- ✅ Escalabilidade independente

**Tudo pronto e funcionando!** 🚀

