Gestão de Utilizadores

O sistema de gestão de utilizadores permite administrar os acessos e permissões dos utilizadores da plataforma.

Visão Geral

A gestão de utilizadores inclui:

• Listagem e pesquisa de utilizadores
• Criação de novos utilizadores
• Edição de perfis
• Atribuição de roles
• Ativação/desativação de contas
• Reset de passwords

Modelo de Utilizadores

Estrutura de Dados

interface User {
    id: string;
    name: string;
    email: string;
    emailVerified: boolean;
    image?: string;
    createdAt: Date;
    updatedAt: Date;
    roles: Role[];
}

interface Role {
    id: string;
    name: string;
    description?: string;
    permissions: Permission[];
}

interface Permission {
    id: string;
    name: string;
    resource: string;
    action: string;
}

Roles Disponíveis

Role	Descrição	Permissões
Admin	Administrador do sistema	Acesso total a todas as funcionalidades
Editor	Gestor de conteúdo	Gerir biblioteca, ver utilizadores
User	Utilizador padrão	Usar chat, ver próprio perfil

Hierarquia de Permissões

Admin
  └── Editor
        └── User

Funcionalidades

📋 Listagem de Utilizadores

Interface para ver todos os utilizadores do sistema:

┌─────────────────────────────────────────────────────────────────┐
│  Gestão de Utilizadores                    [+ Novo Utilizador]  │
├─────────────────────────────────────────────────────────────────┤
│  🔍 Pesquisar por nome ou email...                              │
│                                                                 │
│  Role: [Todos ▼]    Estado: [Todos ▼]                          │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────┬─────────────────┬─────────────────────┬───────┬────┐ │
│  │ 👤   │ Nome            │ Email               │ Role  │ ⋮  │ │
│  ├──────┼─────────────────┼─────────────────────┼───────┼────┤ │
│  │ [JD] │ João Silva      │ joao@example.com    │ Admin │ ⋮  │ │
│  │ [MS] │ Maria Santos    │ maria@example.com   │ Editor│ ⋮  │ │
│  │ [PO] │ Pedro Oliveira  │ pedro@example.com   │ User  │ ⋮  │ │
│  └──────┴─────────────────┴─────────────────────┴───────┴────┘ │
│                                                                 │
│  Mostrando 1-10 de 45 utilizadores            ◀ 1 2 3 4 5 ▶    │
└─────────────────────────────────────────────────────────────────┘

➕ Criar Utilizador

// tRPC mutation para criar utilizador
create: adminProcedure
  .input(z.object({
    name: z.string().min(2),
    email: z.string().email(),
    password: z.string().min(8),
    roleId: z.string(),
  }))
  .mutation(async ({ ctx, input }) => {
    const hashedPassword = await hash(input.password, 10);

    return ctx.db.transaction(async (tx) => {
      // Criar utilizador
      const [user] = await tx.insert(users).values({
        id: generateId(),
        name: input.name,
        email: input.email,
      }).returning();

      // Criar conta com password
      await tx.insert(accounts).values({
        id: generateId(),
        userId: user.id,
        accountId: user.id,
        providerId: "credential",
        password: hashedPassword,
      });

      // Atribuir role
      await tx.insert(userRoles).values({
        userId: user.id,
        roleId: input.roleId,
      });

      return user;
    });
  }),

✏️ Editar Utilizador

Modal de edição com campos editáveis:

┌─────────────────────────────────────────────────────────────────┐
│  Editar Utilizador                                       [✕]   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  👤 Avatar                                                      │
│  [     ]  [Alterar]                                            │
│                                                                 │
│  Nome                                                           │
│  [João Silva                               ]                   │
│                                                                 │
│  Email                                                          │
│  [joao@example.com                         ]                   │
│                                                                 │
│  Role                                                           │
│  [Admin ▼]                                                     │
│                                                                 │
│  Estado                                                         │
│  [●] Ativo  [ ] Inativo                                        │
│                                                                 │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  📅 Criado em: 15 Jan 2024                                     │
│  📅 Última atualização: 28 Nov 2024                            │
│                                                                 │
│                                [Cancelar] [💾 Guardar]          │
└─────────────────────────────────────────────────────────────────┘

