# Fluxo de Controle de Acesso - Google Calendar Integration

## Visão Geral

O sistema de controle de acesso para a integração do Google Calendar implementa uma hierarquia de verificações que combina planos de assinatura, permissões RBAC e regras de bypass administrativo.

## Arquitetura do Sistema

### 1. Middleware de Controle de Planos (`PlanAccessMiddleware`)

O `PlanAccessMiddleware` é o ponto central de controle que:

- **Intercepta requisições** para endpoints protegidos
- **Verifica habilitação de módulos** baseada no plano do tenant
- **Aplica regras de bypass** para usuários administrativos
- **Registra tentativas de acesso** para auditoria

### 2. Hierarquia de Verificação

#### Ordem de Prioridade:

1. **Bypass Administrativo** (mais alta prioridade)
   - Sessões impersonadas (`impersonated: true`)
   - Usuários registrados em `superadmins` (email presente na tabela)
   - Usuários com role 'admin'
   - Fallback de dev: email `admin@local` (quando `APP_ENV=local`)

2. **Verificação de Plano**
   - Consulta o plano ativo do tenant
   - Verifica se o módulo está habilitado no plano
   - Aplica overrides específicos do tenant

3. **Verificação RBAC** (mais baixa prioridade)
   - Valida permissões específicas do usuário
   - Consulta tabelas: `permissions`, `role_permissions`, `user_roles`

## Fluxo Detalhado

### Etapa 1: Inicialização do Contexto

```php
// No Kernel.php
TenantContext::bootstrapFromRequest($req);
```

- Extrai informações do tenant dos headers da requisição
- Configura conexão com banco de dados do tenant
- Prepara contexto para verificações subsequentes

### Etapa 2: Verificação de Bypass

```php
// Condições de bypass centralizadas (RBAC)
if ($user['impersonated'] || isSuperAdmin($user) || in_array('admin', $user['roles'])) {
    return $next($request); // Acesso liberado
}
```

### Etapa 3: Verificação de Plano

```php
// Consulta configuração do plano
$plan = $pdo->query("SELECT modules_json FROM plans WHERE id = ?", [$tenant['plan_id']]);
$enabledModules = json_decode($plan['modules_json'], true);

// Verifica se módulo está habilitado
if (!in_array($moduleName, $enabledModules)) {
    return Response::json(['error' => 'PLAN_RESTRICTION'], 403);
}
```

### Etapa 4: Aplicação de Overrides

```php
// Overrides específicos do tenant
$overrides = json_decode($tenant['module_overrides'], true) ?? [];
if (isset($overrides[$moduleName]) && !$overrides[$moduleName]) {
    return Response::json(['error' => 'MODULE_DISABLED'], 403);
}
```

### Etapa 5: Verificação RBAC (se aplicável)

```php
// No controlador, após passar pelo middleware
if (!Rbac::requirePermissions(['integrations.googlecalendar.read'])) {
    return Response::json(['error' => 'INSUFFICIENT_PERMISSIONS'], 403);
}
```

## Cenários de Teste Implementados

### 1. Usuário Básico - Plano Basic
- **Expectativa**: Bloqueado (403)
- **Razão**: Módulo GoogleCalendar não habilitado no plano basic
- **Resposta**: `{"error": "PLAN_RESTRICTION"}`

### 2. Usuário Admin - Qualquer Plano
- **Expectativa**: Acesso liberado (200)
- **Razão**: Bypass administrativo ativo
- **Token**: `impersonated: true, roles: ['admin']`

### 3. Usuário Premium - Plano Premium
- **Expectativa**: Acesso liberado (200)
- **Razão**: Módulo habilitado no plano + permissões RBAC
- **Verificações**: Plano + Permissão `integrations.googlecalendar.read`

## Configuração de Planos

### Plano Basic
```json
{
  "modules_json": ["core", "basic_features"]
}
```

### Plano Premium
```json
{
  "modules_json": ["core", "basic_features", "GoogleCalendar", "advanced_features"]
}
```

## Permissões RBAC

### Permissões do Google Calendar
- `integrations.googlecalendar.read` - Leitura de configurações
- `integrations.googlecalendar.manage` - Gerenciamento completo

### Vinculação com Roles
```sql
-- Role admin tem acesso total
INSERT INTO role_permissions (role_name, permission_name) 
VALUES ('admin', 'integrations.googlecalendar.read');

INSERT INTO role_permissions (role_name, permission_name) 
VALUES ('admin', 'integrations.googlecalendar.manage');
```

## Auditoria e Logs

### Registro de Acessos Negados
- **Banco do Tenant**: Tabela `audit_logs`
- **Banco Administrativo**: Tabela `access_denials`
- **Informações**: IP, usuário, módulo, timestamp, razão

### Exemplo de Log
```json
{
  "user_id": 2,
  "ip": "127.0.0.1",
  "path": "/api/integrations/googlecalendar/config",
  "module": "GoogleCalendar",
  "reason": "PLAN_RESTRICTION",
  "timestamp": "2024-01-15 10:30:00"
}
```

## Considerações de Segurança

### 1. Ordem de Verificação
- Bypass administrativo é verificado **primeiro** para evitar vazamentos de informação
- Verificações de plano precedem RBAC para otimização

### 2. Tokens JWT
- Tokens administrativos devem incluir `impersonated: true`
- Roles são validadas tanto no token quanto no banco

### 3. Isolamento de Tenants
- Cada tenant tem seu próprio banco de dados
- Configurações de plano são isoladas por tenant
- Overrides permitem customização específica

## Manutenção e Extensibilidade

### Adicionando Novos Módulos
1. Criar migrações de permissões (MySQL e SQLite)
2. Atualizar configurações de planos
3. Implementar middleware nos controladores
4. Criar testes de acesso

### Modificando Hierarquia
- Alterações no `PlanAccessMiddleware` afetam todos os módulos
- Testes devem ser atualizados para refletir mudanças
- Documentação deve ser mantida sincronizada

## Troubleshooting

### Problemas Comuns

1. **Permissões não encontradas**
   - Verificar se migrações foram executadas
   - Confirmar existência das permissões no banco

2. **Bypass não funcionando**
   - Validar token JWT (impersonated, roles)
   - Verificar configuração do usuário admin

3. **Plano não reconhecido**
   - Confirmar configuração do tenant
   - Verificar `modules_json` do plano