48 lines
18 KiB
Markdown
48 lines
18 KiB
Markdown
# 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](https://docs.suitecrm.com/8.x/admin/compatibility-matrix/)). A release 8.10.2 aparece como a release actual na página oficial consultada ([releases SuiteCRM](https://github.com/SuiteCRM/SuiteCRM-Core/releases)). 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`.
|