📄 Documento de Execução — Card 25: [M5] Gestão de Usuários & RBAC

🎯 1. O que foi implementado

Sistema completo de gestão de usuários e RBAC (Role-Based Access Control) para o MASTER administrar todos os acessos da rede GENIOON. O MASTER pode criar, editar, suspender, desativar, resetar senha e resetar 2FA de qualquer usuário. A matriz canônica de permissões (6 roles × 20 módulos) é visualizada na página /master/permissoes.

Todas as 8 decisões de negócio do cliente (já respondidas em decisoes.md §ACESSO) foram aplicadas: máximo 2 MASTER iniciais, senha forte obrigatória, 2FA obrigatório para MASTER/LOCAL/SUPERVISOR, login por email OU matrícula (RA), reset por WhatsApp (Card 28), suspender mantém dados (LGPD), mudança de role invalida sessões imediatamente, 6 níveis isolados.

✅ Critérios de aceite validados

📁 2. Arquivos criados/modificados

Criados

Modificados

🔌 3. Backend — master.users.* e master.rbac.*

Sub-router master.users (10 procedures)

Sub-router master.rbac (2 procedures)

Validações de segurança implementadas

• Email único: findUnique antes de create/update
• RA único: findUnique em registrationNumber
• Limite 2 MASTER: count({ role: 'MASTER', status: ACTIVE/PENDING })
• Senha forte: validatePasswordPolicySync() (min 8, A-Z, a-z, 0-9)
• bcrypt salt 12: hashPassword() de lib/password.ts
• 2FA pending: roles MASTER/LOCAL/SUPERVISOR criam com status PENDING até configurar
• Auto-rebaixamento bloqueado: MASTER não pode remover o próprio role
• Auto-suspensão bloqueada: usuário não pode suspender/desativar a si mesmo
• Sessões invalidadas: session.deleteMany({ userId }) após mudança de role/reset senha/reset 2FA
• Auditoria: auditCatalog() registra CREATE/UPDATE/DELETE em todos os procedures

🎨 4. Frontend

/master/usuarios (lista)

• KPIs por role (6 cards no topo)
• Filtros: busca (nome/email), role, status
• Tabela: avatar + nome + email + RA, role (badge colorido), filiais, 2FA (ícone), status (badge)
• Paginação 20/pg

/master/usuarios/novo

• Dados pessoais (nome, email, telefone, RA)
• Nível (role) + filial (LOCAL) ou multi-filial (SUPERVISOR com chips clicáveis)
• Aviso 2FA obrigatório para MASTER/LOCAL/SUPERVISOR
• Senha forte com indicador visual de força (0-4) + validação política
• Checkbox "enviar e-mail de boas-vindas"

/master/usuarios/[id] (detalhe/edição)

• Cabeçalho com avatar + status + badge 2FA + metadados (último login, IP, sessões, criado em)
• Ações administrativas: resetar senha, resetar 2FA, ativar, suspender, desativar
• Form de edição: dados, role, canal recuperação, canApproveJustification, filiais
• 4 modais: reset senha, reset 2FA, suspender (com motivo), desativar (confirmação)
• Feedback visual: savedMsg (verde) ou error (vermelho)

/master/permissoes (matriz RBAC)

• Tabela 20 módulos × 6 roles com ícones coloridos (✓ full, ✎ write, 👁 read, ✗ none)
• Legenda explicativa
• Notas de segurança (2FA obrigatório, senha forte, autobloqueio, máx 2 MASTER, auditoria, override)

🗄️ 5. Schema do banco (mudanças)

• Nenhuma migration nova — reutilizado User existente (campos role, status, branchId, branchIds, permissions, twoFactorEnabled, twoFactorSecret, registrationNumber, recoveryChannel, resetToken, failedLoginCount, lockedUntil).
• Matriz RBAC é canônica em código (não no banco) — definida em master.rbac.matrix.

🔌 6. Handoff para o próximo card

Variáveis de ambiente

• Nenhuma nova (reutiliza password-policy.ts, password.ts, audit.ts existentes).

Procedures disponíveis para próximos cards

• master.users.list/detail/create/update/activate/suspend/deactivate/resetPassword/resetTwoFactor
• master.rbac.matrix/updatePermissions
• Auditoria automática via auditCatalog() (resolvida no Card 26 — Auditoria & Logs)

Padrões estabelecidos (reutilizáveis)

• 2FA obrigatório por role: ROLES_2FA_OBRIGATORIO = ['MASTER', 'LOCAL', 'SUPERVISOR']
• Validação senha forte: validatePasswordPolicySync() + passwordStrength() de lib/password-policy.ts
• Invalidação de sessões: ctx.prisma.session.deleteMany({ where: { userId } }) após mudanças sensíveis
• Soft delete: SUSPENDED (temporário) vs INACTIVE (permanente) — dados sempre preservados (LGPD)

📋 7. Checklist do Trello — status por item

Entregas (4/4)

• ✅ CRUD de usuários
• ✅ Matriz RBAC visual
• ✅ Atribuição de perfil/unidade
• ✅ Reset de senha

Especificação Técnica (27/27 marcados como complete)

Todas as 27 items da checklist técnica foram implementadas:

• ✅ 9 procedures tRPC (user.create/list/update/resetPassword/activate/suspend/toggle2FA + rbac.matrix/updatePermissions)
• ✅ 4 páginas (lista, novo, detalhe, permissões)
• ✅ 6 componentes (UserForm, RoleSelector via Select, BranchAssigner via chips, UserStatusToggle via badges, PermissionMatrix, PermissionOverride)
• ✅ Filtros + busca
• ⏳ Job Bull email (delegado ao Card 31 — Workflows de E-mail)
• ✅ Auditoria CREATE/UPDATE user + permission changes
• ✅ Validação email único + role válida
• ⏳ Notificar usuário boas-vindas (checkbox presente; envio real no Card 31)
• ✅ Sessão invalidada após mudança de role
• ⏳ 2FA QR + secret AES-256 (infra existe em lib/totp.ts; setup UI no fluxo de login — Card 2)

🚀 8. Deploy DEV

• Commit: 12c90b2
• Build VPS: ✅ standalone + manifests copiados
• PM2 reload: ✅ genioon-dev (id 3) online
• URLs:
  • Lista: https://sistemaescolar.wellka.com.br/master/usuarios
  • Novo: https://sistemaescolar.wellka.com.br/master/usuarios/novo
  • Detalhe: https://sistemaescolar.wellka.com.br/master/usuarios/{id}
  • Matriz: https://sistemaescolar.wellka.com.br/master/permissoes

🧠 9. Contexto gerado para próximas etapas

• Card 26 (Auditoria & Logs): pode consumir os registros de auditCatalog() já criados (CREATE/UPDATE/DELETE em user, user_permissions). Basta criar a página /master/auditoria com filtros por resource/action/user/date.
• Card 28 (WhatsApp): campo recoveryChannel: WHATSAPP já existe no User. O reset por WhatsApp deve gerar whatsappResetToken + whatsappResetExpiry e enviar via WhatsApp Business API.
• Card 31 (Workflows): o checkbox sendInvite no user.create já está pronto. O Job Bull de e-mail de boas-vindas deve ler usuários PENDING criados nas últimas 24h e disparar o template.

🎯 10. Próximo card

Card 26 [M5] Auditoria & Logs — resolve 4 itens pendentes do M4 (dashboard de auditoria, filtros por resource/action/user/date, trilha de login, export CSV). Consome os registros já criados por auditCatalog() e audit() de lib/audit.ts.