Colliers × Costal — Interno

Spec: Inteligência de Mercado Colliers

Leitura de 22 min

Spec | Inteligência de Mercado Colliers

spec colliers inteligencia-mercado

Autor: Pedro Villa Status: Rascunho v3.1 — modelo de dados ampliado com hierarquia temporal de geometria + dimensão de tracking histórico de proprietário (devolutiva pt2 07/05) Última atualização: 2026-05-13 — incorporação de achados da devolutiva pt2 com Braga (07/05) Próxima iteração: Pedro publica v3 completa na wiki → Leandro + Daniel revisam assincronamente → reunião pré-execução pós-retorno de Daniel Empresa: colliers Documentos-filho: Dicionário de dados as-is · Análise AS-IS vs. TO-BE

v2 (25/04): spec atualizada após análise direta da planilha modelo enviada por Braga. O ER inferido na v1 (5 entidades) foi substituído pelo modelo observado e o to-be amadureceu para 9 entidades. A análise revelou 27 problemas estruturais documentados no dicionário — o problema é mais grave (e a oportunidade maior) do que parecia em 24/04.

v3 (06/05): evolução do modelo de dados pós-devolutiva 05/05 com Braga. O modelo v2 tratava subdivisão como entidade única de dois níveis (andar/conjunto OU galpão/módulo), o que não resolve a geometria variável de subdivisões reais — Braga apontou como “calcanhar de Aquiles”. A v3 separa em 5 níveis temporais explícitos: Imóvel-base (estável) → Estrutura Física (versionada por reforma) → Agrupamento Comercial (versionada por período de oferta/contrato) → Subdivisão Terminal (unidade locada efetiva) → Ocupação (trimestre). Detalhe canônico em §“Modelo v3 — hierarquia temporal de geometria” abaixo.

Asset paralelo já em produção (desde 04/2026 — pré-projeto): Ferramenta Anouk de Inteligência de Mercado FII/CVM — dashboard com dados públicos da CVM (fundos imobiliários) que cobre análise dimensão complementar à planilha Excel as-is do Braga. Apresentada para Ricardo em 08/04 (ata), publicada para a equipe Colliers em 10/04, com Leandro Braga como “pai da criança” (interlocutor primário). Capacidades atuais: análise por fundo (BTGP Logística como caso-âncora) com score de compra · ranking de 356 fundos com caixa crescente (candidatos a abordagem comercial) · radar de oportunidades por segmento (Logística e Shopping em alta; Residencial/Varejo/Saúde em baixa) · vacância crítica por fundo · geolocalização de transações · módulo IA com resumos básicos. Próximo passo definido em 08/04: aplicar cap rate para estimar valor das transações (limitado hoje pelo problema de FK ausente — ver §1.4 abaixo). A spec to-be do Lakehouse deve integrar este asset (não duplicar): a ferramenta FII/CVM consome dados externos públicos; a planilha Braga é dado interno proprietário Colliers. Ambos convergem no Gold do Lakehouse.

Problema

A Colliers opera um produto de pesquisa e inteligência de mercado que é ativo comercial crítico — suporta pitches de exclusividade de comercialização e gera prospecção de cauda longa (inquilinos cujos contratos expirarão em 3 anos). Entrega valor hoje, com painel Power BI em operação.

O problema é que esse ativo vive sob arquitetura frágil. Após análise direta da planilha modelo (25/04), os problemas se confirmam e se ampliam:

  1. Armazenamento: 100% em Excel (~290k–700k linhas estimadas, histórico 10 anos desde 2016) — sem versionamento canônico, sem backup estruturado, sem redundância. “Fé na Microsoft” foi a palavra do próprio Leandro.
  2. Documentação: sem dicionário de dados. Conhecimento da estrutura é 100% tácito em Leandro Braga. Foi necessário inferir o modelo a partir da planilha — agora documentado no dicionário.
  3. Modelagem: 27 problemas estruturais identificáveis a olho nu, agrupados em 8 categorias (denormalização, inconsistência de schema cross-segmento, falta de chave estrangeira, derivados armazenados como dados, conceitos sobrepostos, tipos misturados, erros tipográficos em headers, sem schema validation). Detalhe em análise AS-IS vs. TO-BE.
  4. Falta de chave estrangeira (CRÍTICO): transações de VENDA LOGÍSTICA não têm ID — match por texto livre. VENDA OFFICE tem ID mas em faixa diferente da FICHA TÉCNICA, inutilizável como FK. Resultado: 10 anos de histórico de transações estão tecnicamente desligados do cadastro de imóveis. Análises de cap rate por ativo, série histórica de preço por imóvel — perdidas.
  5. Inconsistência cross-segmento: Office e Logística usam nomes diferentes para a mesma chave (ID / ID_Novo / ID_Colliers), para latitude/longitude (Lat/long vs. Latitude/Longitude), para conceitos comerciais. Schemas divergem mesmo onde o domínio é o mesmo.
  6. Modelo rígido: mudanças naturais da realidade (um módulo de 2.000m² ocupado por 1.500m² → vira módulo 1A + 1B) são representadas com tipos misturados (“All” + “M.01” na mesma coluna).
  7. Artefatos dispersos: PDFs, fotos, books de imóveis ficam em pastas locais nomeadas pelo imóvel; match por nome quebra quando o imóvel é vendido e renomeado.
  8. Universo limitado: só monitora imóveis de alto padrão profissionalizados (fundos, grandes proprietários). Universo B/C (galpões pequenos, prédios médios, monousuários) está fora do radar — cauda longa comercial não explorada.
  9. Erros tipográficos contagiosos: o header Preҫo (com Ҫ cirílico, U+04AA, em vez de Ç latino) aparece em VENDA OFFICE e VENDA LOGÍSTICA. Quem busca “Preço” não encontra. Bug silencioso.

