Portal de Equipa como Centro de Comando do Grupo

0 O mais urgente, em primeiro (para o CEO)

1 O que isto é, em três linhas

O portal já existe e está bem construído. O objetivo é fazê-lo crescer de "painel de registo" para o centro de comando do grupo: o sítio onde o CEO vê e controla as 4 lojas, onde cada diretor gere a sua, e onde cada consultor se motiva a cumprir os seus objetivos.

Passa a ser o único sítio de registo e acompanhamento da imobiliária, no lugar dos Excels. Do CRM (X-IMO, crmdsi.pt) só entram automaticamente os leads. A produção (angariações, vendas, CPCVs, visitas) é registada à mão pelo diretor, com o relatório do CRM ao lado.

2 Objetivos do CEO (02 e 03/11/2026)

1. Funcional e automático. Os leads entram sozinhos e o diretor recebe o relatório do CRM automaticamente.
2. Um registo, visível em todas as camadas. Grava-se uma vez, aparece em todo o lado.
3. O consultor vê o quadro completo do seu trabalho. O que está a fazer, o que já fez, e a comparação com a sua produção anterior, com números nos gráficos.
4. Rankings de loja e do grupo Valores. Cada um sabe onde está.
5. Design mais atrativo. Mobile-first. Atrativo de usar, não só funcional.
6. Acabar com os 3 Excels. Portal como único sítio de registo e acompanhamento.

Quem regista o quê (decisão do CEO, 03/11)

3 A fasquia

Referência: sistema de operações de uma rede de mediação europeia de topo (eGO Real Estate, Casafari). Cinco critérios:

1. Cada número tem um dono, e ele está à vista. Ao lado de cada número, o portal mostra quem o registou e quando.
2. Em camadas, por papel. O consultor vê-se a si, o diretor vê a loja, o CEO vê o grupo. Drill-down em todo o lado.
3. Ação, não só relatório. Cada número vermelho traz uma ação ao lado: quem faz, até quando.
4. Indicadores de avanço, não só de resultado. Leads, angariações, visitas, propostas, taxa de conversão entre cada passo.
5. Rápido e no telemóvel. Mobile-first. O registo do diretor e os FSBOs do consultor fazem-se em segundos.

4 O que já está bem (base a manter)

• Login por token em cabeçalho Authorization (resistente a CSRF).
• Três níveis de acesso: LOJA, Diretor, Consultor, CEO.
• Lista de utilizadores trancada só para CEO (403 testado).
• Senha inicial 1234 obriga troca na primeira entrada.
• Gamificação: DS Points, ranking, pódio mensal. Mantém-se e reforça-se.
• Ação "Registar" para o diretor já existe.

5 CRM: só leads e relatório para o diretor

O robô (robo.py) já faz login nos CRM das 4 lojas com conta própria (cofre DS-CacaFSBOs). O portal_import.py já envia leads por /api/fsbo-import.

O que o robô faz (e só isto)

1. Leads para o portal.
2. Relatório do CRM por loja para a área do diretor.
3. FSBOs diários para a aba FSBOs.

Porque não usar a API do X-IMO

Pedir API ao X-IMO abre um precedente de segurança. Não é preciso: o robô usa a conta própria do grupo para ler dados do próprio grupo.

6 Ciclo de faturação e DS Points novo

Estrutura real das comissões (fonte: DSI_final_v2, Drive)

O DSI_final_v2 decompõe os ganhos do consultor em quatro categorias. O portal deve espelhar esta estrutura:

DS Points

• São do grupo Valores e Teorias, não do CRM.
• Fonte: relatório do diretor (regra de 01/11/2026). O robô nunca mete pontos.
• O portal recebe os pontos já calculados pelo diretor, não os recalcula.

Comissões dos consultores

• A comissão decompõe-se em: € Angariação, € Venda, € Dir. Comercial, € Dir. Loja (estrutura do DSI_final_v2).
• O diretor preenche os valores ao registar. O portal mostra o que cada consultor já recebeu e o que está em carteira.

7 Pipeline: estados e pagamento actualizado

O pipeline atual (Excel) tem dois estados. O portal passa a ter três:

Pagamento parcial no CPCV novo

Em alguns negócios a comissão é paga em duas tranches. O portal suporta:

Pipeline atual (dados do Excel, 03/11/2026)

Fonte: pipeline.xlsx lido a 03/11/2026.

8 As três camadas

Camada 1: Consultor (motivar, não burocratizar)

O consultor escreve só duas coisas: os seus objetivos próprios e o seu relatório semanal. Tudo o resto é leitura.

