Mini CRM Lead Tracker — Diário de Bordo: Laravel Sanctum, Multitenancy e Controle por Perfil: Segurança e Escalabilidade no Mini CRM Lead Tracker

No Dia 6 do projeto Mini CRM Lead Tracker, enfrentei um dos marcos mais críticos de qualquer backend moderno: a autenticação segura. Mas não parei por aí. Estruturei também a base de multitenancy e implementei uma camada de controle de acesso por perfil baseada em papéis (roles), tudo com Laravel 10, usando Sanctum e documentação via Swagger.

📌 O que foi implementado

• Autenticação via Laravel Sanctum com retorno de accessToken
• Middleware EnsureCompanyIsValid para garantir escopo por empresa
• Middleware role:{slug} para validação de perfil (admin, operador, master)
• Seeder de roles, companies e users para testes realistas
• Swagger funcional com autenticação via Bearer Token
• Documentação atualizada no README.md com payloads reais
• Inclusão do campo is_active via migration incremental
• Preparação do arquivo CHANGELOG.md para rastreabilidade técnica

🔐 Sanctum: Token, Segurança e Simplicidade

Escolhi Sanctum porque ele entrega exatamente o que uma API moderna precisa: geração de tokens, suporte a autenticação stateless e integração perfeita com o Laravel. Em vez de reinventar a roda, deixo o core da autenticação simples, seguro e escalável.

🏢 Multitenancy via Middleware

Cada usuário está vinculado a uma empresa (company_id). O middleware EnsureCompanyIsValid garante que o usuário esteja ativo e operando apenas no escopo da sua organização.

if (! $user->is_active || ! $user->company_id) {
  return response()->json(['mensagem' => 'Usuário não autorizado.'], 403);
}

👥 Controle por Perfil com Roles

Implementei uma estrutura de perfis com a tabela roles (admin, operador, master) e middleware genérico role:{slug} que protege rotas com clareza e desacoplamento. Exemplo:

Route::middleware(['auth:sanctum', 'role:admin'])->group(function () {
  Route::get('/admin/painel', ...);
});

É limpo, reutilizável e pronto para escalar com policies específicas quando necessário.

🌱 Seeders completos para testes

Seeders inserem perfis, empresas e usuários ativos de teste automaticamente. Isso acelera o teste local e garante consistência no onboarding de novos devs.

🧾 Migration incremental para is_active

Como o campo is_active não existia no início da modelagem, criei uma migration incremental (ao invés de editar a original), garantindo versionamento limpo e histórico rastreável. Essa decisão é vital para manter a confiabilidade do projeto no longo prazo.

📘 Documentação Swagger com Autenticação

Documentei o endpoint /api/v1/login com payloads reais e habilitei autenticação com Bearer Token diretamente na interface Swagger. Isso reduz tempo de teste e facilita QA e onboarding.

📂 README.md e CHANGELOG.md

Atualizei o README.md com instruções claras para rodar o projeto, seeder de dados reais, autenticação e Swagger. E iniciei o CHANGELOG.md para registrar todas as alterações de forma técnica e auditável.

✅ Resultado final

O Mini CRM Lead Tracker agora tem um sistema de autenticação robusto, com segregação por empresa, controle por perfil e documentação completa. A fundação está sólida para que a escalabilidade venha com segurança e rastreabilidade.

🧠 Lições do Dia 6

• Não existe arquitetura limpa sem controle de acesso bem definido
• Multitenancy exige validação explícita e middleware dedicado
• Roles não são strings soltas: são entidades com estrutura
• Swagger e seeders são ferramentas de documentação viva

📅 Diário de Bordo – Dia 6 concluído!

Próximo passo: CRUD de Empresas com vinculação ao usuário e políticas de acesso mais refinadas. O backend está tomando forma — limpo, rastreável e escalável.