Risco crítico: perda do arquivo Excel = perda de 10 anos de histórico irrecuperável. A cada trimestre que passa sem migração, a base ganha mais inconsistências e a remediação fica mais cara.

Proposta

Migrar a base atual para uma arquitetura Data Lakehouse em três camadas (Bronze / Silver / Gold), com remodelagem disciplinada na camada Silver (não basta migrar de prateleira mantendo o estrago), preservando 100% da funcionalidade atual do Power BI e adicionando:

  1. Modelo canônico unificado (9 entidades) substituindo as 8 abas atuais — ver to-be.
  2. Versionamento canônico do dado (trilha histórica imutável em Bronze; mudanças em Silver auditadas).
  3. Dicionário de dados formalizado e mantido — primeira versão já em inteligencia-mercado-dicionario.
  4. Reconciliação de transações de venda ao cadastro de imóveis (fuzzy match + revisão humana, one-shot) — destrava 10 anos de série temporal hoje desligados.
  5. Integração com SiiLa, Buildings e CVM (chaves já presentes na FICHA TÉCNICA — ETL trivial; é oportunidade gratuita).
  6. Enriquecimento automático com fontes externas adicionais (Receita Federal, CAGED/RAIS).
  7. Métricas derivadas em Silver (Absorção, Devolução, Vacância, Eficiência, Preço Ponderado) — calculadas, não armazenadas.
  8. Agentes proativos de descoberta e monitoramento (reuso dos agentes Hunter e Trace da Onda 1 Costal).
  9. Cobertura expandida para o universo B/C (sem monitoramento humano — ingestão automatizada).
  10. Interface de cadastro para manutenção da camada Silver (sem obrigar o operador a editar Excel; com schema validation).

Requisitos

Funcionais

  1. F-01 — Ingerir o Excel atual em Bronze preservando 100% dos dados e estrutura, em cadência mínima trimestral.
  2. F-02 — Tratar e normalizar os dados em Silver: chaves canônicas de imóvel, resolução de renomeações, deduplicação, validação de tipos.
  3. F-03 — Enriquecer em Silver com dados externos: abertura/fechamento de filiais (Receita Federal), contratação/demissão por CEP (CAGED/RAIS), portfólios de fundos imobiliários (CVM).
  4. F-04 — Servir em Gold um conjunto de views que o Power BI atual consome sem perda de funcionalidade.
  5. F-05 — Oferecer uma interface de cadastro para input manual (web form ou app) que substitua edição direta do Excel e tenha validação no input.
  6. F-06 — Suportar modelo de imóvel hierárquico: Complexo → Galpão/Edifício → Módulo/Laje, com versionamento temporal das subdivisões.
  7. F-07 — Associar artefatos (PDFs, fotos, books, análises) por chave canônica de imóvel, não por nome de pasta.
  8. F-08 — Permitir que agentes proativos monitorem sinais externos e alimentem automaticamente candidatos a novos imóveis, novas ocupações, e alertas de movimentação (ex.: empresa X abriu filial no CEP Y).
  9. F-09 — Suportar a feature “batalha de imóveis” descrita pelo Leandro: comparação lado a lado de 2–3 ativos com indicadores normalizados.

Não-funcionais

  1. NF-01 — Preservar acesso uninterrupted ao Power BI atual durante a migração.
  2. NF-02 — Backup canônico diário a partir do dia 1 da ingestão em Bronze.
  3. NF-03 — Latência de atualização trimestral aceitável; para dados enriquecidos externos, atualização mensal.
  4. NF-04 — Controle de acesso granular — dados brutos só visíveis para Leandro Braga, Ricardo Betancourt e time técnico Anouk sob NDA.
  5. NF-05 — Auditabilidade: toda modificação em Silver e Gold rastreada com autor, data e origem.

Arquitetura / Design

Arquitetura alvo (to-be)

