aggios.app/docs/COLABORADORES_SETUP.md

Sistema de Hierarquia de Usuários - Guia de Configuração

Visão Geral

O sistema implementa dois tipos de usuários para agências:

1. Dono da Agência (owner) - Acesso total

   • Pode convidar colaboradores
   • Pode remover colaboradores
   • Tem acesso completo ao CRM

2. Colaborador (collaborator) - Acesso Restrito

   • Pode VER leads e clientes
   • NÃO pode editar ou remover dados
   • Acesso somente leitura (read-only)

Configuração Inicial

Passo 1: Configurar o primeiro usuário como "owner"

Após criar a primeira agência e seu usuário admin, execute o script SQL:

docker exec aggios-postgres psql -U postgres -d aggios < /docker-entrypoint-initdb.d/../setup_owner_role.sql

Ou manualmente:

UPDATE users 
SET agency_role = 'owner'
WHERE email = 'seu-email@exemplo.com' AND role = 'ADMIN_AGENCIA';

Passo 2: Login e acessar o gerenciamento de colaboradores

1. Faça login com o usuário owner
2. Vá em Configurações > Equipe
3. Clique em "Convidar Colaborador"

Passo 3: Convidar um colaborador

• Preencha Nome e Email
• Clique em "Convidar"
• Copie a senha temporária (16 caracteres)
• Compartilhe com o colaborador

Fluxo de Funcionamento

Quando um Colaborador é Convidado

1. Novo usuário é criado com agency_role = 'collaborator'
2. Recebe uma senha temporária aleatória
3. Email é adicionado à agência do owner

Quando um Colaborador Faz Login

1. JWT contém "agency_role": "collaborator"
2. Frontend detecta a restrição
   • Botões de editar/deletar desabilitados
   • Mensagens de acesso restrito
3. Backend bloqueia POST/PUT/DELETE em /api/crm/*
   • Retorna 403 Forbidden se tentar

Dados no JWT

{
  "user_id": "uuid",
  "user_type": "agency_user",
  "agency_role": "owner",  // ou "collaborator"
  "email": "usuario@exemplo.com",
  "role": "ADMIN_AGENCIA",
  "tenant_id": "uuid",
  "exp": 1234567890
}

Banco de Dados

Novos Campos na Tabela users

- agency_role VARCHAR(50)           -- 'owner' ou 'collaborator'
- created_by UUID REFERENCES users  -- Quem criou este colaborador
- collaborator_created_at TIMESTAMP -- Quando foi adicionado

Endpoints da API

Listar Colaboradores

GET /api/agency/collaborators
Headers: Authorization: Bearer <token>
Resposta: Array de Collaborators
Restrição: Apenas owner pode usar

Convidar Colaborador

POST /api/agency/collaborators/invite
Body: { "email": "...", "name": "..." }
Resposta: { "temporary_password": "..." }
Restrição: Apenas owner pode usar

Remover Colaborador

DELETE /api/agency/collaborators/{id}
Restrição: Apenas owner pode usar

Página de Interface

Localização: /configuracoes → Aba "Equipe"

Funcionalidades

• ✅ Ver lista de colaboradores (dono apenas)
• ✅ Convidar novo colaborador
• ✅ Copiar senha temporária
• ✅ Remover colaborador (com confirmação)
• ✅ Ver data de adição de cada colaborador
• ✅ Indicador visual (badge) do tipo de usuário

Troubleshooting

"Apenas o dono da agência pode gerenciar colaboradores"

Causa: O usuário não tem agency_role = 'owner'

Solução:

UPDATE users 
SET agency_role = 'owner'
WHERE id = 'seu-user-id';

Colaborador consegue editar dados (bug)

Causa: A middleware de read-only não está ativa

Status: Implementada em backend/internal/api/middleware/collaborator_readonly.go

Para ativar: Descomente a linha em main.go que aplica CheckCollaboratorReadOnly

Senha temporária não aparece

Verificar:

1. API /api/agency/collaborators/invite retorna 200?
2. Response JSON tem o campo temporary_password?
3. Verificar logs do backend para erros

Próximas Melhorias

• Permitir editar nome/email do colaborador
• Definir permissões granulares por colaborador
• Histórico de ações feitas por cada colaborador
• 2FA para owners
• Auditoria de quem removeu quem