# Administração de Tenants (Painel Admin)

Este documento descreve as funcionalidades técnicas adicionadas ao painel de administração em `/admin/tenants`, incluindo endpoints de API, modelo de dados no banco administrativo e regras básicas de segurança.

## Banco Administrativo

- Tabelas principais criadas:
  - `tenants(tenant_id, name, contact_email, status, plan_id, access_enabled, created_at, updated_at)`
  - `plans(name, price_cents, cycle, active, modules_json, limits_json, created_at, updated_at)`
  - `payments(tenant_id, amount_cents, status, occurred_at, provider, external_id, notes, created_at)`
  - `tenant_modules(tenant_id, module, enabled)` (overrides por tenant)

Observação: `modules_json` e `limits_json` são JSON (MySQL) / TEXT (SQLite) contendo arrays de módulos e limites.

## Endpoints Principais

- Tenants
  - `GET /api/admin/tenants` — lista de IDs de tenants existentes no servidor (compatibilidade)
  - `GET /api/admin/tenants/summary` — resumo consolidado (registro admin + plano + último pagamento)
  - `POST /api/admin/tenants` — cria tenant (DB) e registra no admin; body `{ tenant_id, name?, contact_email?, plan_id? }`
  - `PUT /api/admin/tenants/{tenant}` — atualiza registro (nome, email, status, plan_id, access_enabled)
  - `DELETE /api/admin/tenants/{tenant}` — remove registro admin e tenta dropar o banco do tenant
  - `POST /api/admin/tenants/{tenant}/access` — alterna acesso `{ enabled: true|false }`
  - `POST /api/admin/tenants/{tenant}/migrate` — migrações completas
  - `POST /api/admin/tenants/{tenant}/migrate-modules` — migrações apenas dos módulos
  - `POST /api/admin/tenants/{tenant}/bootstrap?demo=true` — aplica migrações e semeia dados demo
  - `POST /api/admin/tenants/{tenant}/seed-admin` — semeia admin padrão no tenant
  - `GET /api/admin/tenants/{tenant}/verify-admin` — verifica admins do tenant
  - `GET /api/admin/tenants/{tenant}/audit-auth` — logs de autenticação (tenant)
  - `POST /api/admin/tenants/impersonate` — entra como tenant e redireciona para `/clientes`

- Pagamentos
  - `GET /api/admin/tenants/{tenant}/payments` — lista histórico
  - `POST /api/admin/tenants/{tenant}/payments` — registra pagamento `{ amount_cents, status, occurred_at?, provider?, external_id?, notes? }`

- Planos
  - `GET /api/admin/plans` — lista planos
  - `POST /api/admin/plans` — cria plano `{ name, price_cents, cycle, modules?, limits? }`
  - `PUT /api/admin/plans/{id}` — atualiza plano (campos acima + `active`)
  - `DELETE /api/admin/plans/{id}` — desativa plano (`active = 0`)

- Módulos por Tenant
  - `GET /api/admin/tenants/{tenant}/modules` — obtém overrides
  - `POST /api/admin/tenants/{tenant}/modules` — salva overrides `{ modules: { [moduleName]: true|false } }`

## Segurança

- Todos os endpoints admin exigem autenticação via JWT administrativo (`Authorization: Bearer <token>`), emitido por `POST /api/admin/auth/login`.
- Auditoria de ações administrativas ocorre na tabela `admin_audit_logs`.
- Recomendações adicionais (futuras):
  - Rate Limit para operações sensíveis (`create/delete` de tenants, pagamentos)
  - Inclusão de `request_id` nas respostas
  - Banner claro de sessão administrativa na UI

### Superadministradores (por tenant)

Para garantir privilégios totais permanentes ao usuário `admin@local` (e outros emails designados), foi introduzido o registro de superadministradores no banco do tenant:

- Tabela: `superadmins (id, email UNIQUE, secret_hash, created_at, updated_at)`
- Armazenamento seguro: `secret_hash` utiliza `password_hash` (bcrypt) com salt
- Endpoints:
  - `POST /api/auth/superadmin/register { email, secret? }` — registra/atualiza superadmin (se `secret` for omitido, um segredo aleatório é gerado; o segredo não é retornado)
  - `GET /api/auth/superadmin/status?email=...` — valida se o email está registrado
- Reconhecimento automático: o RBAC (`Rbac::requireRoles`/`requirePermissions`) verifica se o `email` do token está presente em `superadmins` e libera o acesso sem checar permissões/roles
- Fallback de desenvolvimento: `admin@local` é sempre considerado superadmin em ambiente `local` (`APP_ENV=local`)

Observação: O registro é persistente no banco do tenant e se mantém após atualizações e reinicializações, garantindo acesso irrestrito contínuo.

## UI /admin/tenants

- Busca e filtros por status e plano
- CRUD simplificado: criar, editar (nome/email/plano) e excluir tenant
- Gestão de acesso: liberar/bloquear manualmente
- Gestão financeira: histórico e registro de pagamentos
- Ações técnicas: migrações, bootstrap, semear/verificar admin
- Impersonate: botão "Entrar como tenant" configurando sessão do cliente

## Observações de Implementação

- O endpoint `GET /api/admin/tenants` foi mantido por compatibilidade, mas a UI utiliza `GET /api/admin/tenants/summary` para informações consolidadas.
- `modules_json` nos planos define módulos por plano; `tenant_modules` permite overrides por tenant.
- `DELETE /api/admin/tenants/{tenant}` tenta dropar o banco do tenant em MySQL; ambientes SQLite ignoram.