graph TB
    subgraph "Camada 0 — Fontes"
        S1[Excel atual<br/>~600k linhas]
        S2[Receita Federal<br/>via Base dos Dados]
        S3[CAGED + RAIS<br/>por CEP]
        S4[CVM Fundos<br/>Imobiliários]
        S5[Input manual<br/>via formulario]
        S6[Agentes proativos<br/>Hunter / Trace]
    end

    subgraph "Bronze — raw, imutavel"
        B1[imoveis_bronze]
        B2[temporal_bronze]
        B3[venda_bronze]
        B4[locacao_bronze]
        B5[controle_bronze]
        B6[externos_bronze<br/>CNPJ/CAGED/CVM]
    end

    subgraph "Silver — canonico, enriquecido"
        V1[imoveis_silver<br/>chave canonica + hierarquia]
        V2[serie_temporal_silver]
        V3[ocupacoes_silver<br/>com proxy de inquilino]
        V4[empresas_silver<br/>via CNPJ]
        V5[artefatos_silver<br/>PDFs/fotos]
    end

    subgraph "Gold — views para consumo"
        G1[painel_mercado_view]
        G2[batalha_imoveis_view]
        G3[sinais_proativos_view]
        G4[prospects_caudalonga_view]
    end

    S1 --> B1 & B2 & B3 & B4 & B5
    S2 & S3 & S4 --> B6
    S5 --> B1 & B2
    S6 --> B6

    B1 & B2 & B3 & B4 & B5 --> V1 & V2 & V3 & V5
    B6 --> V4

    V1 & V2 & V3 & V4 & V5 --> G1 & G2 & G3 & G4

    G1 --> PBI[Power BI existente]
    G2 --> PBI
    G3 --> AG[Alertas para equipe comercial]
    G4 --> CRM[CRM / prospecção]

Modelo de dados alvo (real, pós-análise da planilha)

9 entidades no Silver canônico, derivadas das 8 abas Bronze por segmento. Ver análise para o detalhe.

#EntidadeGranularidadeSubstitui (no AS-IS)Por que
1imovel1 linha por imóvelFICHA TÉCNICA OFFICE + FICHA TÉCNICA LOGÍSTICAPK unificada id_imovel; mapa de equivalência guarda ID/ID_Novo/ID_Colliers herdados
2subdivisao1 linha por subdivisão (andar+conjunto OU galpão+módulo)(parte de) BASE OFFICE + BASE LOGÍSTICApolimórfica via tipo_subdivisao enum; atributos comuns + opcionais por tipo
3ocupacao1 linha por (subdivisao, trimestre)(parte de) BASE OFFICE + BASE LOGÍSTICAsérie temporal canônica; absorção/devolução/vacância derivados
4empresa1 linha por empresaas 4 colunas confusas de papel comercialtabela canônica para Proprietário, Administradora, Comercializadora, Ocupante, Locadora — papéis tipados
5empresa_imovel_papel1 linha por (empresa, imovel, papel, periodo)implícito hojetabela de relacionamento com período de validade
6transacao1 linha por transaçãoVENDA OFFICE + VENDA LOGÍSTICAvenda + locação fechada; FK obrigatória para imovel (com fuzzy match no bootstrap)
7fonte_pesquisa1 linha por (imovel, contato)CONTROLE OFFICE + CONTROLE LOGÍSTICAsepara CRM mini do status de pesquisa
8ext_siila1 linha por chave SiiLacolunas ID_SiiLa/Nome_SiiLa em FICHAreconciliação automatizada (chave já existe)
9ext_buildings1 linha por chave Buildingscolunas ID_Buildings/Nome_Buildings em FICHAreconciliação automatizada

Tabelas auxiliares de enriquecimento externo (não contam como entidades de negócio): ext_fundos_cvm (via Ticker fundo), ext_receita_cnpj (filiais por CEP), ext_caged_rais (movimentação trabalhista por CEP).

Decisões de modelagem a validar com Braga em 30/04:

  1. Unificar Office + Logística no Silver (subdivisao polimórfica) — recomendação: SIM, com atributos opcionais por tipo. Detalhe em decisão 1.
  2. Como tratar VENDA LOGÍSTICA sem ID — recomendação: bootstrap fuzzy match + revisão humana, depois disciplina nova. Detalhe em decisão 2.
  3. Re-segmentação de módulos — versionamento temporal em subdivisao com ID estável e atributos mutáveis por período.
  4. Cap Rate normalizado para decimal (Office já está; Logística migrar).
  5. Saída prevista vira coluna estrutural em ocupacao (hoje só existe em CONTROLE OFFICE; estender para Logística).
  6. Eliminação de typos cirílicos em headers já no Bronze.

Modelo v3 — Hierarquia temporal de geometria (NOVO 06/05)

Por que v2 não resolve

