Investidor-V2/docs/investmoz/suitecrm/mapping-catalog.md

Catálogo lógico de módulos e mapeamento — SuiteCRM

Estado: especificação preliminar, 2026-10-04. Não é configuração executável nem autorização de exportação. O cliente SuiteCRM permanece desligado.

Pré-condição de runtime ainda aberta

O portal usa PHP 8.5.11 por instrução do projecto. A matriz oficial consultada para SuiteCRM 8.10.x lista PHP 8.2, 8.3 e 8.4; PHP 8.5 não está listado como suportado (matriz oficial). A release 8.10.2 aparece como a release actual na página oficial consultada (releases SuiteCRM). Assim, o runtime aprovado para CRM continua por resolver; não instalar nem declarar compatibilidade de PHP 8.5 com esta release.

O ambiente também não dispõe de Docker/Podman e wsl --status confirma que o Subsistema Windows para Linux não está instalado. Não instalei componentes do sistema operativo nem serviços. A homologação SuiteCRM não pode arrancar nesta máquina no estado observado.

Regras de interpretação

• A coluna de atributo de destino descreve conceitos. Os nomes técnicos, campos personalizados, links JSON:API, obrigatoriedade e limites têm de ser descobertos e aprovados na instalação SuiteCRM de homologação.
• O portal continua fonte de verdade para manifestações, consentimentos, perfis de investimento, oportunidades publicadas, projectos, clusters, corredores, geografia, documentos e cálculos.
• SuiteCRM só será fonte de verdade para leads comerciais aceites, negociação, tarefas, reuniões e acompanhamento comercial depois de migração e decisão Go/No-Go.
• Receber uma manifestação não cria automaticamente Contact, Account ou Opportunity no CRM. A outbox contém apenas UUID e tipo de evento; um futuro worker terá de reler consentimento, finalidade, estado e autorização antes de formar o payload.
• Correspondência por email/telefone, duplicados, identidade incerta ou consentimento ausente exigem revisão; nunca fazer fusão automática.
• Documentos, mensagens livres, dados fiscais, informação bancária, geometrias completas, IP, user-agent, tokens e credenciais não são enviados por este catálogo.

Matriz de 15 campos de decisão

