feat: versão 1.5 - CRM Beta com leads, funis, campanhas e portal do cliente

2025-12-24 17:36:52 -03:00
parent 99d828869a
commit dfb91c8ba5
98 changed files with 18255 additions and 1465 deletions
--- a/docs/COLABORADORES_SETUP.md
+++ b/docs/COLABORADORES_SETUP.md
@@ -0,0 +1,159 @@
+# 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