• Barra de progresso rumo aos objetivos próprios.
• Os meus leads (do robô).
• FSBOs atribuídos (ver secção 9).
• Funil: leads, angariações, visitas, propostas, fechados e taxa de conversão por passo.
• Comissão prevista vs recebida (€ Angariação, € Venda, € Dir. — estrutura do DSI).
• Meta do ciclo e ranking na loja e no grupo.
• Histórico completo com comparação (ver secção 10).
• Formação do grupo (acesso à Drive).

Camada 2: Diretor e Loja

• Registo rápido da produção por consultor, com o relatório do CRM ao lado. Rápido no telemóvel.
• Relatório do CRM com aviso de divergência.
• FSBOs da loja com estado por consultor.
• Mapa da equipa: consultor por linha, funil, conversão, atividade da semana.
• Objetivos e relatório semanal de cada consultor.
• Alertas acionáveis com responsável e prazo.
• Pipeline da loja por fase.
• Perfil completo de qualquer consultor (ver secção 10).

Camada 3: CEO e Grupo

• As 4 lojas lado a lado: comissão vs 20.000€, angariações, CPCVs, pipeline, tendência.
• Onde está o risco hoje.
• Disciplina de registo: que diretor registou e quando.
• FSBOs do grupo (resumo de todas as lojas).
• Drill-down: loja → diretor → consultor.
• Cada loja contra os 20.000€ mínimos e contra os 60.000€ do grupo.

9 Aba FSBOs no portal novo

Nova aba "FSBOs"

• Lista de FSBOs do dia, por loja e consultor atribuído.
• Data do lote, fonte e número de contactos novos.
• Se o robô falhou, mostrar data do último lote bem-sucedido com aviso.

Ações do consultor em cada FSBO

• Ao clicar qualquer botão, abre campo de descrição livre (até 500 caracteres). Opcional mas recomendado.
• Cada registo guarda: consultor, botão, descrição, data e hora.

O que o diretor e o CEO veem

• Diretor: todos os FSBOs da loja, estado por consultor, alerta de FSBOs sem resposta há mais de X dias.
• CEO: resumo do grupo — total de FSBOs do dia, quantos têm feedback, quantos têm visita marcada, por loja.

Rotas sugeridas

• POST /api/fsbos — só robô (chave de serviço). Carrega lote diário.
• GET /api/fsbos?loja=X&data=YYYY-MM-DD — lista da loja na data.
• POST /api/fsbos/:id/feedback — consultor. Regista botão + descrição.
• GET /api/fsbos/resumo — CEO/Diretor. Totais por loja.

10 Histórico completo do consultor novo

Secção "Agora" — ciclo atual

• Angariações, visitas, propostas, CPCVs, escrituras do ciclo em curso.
• DS Points; comissão recebida (€ Ang. + € Venda + € Dir.) + em carteira.
• Taxa de conversão por passo. Objetivos próprios. Último relatório semanal. FSBOs.

Secção "Histórico" — presente vs passado

• Gráfico de barras: produção por ciclo, últimos 12 meses, com o número em cada barra.
• Gráfico de linha: evolução DS Points mês a mês.
• Gráfico de linha: comissão recebida por ciclo.
• Comparação direta: ciclo atual vs mesmo ciclo do ano anterior.
• Taxa de conversão por ciclo: onde melhorou, onde piorou.

Secção "Registos semanais"

Lista de todos os relatórios semanais submetidos, mais recente primeiro.

Secção "Pipeline pessoal"

Todos os negócios do consultor em carteira, com estado e previsão.

11 Os KPIs certos

12 Design e utilidade actualizado

Cores e tipografia

• Tema escuro. Azul DS #004AAD como cor de destaque. Texto branco.
• Fonte: Gotham Rounded (ou Inter como fallback).
• Gráficos com os números escritos em cada barra/ponto. Medalhas e pódio com mais vida.

Melhorias de utilidade

1. Telemóvel primeiro. Registo do diretor e FSBOs do consultor em segundos.
2. A ação ao lado do número (botões "marcar reunião", "registar" dentro de alertas).
3. Drill-down em todo o lado. Clicar num número leva ao detalhe.
4. Semáforo consistente: vermelho abaixo de 50% da meta do ciclo.
5. Origem à vista: ao pé de cada número, quem registou e quando.

Aprovação do aspeto (Fase 1b)

Antes de alastrar ao portal inteiro, mostrar ao CEO um ou dois ecrãs (consultor + diretor) para aprovação.

13 Segurança

Falha a corrigir: autorização por loja

/api/portal-data devolve dados das 4 lojas a qualquer login. /api/data?key=kanban:outra-loja responde ao Diretor de outra loja.

Correção: em cada pedido, confirmar se a loja pedida está nas lojas do utilizador. Se não, 403. Mesmo mecanismo que já existe em /api/users-list.