🔐 Reset de Password

Administradores podem resetar passwords de utilizadores:

resetPassword: adminProcedure
  .input(z.object({
    userId: z.string(),
    newPassword: z.string().min(8),
  }))
  .mutation(async ({ ctx, input }) => {
    const hashedPassword = await hash(input.newPassword, 10);

    return ctx.db.update(accounts)
      .set({ password: hashedPassword })
      .where(
        and(
          eq(accounts.userId, input.userId),
          eq(accounts.providerId, "credential")
        )
      );
  }),

🚫 Desativar Utilizador

Soft delete - o utilizador não pode fazer login mas os dados são mantidos:

deactivate: adminProcedure
  .input(z.object({ userId: z.string() }))
  .mutation(async ({ ctx, input }) => {
    // Invalidar todas as sessões
    await ctx.db.delete(sessions)
      .where(eq(sessions.userId, input.userId));

    // Marcar utilizador como inativo
    return ctx.db.update(users)
      .set({
        isActive: false,
        updatedAt: new Date()
      })
      .where(eq(users.id, input.userId));
  }),

Permissões por Ação

Ação	Admin	Editor	User
Listar utilizadores	✅	✅ (só visualizar)	❌
Ver detalhes	✅	✅	Só próprio
Criar utilizador	✅	❌	❌
Editar utilizador	✅	❌	Só próprio (limitado)
Alterar role	✅	❌	❌
Reset password	✅	❌	Própria password
Desativar	✅	❌	❌

Hooks de Utilizador

useSession

const { data: session, isLoading } = useSession();

if (session) {
    console.log(session.user.name);
    console.log(session.user.roles);
}

usePermissions

const { hasPermission, hasRole } = usePermissions();

if (hasRole("admin")) {
    // Mostrar opções de admin
}

if (hasPermission("users", "create")) {
    // Mostrar botão de criar
}

Validações

Regras de Negócio

1. Email único - Não podem existir dois utilizadores com o mesmo email
2. Password forte - Mínimo 8 caracteres
3. Self-protection - Admin não pode desativar a própria conta
4. Último admin - Deve existir pelo menos um admin no sistema

Validação com Zod

const createUserSchema = z.object({
    name: z.string().min(2, "Nome deve ter pelo menos 2 caracteres").max(100, "Nome não pode exceder 100 caracteres"),
    email: z.string().email("Email inválido").toLowerCase(),
    password: z
        .string()
        .min(8, "Password deve ter pelo menos 8 caracteres")
        .regex(/[A-Z]/, "Password deve conter pelo menos uma maiúscula")
        .regex(/[0-9]/, "Password deve conter pelo menos um número"),
    roleId: z.string(),
});

Auditoria

Todas as ações de gestão de utilizadores são registadas:

interface AuditLog {
    id: string;
    userId: string; // Utilizador que realizou a ação
    targetId: string; // Utilizador afetado
    action: string; // "create" | "update" | "deactivate" | etc.
    changes: object; // Alterações realizadas
    ipAddress: string;
    userAgent: string;
    createdAt: Date;
}

Integração com Autenticação

A gestão de utilizadores está integrada com o sistema de autenticação:

1. Criação - Cria user + account automaticamente
2. Desativação - Invalida todas as sessões
3. Reset Password - Atualiza na tabela accounts
4. Alteração de Role - Revalida permissões em todas as sessões

Melhores Práticas

1. Princípio do Menor Privilégio - Atribuir apenas as permissões necessárias
2. Revisão Regular - Auditar acessos periodicamente
3. Passwords Seguras - Implementar políticas de password
4. Logs de Auditoria - Manter histórico de alterações
5. MFA - Considerar autenticação multi-fator para admins