# 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:

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

Ou manualmente:

```sql
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

```json
{
  "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`

```sql
- 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:**
```sql
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