A v2 assumia que subdivisão (andar+conjunto ou galpão+módulo) era a unidade canônica de modelagem. A planilha do Braga já mostra mistura “All” + “M.01” na mesma coluna — a vida real é mais fluida que isso. Cenários que quebram o modelo v2:

CenárioPor que v2 quebra
Office: andar 1,2,3,4 em Q1 → 1B,2,3,4 em Q2 (cliente alugou só fração do conjunto 1)“Conjunto 1” deixa de existir e nasce 1A+1B — sem chave estável, série temporal se perde
Logística: galpão de 10.000m² (5 módulos × 2.000m²) → inquilino de 1.000m² (não respeita modulação)Módulos físicos não casam com módulos comerciais — relacionamento N:M temporal sem entidade que medeia
BH “saletas”: andar com 6+ saletas mudando arbitrariamenteSem hierarquia consistente — força-fit em “andar/conjunto” gera tipos misturados
Reforma estrutural: armazém 2 galpões → 3 galpõesMudança física do imóvel não tem ponto de versão — vira nova FICHA TÉCNICA, perde rastreabilidade
Fusão comercial: cliente aluga conjuntos 1+2+3 inteiros (3 conjuntos físicos = 1 contrato)Não há entidade que represente o “conjunto comercial 1+2+3”

Princípio canônico v3

Separar 3 noções de “subdivisão” que hoje vivem misturadas:

  1. Geometria física do imóvel (paredes estruturais, andares, módulos como construídos) — muda raramente, só em reforma estrutural
  2. Geometria comercial (como o ativo é ofertado/dividido para o mercado num período) — muda com frequência média, a cada nova oferta/contrato
  3. Unidade locada efetiva (m² real comercializado, base de medição) — muda a cada novo contrato

E o Imóvel-base é estável (lote/CEP/endereço/proprietário) — versionado só em casos extremos (desmembramento de matrícula, fusão de imóveis).

ER simplificado v3