Entidade de origem	Campos de origem já existentes	Módulo SuiteCRM candidato	Registo lógico de destino	Direcção prevista	Atributos lógicos candidatos	Relações candidatas	Sistema de registo	Finalidade permitida	Gate de consentimento/autoridade	Classificação	Minimização/transformação	Chave externa/idempotência	Controlo de acesso/auditoria	Estado/evidência exigida
InterestRequest / interest_requests	integration_id, reference, full_name, email, phone, investor_type, country, sector_interest, investment_range, message, status; consentimentos são registados separadamente	Leads	Manifestação comercial mínima, identificada no CRM como proveniente do portal	Portal → CRM, apenas após processamento aprovado da outbox	Nome de apresentação e meios de contacto estritamente necessários; referência do portal; categoria geral de interesse	Lead ligado a Contact/Account só após resolução humana/identificador externo	Portal mantém pedido e consentimento; CRM mantém tratamento comercial após aceitação	Responder à manifestação e acompanhar o pedido	Consentimento vigente para resposta; consentimento separado se houver partilha com proponente; finalidade, retenção e base legal aprovadas	Confidencial/PII	Excluir mensagem livre por defeito; não inferir residência, elegibilidade ou identidade; normalização sem alterar valor de origem	integration_id imutável e chave de integração única a definir no CRM; retry após escrita ambígua exige pesquisa antes de repetir	Papel técnico mínimo; logs apenas com operação/resultado/duração; acesso humano auditado	Parcial: intake e outbox transaccionais testados; não há worker, CRM nem esquema confirmado
Investor e relações investor_contacts	UUID do investidor; sectores, geografias, horizonte, ticket e relações a contactos	Contacts; Accounts para organização	Contact individual e Account organizacional, sem duplicar o perfil de investimento	Portal → CRM depois de identidade e vínculo revistos; eventual projecção CRM → portal ainda por decidir	Identificador externo; nome/contacto somente se fonte, finalidade e permissão autorizarem; organização e papel apenas após validação	Contact–Account e representação segundo relações comprovadas no CRM	Portal conserva perfil e preferências; CRM poderá ser principal para contacto comercial após corte	Gestão comercial de contacto e organização	Verificar consentimento, qualidade/origem, papel de representante e regras de acesso; sem equivalência automática de registos	Confidencial/PII	Não copiar preferências de investimento ou ticket sem necessidade documentada; NUIT e documentos ficam fora até aprovação específica	UUID externo do portal; restrição única e extensão de deduplicação a comprovar	Acesso restrito por equipa/território; trilho de alteração e origem	Pendente: resolução de identidade, política de campos e relação ainda não aprovadas
Lead e CrmTask locais	Estado, owner, investor, estimated amount, tarefas e respectivos estados	Leads; Tasks	Lead qualificado e actividade comercial	CRM → portal ou carga única durante transição; sem escrita dupla permanente	Estado, responsável, próxima acção e valores comerciais somente após definição do modelo de transição	Lead–Contact/Account; Task–Lead/Contact conforme API instalada	SuiteCRM após corte; actualmente o portal local	Qualificação e gestão comercial	Perfil autorizado, papéis institucionais e política de atribuição/SLA aprovados	Confidencial; PII onde aplicável	Não transportar comentários privados ou payload integral sem classificação e finalidade	UUID externo; estado e versão/correlação para reconciliação	Permissões CRM por papel, operação administrativa restrita, eventos auditados	Parcial: CRM local existe; ainda sem processo de migração, mappings de status ou ACL comprovada
Opportunity pública e Project	Slug/UUID, título, estado publicado, descrição pública, território, sector e referências	Módulo personalizado de referência ou leitura externa; não usar automaticamente Opportunities comercial	Espelho de catálogo publicado, se houver necessidade demonstrada	Portal → CRM, só dados já públicos e sincronização autorizada	Identificador e URL pública; título e estado público	Relação a Lead apenas por comando comercial revisto; não fundir com Opportunity do CRM	Portal	Contexto de referência para negociação	Aprovação do proprietário do catálogo e política de publicação	Público; referências internas podem ser confidenciais	Lista permitida de campos públicos; retirar geometria detalhada e metadados privados	UUID estável e versão do catálogo; upsert só depois de extensão única comprovada	Leitura por utilizadores comerciais autorizados; mudanças do catálogo auditadas no portal	Pendente: módulo, API, necessidade, contrato e política de actualização por validar
EconomicCluster, DevelopmentCorridor, InvestmentZone e relações	UUID/código, nome, estado, relações e geometrias/atributos GIS	Módulo de referência personalizado apenas se aprovado	Referência resumida a cluster/corredor/zona	Portal → CRM, somente identificadores e metadados aprovados	UUID, código, nome público e link do portal	Ligações a Project/Lead não podem alterar cadastro territorial	Portal	Contextualizar uma negociação	Aprovação do responsável do catálogo e classificação campo a campo	Público ou interno conforme o atributo	Nunca replicar geometrias completas, camadas GIS, coordenadas sensíveis ou dados de titularidade	UUID do portal e versão; sem chave única validada não sincronizar	Sem edição CRM; leitura restrita conforme classificação	Pendente: módulo/API e necessidade por provar
Reuniões, aftercare e seguimento institucional	Não há contrato de domínio SuiteCRM ligado ao portal; eventos são apenas propostos	Meetings, Cases, Tasks, Campaigns	Actividade comercial ou caso após investimento	CRM → portal por API/webhook assinado e projectado; comando validado via Laravel	Estado, data, responsável e resumo mínimo, conforme contrato a aprovar	Relações e ACL dependem dos módulos efectivamente instalados	CRM após corte; consentimentos e comprovativos continuam no portal	Seguimento comercial/aftercare autorizado	Base legal, participantes, finalidade e perfis de acesso aprovados	Confidencial/PII	Não sincronizar notas livres por defeito; resumos redigidos e auditáveis	ID CRM + UUID/correlation ID; inbox idempotente com assinatura e anti-replay	Autorização por pedido e papel; webhook validado; reconciliação de versão	Não implementado; módulos, webhook e projection inexistentes
LandAssistanceCase, anexos e assistência DUAT	Dados do requerente, finalidade, etapa, consentimento e referências de anexos	Sem módulo atribuído nesta fase	Nenhum registo no CRM até decisão específica	Nenhuma direcção aprovada	Nenhum	Nenhuma	Portal e arquivo privado autorizado	Apoio informativo/documental fundiário	Validação jurídica, consentimento específico e necessidade demonstrada	Sensível/PII e possivelmente documentos de alto risco	Não copiar anexos, dados de terra/titularidade ou informação jurídica para CRM por defeito	Não aplicável	Permissões e retenção específicas do portal	Bloqueado para integração; fluxo permanece separado e sem sincronização externa

Contrato de identidade e de reconciliação

1. O identificador externo é UUID aleatório imutável do portal, não email, telefone, NUIT ou referência visível.
2. Até existir campo único suportado e verificado na API, nenhuma operação de criação pode ser repetida automaticamente após timeout; primeiro pesquisa e revisão de ambiguidade.
3. O payload deve incluir versão do esquema, UUID, finalidade e correlação; só inclui dados de negócio permitidos pelo catálogo aprovado.
4. A inbox futura validará assinatura do corpo bruto, timestamp, identificador único e janela anti-replay. O desenho ainda exige prova de compatibilidade com mecanismo suportado pelo SuiteCRM.
5. A reconciliação compara UUID, versão e allowlist de campos. Diferenças de sistema principal, identidade duplicada e conflitos de consentimento são filas de revisão, nunca sobrescritas automáticas.

Critérios para passar do catálogo à implementação

• Instância de homologação SuiteCRM isolada, TLS válido, versão fixada, backup e conta OAuth não administrativa.
• Descoberta de módulos, campos, relações, obrigatoriedade, permissões e paginação pela API; guardar resposta sanitizada e hashes do contrato, sem tokens nem PII.
• Aprovação de cada campo por finalidade, classificação, retenção, acesso e origem.
• Testes de contrato contra essa instância para leitura, escrita, duplicação, timeout ambíguo, 401/403/409/422, limites, paginação e reconciliação.
• Processo de outbox com leases, tentativas limitadas, dead-letter, replay autorizado, monitoria e prova de não duplicação.
• Go/No-Go separado antes de qualquer credencial real ou activação. Até esses gates, SUITECRM_ENABLED=false.