Afinações

• Cabeçalhos de segurança (CSP, HSTS, anti-clickjacking) nas regras da Cloudflare.
• Senha inicial 1234 expira em 24–48 horas.

Conta de serviço do robô

Rotas de escrita do robô (/api/fsbo-import, /api/fsbos, relatório CRM) só aceitam a conta de serviço própria do robô. O portal_import.py deixa de usar a conta master do CEO.

Regras de escrita

• Diretor: só regista na sua loja.
• Consultor: só os seus objetivos, relatórios e feedback FSBOs.
• Diretor ou CEO: marcam pagamento no pipeline.
• Cada registo guarda registado_por e registado_em. Alteração guarda valor anterior.

14 Roadmap por fases

15 Decisões tomadas

1. Robô só para leads, relatório CRM e FSBOs (CEO, 03/11).
2. Pipeline com três estados (CEO, 03/11): CPCV Assinado → Escriturado → Pago.
3. Pagamento parcial no CPCV (CEO, 03/11).
4. Ciclo 26 a 25: todos os números respeitam este ciclo, com o período sempre visível.
5. DS Points do relatório do diretor (regra 01/11).
6. Comissão em 4 categorias (estrutura DSI_final_v2): € Angariação, € Venda, € Dir. Comercial, € Dir. Loja.
7. FSBOs com aba própria (CEO, 03/11): 3 botões de feedback + descrição livre.
8. Histórico completo no perfil do consultor (CEO, 03/11): gráficos com números, comparação presente vs passado.
9. Mobile-first (CEO, 03/11).
10. Programador já na Fase 1 (CEO, 03/11): segurança + conta de serviço do robô + Fase 1b do aspeto em paralelo.

16 Modelo de dados mínimo

Utilizador

utilizador {
  id:       string
  user:     string
  nome:     string
  papel:    CEO | diretor | loja | consultor | robo
  lojas:    string[]    // loja_ids acessíveis
}

Registo de produção (pelo diretor)

producao {
  id:                    string
  loja_id:               string
  consultor_id:          string
  tipo:                  angariacao | visita | proposta | cpcv | escritura | venda | arrendamento
  ref_imovel:            string | null
  valor:                 number
  comissao_ang:          number    // € Angariação (estrutura DSI)
  comissao_venda:        number    // € Venda
  comissao_dir_comercial: number   // € Dir. Comercial
  comissao_dir_loja:     number    // € Dir. Loja
  comissao_bruta:        calculado // soma das 4 categorias
  pago_no_cpcv:          number    // 0 ou metade — split de comissão
  pago_na_escritura:     number
  por_receber:           calculado // comissao_bruta − pago_no_cpcv − pago_na_escritura
  estado:                CPCV_Assinado | Escriturado | Pago
  data_cpcv:             date | null
  data_escritura:        date | null
  data_pagamento:        date | null
  ciclo:                 string    // "2026-11" = ciclo 26/10 a 25/11
  registado_por:         utilizador_id
  registado_em:          datetime
  valor_anterior:        object | null
}

FSBO e feedback

fsbo {
  id:           string
  lote_id:      string       // agrupa todos os FSBOs do mesmo dia
  loja_id:      string
  consultor_id: string
  contacto:     object       // nome, telefone, imóvel, fonte
  data_lote:    date
}

fsbo_feedback {
  id:           string
  fsbo_id:      string
  consultor_id: string
  acao:         follow_up | colega | visita
  descricao:    string       // max 500 chars
  data_visita:  datetime | null  // só para acao=visita
  criado_em:    datetime
}

Relatório CRM (robô), objetivo e relatório semanal (consultor)

relatorio_crm {
  id:       string
  loja_id:  string
  data:     date
  linhas:   { consultor_id, tipo, ref_imovel, data }[]
}

objetivo_consultor {
  id:           string
  consultor_id: string
  tipo:         string
  valor_meta:   number
  ciclo:        string
}

relatorio_semanal {
  id:           string
  consultor_id: string
  semana:       string     // "2026-W44"
  conteudo:     object
  criado_em:    datetime
}

Regras de autorização

Leitura: se papel == CEO, passa. Senão, a loja_id pedida tem de estar em utilizador.lojas, ou 403.

Escrita por papel:

• Consultor: objetivos próprios, relatório semanal, feedback FSBOs.
• Diretor: produção, DS Points, comissões e metas — só na sua loja.
• Robô: leads, FSBOs e relatórios CRM. Nada mais.
• Diretor ou CEO: marcar pagamento no pipeline (estado → Pago).
• Toda a escrita guarda registado_por e registado_em. Alteração guarda valor anterior.