erDiagram
    IMOVEL ||--o{ ESTRUTURA_FISICA_VERSAO : "tem versões"
    ESTRUTURA_FISICA_VERSAO ||--o{ ESTRUTURA_FISICA_PARTE : "contém partes"
    IMOVEL ||--o{ AGRUPAMENTO_COMERCIAL : "é ofertado como"
    AGRUPAMENTO_COMERCIAL }o--o{ ESTRUTURA_FISICA_PARTE : "link N:M com proporção"
    AGRUPAMENTO_COMERCIAL ||--o{ SUBDIVISAO_TERMINAL : "comercializado via"
    SUBDIVISAO_TERMINAL ||--o{ OCUPACAO : "ocupação trimestral"
    IMOVEL ||--o{ EMPRESA_IMOVEL_PAPEL : "tem empresas com papéis"
    EMPRESA ||--o{ EMPRESA_IMOVEL_PAPEL : ""
    IMOVEL ||--o{ TRANSACAO : "compra/venda/locação"
    OCUPACAO }o--|| EMPRESA : "ocupada por"

    IMOVEL {
        string id_imovel PK
        array aliases
        string endereco
        string tipo
    }
    ESTRUTURA_FISICA_VERSAO {
        string id_versao PK
        string id_imovel FK
        date valido_de
        date valido_ate
        string motivo_versao
    }
    AGRUPAMENTO_COMERCIAL {
        string id_agrupamento PK
        string id_imovel FK
        string status
        date valido_de
        date valido_ate
    }
    SUBDIVISAO_TERMINAL {
        string id_subdivisao PK
        string id_agrupamento FK
        number m2_terminal
    }
    OCUPACAO {
        string id_ocupacao PK
        string id_subdivisao FK
        string trimestre
        string ocupante_anon
    }

Hierarquia v3 — 5 níveis com versionamento temporal explícito

graph TB
    subgraph IMOV["Nível 1 — IMÓVEL (estável)"]
        I[imovel<br/>id_imovel<br/>endereço · CEP · lote · proprietário]
    end

    subgraph EF["Nível 2 — ESTRUTURA FÍSICA (versionada por reforma)"]
        EF_V["estrutura_fisica_versao<br/>id_imovel + valido_de + valido_ate<br/>nº andares · nº módulos físicos · ABL bruta · m² total"]
        EF_PARTE["estrutura_fisica_parte<br/>id_estrutura + tipo<br/>(andar · galpão · módulo físico · saleta)"]
    end

    subgraph AC["Nível 3 — AGRUPAMENTO COMERCIAL (versionado por período de oferta/contrato)"]
        AC_V["agrupamento_comercial<br/>id_agrupamento + valido_de + valido_ate<br/>nome comercial · m² ofertado · status (ofertado · ocupado · em obras · vago)"]
        AC_LINK["agrupamento_estrutura_link<br/>tabela N:M com proporção m²<br/>(quanto cada parte física compõe o agrupamento)"]
    end

    subgraph ST["Nível 4 — SUBDIVISÃO TERMINAL (unidade locada efetiva)"]
        ST_T["subdivisao_terminal<br/>id_subdivisao + id_agrupamento + valido_de + valido_ate<br/>m² real comercializado<br/>(pode ser = ao agrupamento OU fração)"]
    end

    subgraph OC["Nível 5 — OCUPAÇÃO (série temporal trimestral)"]
        O[ocupacao<br/>id_subdivisao + trimestre<br/>ocupante · valor · status · saída prevista]
    end

    I --> EF_V
    EF_V --> EF_PARTE
    I --> AC_V
    EF_PARTE --> AC_LINK
    AC_V --> AC_LINK
    AC_V --> ST_T
    ST_T --> O

Definições canônicas

Nível 1 — imovel

A unidade estável do modelo. É o imóvel como entidade jurídica/física macro: edifício, complexo, galpão.

AtributoTipoNotas
id_imovelstring PKID canônico Colliers
aliasesarrayIDs herdados (Sila, Buildings, antigo Colliers)
enderecostringCEP/lat/long oficiais
tipoenumoffice · logistica · industrial · varejo · residencial · outro
proprietario_atualFK empresasérie histórica vai em empresa_imovel_papel

Versiona apenas em: desmembramento de matrícula · fusão de imóveis · venda total a novo proprietário (opcional — pode ser registrada via empresa_imovel_papel sem nova versão).

Nível 2 — estrutura_fisica_versao + estrutura_fisica_parte

Captura a geometria física construída do imóvel num período. Versão muda quando há reforma estrutural (novo andar construído, galpão expandido, ala demolida).

TabelaAtributosNotas
estrutura_fisica_versaoid_imovel · versao · valido_de · valido_ate · descricao_mudanca · m2_total · n_andares · n_modulos_fisicos1 linha por versão estrutural do imóvel
estrutura_fisica_parteid_parte · id_estrutura_fisica_versao · tipo · nome_fisico · m2_fisica · nivel_hierarquicotipo: andar · conjunto_fisico · galpao · modulo_fisico · saleta · outro

Princípio: a parte física é imutável dentro de uma versão. Se a parede cair, é nova versão da estrutura física.

Nível 3 — agrupamento_comercial + agrupamento_estrutura_link

Captura como o imóvel está sendo ofertado/dividido para o mercado num período. Esta é a entidade que resolve o calcanhar de Aquiles.

TabelaAtributosNotas
agrupamento_comercialid_agrupamento · id_imovel · nome_comercial · m2_ofertado · status · valido_de · valido_ate · motivo_versaostatus: ofertado · ocupado · em_obras · vago
agrupamento_estrutura_linkid_agrupamento · id_parte_fisica · m2_proporcaoN:M — um agrupamento pode usar fração de uma parte física, ou agregar múltiplas partes

Versiona quando:

  • Cliente aluga só fração de um conjunto físico (1.000m² do módulo 2.000m²)
  • Cliente aluga combinação de conjuntos (1+2+3 inteiros)
  • Imóvel passa de “1 contrato grande” para “5 contratos pequenos” (re-segmentação comercial)
  • Cliente devolve, imóvel volta a ofertar com nova divisão

Motivo da versão (auditoria): novo contrato · devolução · nova oferta de mercado · re-segmentação · BH-style ad-hoc.

Nível 4 — subdivisao_terminal

Unidade efetivamente medida/comercializada num contrato. Pode ser:

  • 1:1 com agrupamento (cliente alugou exatamente o agrupamento ofertado)
  • fração do agrupamento (cliente sub-locou 500m² dos 2.000m² ofertados)
AtributoTipo
id_subdivisaoPK
id_agrupamentoFK
m2_terminalnúmero
valido_de / valido_atedata

Nível 5 — ocupacao

Série temporal canônica: 1 linha por (subdivisão_terminal, trimestre). Mantido como na v2 — só muda a FK (agora aponta para subdivisao_terminal, não direto para subdivisao).

AtributoTipo
id_ocupacaoPK
id_subdivisao_terminalFK
trimestrestring YYYY-Q[1-4]
ocupante_anonstring · mascarado
ocupante_realFK empresa · acesso restrito
valor_locacaonúmero
statusenum: ocupado · vago · em_obras
saida_previstadate · opcional
confianca_saidaenum: alta · media · baixa

Cenários reais — como v3 resolve

Caso 1: Office corporate — partição de conjunto (1,2,3,4 → 1B,2,3,4)

EstadoEstrutura físicaAgrupamento comercialSubdivisão terminalOcupação
Q1parts: andar X com conjuntos 1, 2, 3, 4 (todos físicos)A1=conjunto 1 (link 1:conj.1) · A2 · A3 · A4ST_A1=A1 inteiro · ST_A2 · ST_A3 · ST_A44 linhas Q1
Q2(sem mudança física)A1 fechado (valido_ate=fim Q1) · A1B aberto (link parcial: 50% do conj.1) · A2 · A3 · A4 (mantidos)ST_A1B novo5 linhas Q2 (1 fechada, 1 nova)

Princípio: o conjunto físico 1 não muda — quem muda é o agrupamento comercial. A série temporal da ocupação fica rastreável porque cada agrupamento tem valido_de/valido_ate.

Caso 2: Logística — inquilino fora da modulação

Galpão de 10.000m² com 5 módulos físicos × 2.000m². Cliente aluga 1.000m² no módulo M.01.

NívelRegistro
Estrutura físicaM.01 (2.000m²) · M.02 · M.03 · M.04 · M.05
Agrupamento comercialA_M01_a (link 50% de M.01 = 1.000m²) · A_M01_b (link 50% de M.01 = 1.000m²) · A_M02 · A_M03 · A_M04 · A_M05
Subdivisão terminalST para cada agrupamento
OcupaçãoA_M01_a ocupado pelo cliente; A_M01_b vago

Princípio: a modulação física não muda — só a partição comercial. Se o cliente desocupa, A_M01_a e A_M01_b podem ser fundidos em novo agrupamento A_M01 com link 100%.

Caso 3: BH “saletas malucas”

Andar com 6 saletas sem padrão. Não force-fit hierarquia:

NívelRegistro
Estrutura físicaparte tipo=andar (nível 1) com 6 partes filhas tipo=saleta (nível 2) — nivel_hierarquico registra a profundidade
Agrupamento comercialum agrupamento por saleta, ou agrupamento que junta 2-3 saletas se cliente aluga em conjunto
…igual aos outros casos

Princípio: a hierarquia física é arbitrariamente aninhada via nivel_hierarquico. Cada caso BH-style vira um conjunto de partes físicas no nível certo.

Caso 4: Reforma estrutural (armazém 2 galpões → 3 galpões)

EstadoEstrutura física versão
2024-Q1 a 2025-Q2versão 1: 2 galpões físicos
2025-Q3 em dianteversão 2: 3 galpões físicos · motivo_versao=“expansão construção do galpão 3”

Princípio: versionamento explícito da estrutura física. Agrupamentos comerciais vinculados à versão 1 ficam fechados em 2025-Q2; novos agrupamentos vinculados à versão 2 abrem em 2025-Q3. Toda a série histórica fica preservada.

Caso 5: Fusão comercial (cliente aluga 1+2+3 inteiros)

NívelRegistro
Estrutura físicaconjuntos físicos 1, 2, 3, 4 (sem mudança)
Agrupamento comercialA_123 (link 100% de cada um dos 3 conjuntos físicos · m2_ofertado = soma) · A_4
Ocupação1 linha por trimestre em A_123 (1 contrato) · 1 linha em A_4

Princípio: o link N:M entre agrupamento e estrutura física é o que permite fusão sem destruir as partes físicas.

Métricas derivadas em Silver — atualização v3

A introdução do agrupamento permite três métricas novas que v2 não suportava:

  1. Taxa de re-segmentação — quantas vezes os agrupamentos comerciais de um imóvel mudam por ano (sinal de gestão ativa vs estática)
  2. Eficiência de modulação — % de m² física efetivamente ofertado nos agrupamentos comerciais (vagos sem agrupamento entram aqui)
  3. Vacância por agrupamento — granularidade certa para fundos imobiliários (hoje vacância vira média ponderada de unidades terminais)

Migração v2 → v3 — caminho proposto

  1. Bronze não muda — Excel atual + fontes externas continuam ingeridas no formato bruto
  2. Silver v3 substitui Silver v2 — adiciona 3 tabelas novas (estrutura_fisica_versao, estrutura_fisica_parte, agrupamento_comercial, agrupamento_estrutura_link) e mantém imovel, subdivisao_terminal (renomeada do subdivisao), ocupacao, empresa, transacao, fonte_pesquisa
  3. Bootstrap inicial — para o histórico Excel existente, criar uma versão de estrutura física por imóvel (sem reforma rastreada — é a foto inicial) e um agrupamento comercial por trimestre × Conjunto/Módulo da BASE (modo conservador). Depois Braga revisa caso a caso para resgatar fusões/partições documentadas
  4. Gold — views permanecem compatíveis com o Power BI atual; tabelas novas são opt-in para análises mais finas

Decisões pendentes pós-v3

IDDecisãoOwnerPrazo
DP-MI-1Validar a hierarquia 5 níveis com Braga em 06/05 14hPedro · Braga06/05 14h
DP-MI-2Bootstrap do histórico Excel — modo conservador (1 agrupamento por (trimestre × parte física)) ou modo curado (Braga revisa)Pedro · Bragasprint-semana-3
DP-MI-3Versionamento de imovel em casos extremos (desmembramento, fusão de matrículas)Pedro · Bragamédio prazo

Achados da devolutiva pt2 (07/05) — v3.1

Tracking histórico de proprietário (gap G-032):

  • [fato] Leandro identificou gap: falta tracking histórico de proprietário com versionamento temporal, análogo ao tracking de ocupação. Proprietário muda ao longo do tempo (XP → BTG → Itaú). — Fonte: devolutiva pt2.
  • [fato] Pedro reconheceu: proprietário atual estava no modelo (nível 1), mas versionamento histórico faltava. Proprietário é dimensão separada de transação de compra/venda.
  • [fato] Complexidade de renomeação: mesma entidade muda de nome (GLP fez rebrand). Sem CPF/CNPJ disponível na pesquisa — tracking por nome de entidade, correlação manual.
  • Implicação modelo v3.1: empresa_imovel_papel já suporta valido_de/valido_ate (versionamento temporal). O gap é operacional: garantir que mudanças de proprietário gelem novo registro com período, não sobrescrevam. Chave canônica de entidade + aliases resolve renomeação (R-019).

Subdivisão de imóveis (confirmação):

  • [fato] Pedro apresentou as 3 camadas de subdivisão (geometria física, comercial, unidade locada). Leandro confirmou: “único ponto que chamou atenção é a questão do proprietário. As outras coisas não senti falta de nada.” — Modelo v3 validado exceto proprietário.

Canal Slack MI:

  • [fato] Canal Slack de MI aberto para Leandro interagir com Axios assincronamente. Mesmo modelo que Igor usa na Costal. Leandro testou acesso à wiki com e-mail Colliers — funcional.

Dados de vencimento de contrato:

  • [fato] Dados existem na TB locação (tempo de contrato, carência, condição comercial), mas enriquecimento é parcial. Podem ser complementados via fornecedores. — G-033.

Próximos passos (07/05):

  • Pedro publica spec v3 na wiki (com subdivisão + proprietário)
  • Daniel retorna de férias → Leandro + Daniel revisam colunas detalhadas
  • Reunião pré-execução quando revisão assíncrona estiver concluída

Total de entidades canônicas v3

A v2 tinha 9 entidades. A v3 tem 12 entidades (3 novas, 0 removidas):

#EntidadeStatus v2 → v3
1imovelmantida — renomeada imovel-base em alguns docs para clareza
2estrutura_fisica_versaonova v3
3estrutura_fisica_partenova v3
4agrupamento_comercialnova v3 — resolve calcanhar de Aquiles
5agrupamento_estrutura_linknova v3 — N:M com proporção
6subdivisao_terminalmantida (era subdivisao em v2)
7ocupacaomantida — FK ajustada
8empresamantida
9empresa_imovel_papelmantida
10transacaomantida
11fonte_pesquisamantida
12ext_siila / ext_buildings / ext_fundos_cvmmantidas (3 tabelas auxiliares)

Stack proposto

CamadaTecnologiaJustificativa
Bronze / Silver / GoldDatabricks LakehouseJá é a plataforma definida para o projeto; integra com Sienge e com as outras frentes.
Ingestão ExcelDatabricks Autoloader ou job Python agendadoTrimestral; volume baixo.
Enrichment APIsPython jobs agendados (mensal)Receita/CAGED/CVM têm cadência mensal.
Interface de cadastroApp web leve (a decidir: Streamlit / Retool / app próprio)Fora do escopo imediato; pode ficar para Onda 2.
Agentes proativosFramework interno Anouk (mesmos da Onda 1 Costal)Reuso de Hunter (monitoramento) e Trace (descoberta).
ConsumoPower BI existente + exportsPreservar produto atual.

Dependências

DependênciaTipoStatusOwner
Acesso aos dados originais (Excel base completa, com dados reais)dadopendente OK do Ricardo BetancourtLeandro Braga
Excel modelo (estrutura + amostra anonimizada)dadorecebido 25/04, analisado ✓Pedro (concluído)
Dicionário de dados as-isdocumentoconcluído ✓ — ver inteligencia-mercado-dicionarioPedro
Análise as-is vs. to-bedocumentoconcluída ✓ — ver inteligencia-mercado-asis-vs-tobePedro
Validação cruzada do dicionário com Bragareuniãoagendada 30/04 17:00Pedro + Braga
Plataforma de dados Databricks com ambiente provisionadoinfraem planejamento Costal (D-006)Gabriel + time técnico
OK dos agentes Hunter/Trace reutilizáveis (Onda 1 Costal)arquiteturaem desenhoGabriel
Base dos Dados (licença/acesso)fornecedora confirmarPedro (existe precedente APVIDA)
Acesso a SiiLa e Buildings (já presentes como chaves no AS-IS)API/dadoa confirmarLeandro Braga (interno Colliers)
Bug mapa Power BI .com → .BRinterno Colliersem resoluçãoTI Colliers (Michael)

Métricas de sucesso

MétricaBaseline atual (25/04)Target (6 meses)
Volume de base canonizada0 linhas em Lake100% do Excel atual em Bronze + Silver
Dicionário de dados0 → rascunho v1 concluído (25/04)100% das tabelas documentadas e validadas com Braga
% transações VENDA ligadas a imovel via FK0% (FK quebrada AS-IS)≥ 95% (após bootstrap fuzzy + revisão)
# problemas estruturais do AS-IS resolvidos0 / 27≥ 25 / 27
Universo monitorado~alto padrão (2–5k imóveis est.)+universo B/C ingerido automaticamente (+5x volume)
Insights enriquecidos0≥ 3 cruzamentos ativos (CNPJ/CEP/CAGED) + SiiLa + Buildings + CVM
Prospects gerados proativamente0 (descoberta humana)≥ 20/trimestre (via agentes + saida_prevista)
Latência de atualizaçãotrimestral, humanotrimestral + camada diária para externos
Risco de perdacrítico (arquivo único)zero (backup canônico)
Headers livres de typos cirílicos (Preҫo)0 corrigidos100% normalizados em Bronze

Riscos

RiscoProbabilidadeImpactoMitigação
Ricardo Betancourt não aprovar compartilhamento amploMédiaAltoProposta em fases: começar só com estrutura e dicionário (sem dados) — Pedro já propôs esse caminho na sessão.
Modelo hierárquico não captura todas as variações (re-segmentação, retrofit, mudança de tipologia)AltaMédioSessão dedicada de modelagem 30/04; iteração com Braga antes de congelar.
Power BI atual quebrar na migraçãoBaixaAltoMigrar de forma incremental; Gold mantém shape atual; só substituir fonte quando paridade confirmada.
Artefatos legados (PDFs, fotos) não conseguirem match por nome de pasta (~5% estimado pelo Braga)AltaBaixoRevisão humana assistida nos casos duvidosos; aceitar perda marginal inicial.
Escopo crescer e competir com prioridades CostalMédiaMédioPriorização explícita com Pedro; Costal continua prioridade. Este módulo entra como fronte paralela da frente Colliers.
Dependência de dado externo (Base dos Dados, CVM) ficar indisponívelBaixaMédioArmazenar cópias em Bronze; reprocessar sem depender de API.

Timeline

MarcoData estimadaStatus
Discovery inicial com Leandro Braga2026-04-24concluído ✓
Recebimento de estrutura + amostras anonimizadas2026-04-25concluído ✓
Dicionário de dados as-is2026-04-25concluído ✓ (inteligencia-mercado-dicionario)
Análise as-is vs. to-be2026-04-25concluído ✓ (inteligencia-mercado-asis-vs-tobe)
Sessão de validação de arquitetura com Braga2026-04-30 17:00agendada
OK de Ricardo para compartilhamento dos dados (versão completa)esta-semanapendente
Acesso ao Excel completo + primeiro ingest em Bronze~2026-05-08pendente
Dicionário validado com Braga + decisões de modelagem fechadas2026-04-30 → ~2026-05-08pendente
Integração com blueprint consolidado (marco crítico)2026-05-16crítico
Onda 1: Bronze + Silver canônico + view Gold espelhando Power BI~2026-06-30pendente
Onda 2: enriquecimento (SiiLa + Buildings + CVM + Receita + CAGED) + features derivadas + interface de cadastro~2026-09-30pendente
Onda 3: universo B/C + agentes proativos + batalha de imóveis~2026-12-31pendente

Ver também

Histórico de versões

VersãoDataMudança
v12026-04-24Rascunho inicial pós-discovery; ER inferido com 5 entidades; lista hipotética de dores.
v22026-04-25Reescrita após análise direta da planilha modelo. ER real com 9 entidades (4 novas: fonte_pesquisa, ext_siila, ext_buildings, ext_fundos_cvm). 27 dores estruturais documentadas. Cronograma em 3 ondas. Métricas de qualidade adicionadas (FK, # dores resolvidas, headers normalizados).
v32026-05-06Hierarquia temporal de geometria — 5 níveis com versionamento. Resolve calcanhar de Aquiles (geometria variável). 12 entidades (3 novas).
v3.12026-05-13Incorpora achados devolutiva pt2 (07/05): tracking histórico de proprietário (G-032), renomeação de entidades (R-019), canal Slack MI, dados de vencimento parciais (G-033). Modelo v3 validado por Leandro exceto proprietário.

Esta spec evolui a cada sessão com Braga. Autores: Pedro Villa com apoio de Axios. Revisões: Leandro Braga (validação 30/04) + Gabriel (arquitetura técnica).

Visão de gráfico

Backlinks