160 lines
3.9 KiB
Markdown
160 lines
3.9 KiB
Markdown
# 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
|