# SuiteCRM — decisão de arquitectura e plano de transição Data: 25/09/2026. O utilizador delegou a escolha da solução e confirmou que não existe SuiteCRM nem cliente OAuth. Esta decisão define o destino da arquitectura; não significa que a integração esteja instalada ou aprovada para produção. ## 1. Diagnóstico Portal confirmado: Laravel 13.30.1, React 19.2.8, Inertia React 3.7.0, Inertia Laravel 3.3.3, Fortify 1.39.0, PostgreSQL 17.11/PostGIS 3.6.2. PHP de trabalho 8.5.11; o PATH ainda resolve outro PHP 8.5.0. Filas/cache/sessões usam database. Gestão autorizada por email verificado e lista de gestores; não existe RBAC organizacional completo. Há CRM local (`CrmController`, `ConvertInterestToLead`), catálogo público, projectos e clusters. O `InterestRequestController` aceita `Idempotency-Key` opcional UUID; `InterestSubmission` guarda apenas o hash da chave, compara o hash canónico do pedido e, na mesma transacção, regista recibo, consentimentos e evento na outbox. Replay com payload igual devolve a manifestação original; reutilização com dados diferentes responde 409. `InterestSubmissionTest` cobre replay, conflito, rollback transaccional e submissão antiga sem chave. A conversão em lead também é idempotente por pedido. Outbox/inbox/reconciliação continuam sem processadores. O agregado da outbox exige UUID, enquanto pedidos usam bigint. A referência IR não é credencial de acesso. O cliente existe em app/Integrations/SuiteCrm/ e está desligado por defeito (SUITECRM_ENABLED=false); os testes usam HTTP simulado. Não há instalação SuiteCRM, credenciais, tráfego real nem implantação Docker do portal. A integração e os processadores de outbox/inbox continuam pendentes. ## 2. Decisões e pendências Escolha para homologação: SuiteCRM **8.10.2**, PHP **8.4**, Apache **2.4**, MariaDB **11.4**, isolados em Linux/Docker. A release foi confirmada no repositório oficial e a combinação na matriz oficial. O PHP 8.5 do portal não será usado para executar o CRM. O pacote pré-compilado dispensa ferramentas de compilação Angular na imagem do CRM. SuiteCRM será o único sistema de escrita comercial após a transição. As páginas comerciais do portal passarão a consulta ou comandos enviados ao Laravel e executados via API do CRM. Não haverá escrita dupla nem sincronização bidireccional irrestrita. Antes da transição, o CRM local permanece operacional; não activar envios externos neste estado. Pendentes externos: motor Docker num ambiente Linux de testes; domínio/TLS da homologação; regras de atribuição e SLA; perfis institucionais; finalidade, retenção, transferências e eliminação validadas pelas áreas jurídica e institucional. Nenhum prazo legal é presumido. ## 3. Arquitectura proposta Laravel é o único intermediário entre React e SuiteCRM. Credenciais ficam no backend. Os sistemas não partilham utilizadores de base de dados. Laravel não recebe credenciais MariaDB. A conta técnica OAuth será não administrativa e terá acesso apenas aos módulos necessários. OAuth máquina-a-máquina não é SSO dos utilizadores; manter Fortify nesta fase. Reutilizar a outbox transaccional: gravação do pedido, UUID de integração e evento na mesma transacção. O worker resolve o payload mínimo autorizado e chama a API oficial. A resposta ao investidor confirma recepção, nunca sincronização ainda pendente. Webhooks assinados entram pela inbox; não se assume que SuiteCRM emita nativamente o contrato de assinatura proposto. Será necessária uma extensão suportada e testada. ## 4. Componentes ```mermaid flowchart LR React[React] --> BFF[Laravel BFF] BFF --> PG[PostgreSQL e PostGIS] PG --> Outbox[Outbox transaccional] Outbox --> Worker[Worker de integração] Worker --> Client[SuiteCrmClient] Client --> API[API oficial SuiteCRM OAuth2] API --> CRM[SuiteCRM] CRM --> MariaDB[MariaDB exclusiva do CRM] CRM --> Hook[Extensão de eventos assinados] Hook --> Inbox[Laravel inbox] Inbox --> Projection[Projecção autorizada e reconciliação] Projection --> PG ``` ## 5. Sequência prevista ```mermaid sequenceDiagram actor Investidor participant Portal as React e Laravel participant DB as PostgreSQL participant Worker participant CRM as API SuiteCRM Investidor->>Portal: Submeter com chave idempotente Portal->>Portal: Validar identidade, autorização e finalidade Portal->>DB: Transacção pedido + identidade UUID + outbox DB-->>Portal: Commit Portal-->>Investidor: Referência e estado recebido Worker->>DB: Reclamar evento com lease Worker->>CRM: Consultar identidade externa e candidatos alt Identidade ambígua Worker->>DB: Aguardar revisão humana else Identidade resolvida Worker->>CRM: Criar ou actualizar contacto e organização Worker->>CRM: Criar lead, relações e tarefa com responsável Worker->>DB: Confirmar vínculos e resultado end ``` ## 6. Responsabilidades dos sistemas | Domínio | Sistema principal após transição | Regra | | ---------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------- | | Login, sessões, acesso do investidor | Portal | Não copiar credenciais para CRM | | Organizações, representantes, contactos | SuiteCRM | Portal propõe alterações; CRM valida; cache mínimo | | Perfil de investimento | Portal | Ligação ao contacto/organização por UUID estável | | Leads, negociação, qualificação, responsáveis | SuiteCRM | Projecção no portal; revisão humana | | Campanhas, reuniões, tarefas, casos e aftercare comercial | SuiteCRM | Estado autorizado devolvido ao portal | | Manifestação submetida e comprovativo | Portal | Conteúdo original preservado; espelho comercial mínimo | | Projectos, clusters, corredores e oportunidades publicadas | Portal | Réplicas de referência no CRM; sem editar cadastro lá | | Oportunidade comercial de negociação | SuiteCRM | Não confundir com oportunidade publicada no portal | | Geometrias e análise GIS | Portal | Não replicar geometrias completas para CRM | | Consentimento recolhido no portal | Portal | Revogação restringe tratamento; não reactivar via CRM | | Documentos submetidos | Armazenamento privado do portal | CRM recebe metadados e acesso controlado quando necessário | | Estado técnico de entrega, conflitos e auditoria | Portal | Nunca tokens, passwords ou payload pessoal nos logs | ## 7–9. Módulos, campos e mapeamentos — direcção definida Usar Accounts para organizações, Contacts para pessoas e relações para representação. Não criar um módulo Investors que duplique esses cadastros; um perfil de investimento distinto pode referenciá-los. Usar Leads, Opportunities, Campaigns, Meetings, Tasks, Cases e Documents quando a semântica coincidir. Avaliar módulos personalizados para manifestações, referências de projectos/clusters/corredores e jornadas. Procedimentos regulatórios permanecem no portal; um resumo no CRM só será criado com necessidade demonstrada. Aftercare usa Cases com classificação própria, salvo exigências de permissões/ciclo incompatíveis. O catálogo lógico e a matriz de mapeamento com 15 colunas foram acrescentados em [mapping-catalog.md](mapping-catalog.md). Nomes técnicos de atributos, links e módulos personalizados permanecem candidatos até validação na instância de homologação. Campos comuns previstos: UUID externo imutável, sistema de origem, versão, classificação, instante de recolha e código de finalidade. Nomes técnicos, relacionamentos e disponibilidade na API devem ser comprovados na instalação. Índice único de identidade externa deve ser definido por extensão suportada. Email partilhado ou telefone coincidente são candidatos a revisão, não autorização para fusão automática. ## 10. Endpoints — contrato a desenvolver Preservar `/api/v1/interest-requests` durante a migração. O novo contrato de manifestações deverá partilhar o mesmo serviço e registo idempotente; não criar dois fluxos de escrita independentes. Dashboard, consulta, documentos e reuniões exigem utilizador autenticado e propriedade do pedido. Nunca autorizar consulta apenas pela referência IR. Reconcile e health detalhado serão restritos à operação autorizada. Webhook exige assinatura do corpo bruto, timestamp, identificador único e protecção contra replay. Não implementar upload de binários supondo suporte genérico da API: validar Documents/DocumentRevisions e o mecanismo oficial da versão instalada. ## 11. Eventos e filas Entrega pelo menos uma vez, com idempotência persistente; não prometer exactly-once distribuído. Evento leva identificadores, versão, correlação e finalidade, evitando cópias de dados pessoais. Reutilizar inbox/outbox e acrescentar leases, tentativas e estado de entrega onde necessário, respeitando os triggers de envelope imutável. Retries limitados, backoff exponencial com jitter e respeito por Retry-After. Respostas 401 permitem uma reautenticação; 403/422 exigem intervenção, não repetição cega. Após timeout de criação, pesquisar pelo UUID externo antes de repetir. Conflitos, duplicados ambíguos e falhas definitivas ficam em revisão, com reprocessamento autorizado e auditado. Reconciliação compara identificador, versão e campos permitidos, sem substituir automaticamente o sistema principal. Eventos previstos incluem ExpressionOfInterestSubmitted, InvestorRegistered, OrganizationCreated, LeadCreated, LeadQualified, OpportunityCreated, OpportunityStageChanged, MeetingScheduled, FollowUpOverdue, ProjectLinked, ClusterLinked, CorridorLinked e PostInvestmentCaseOpened. Ainda não publicados pela aplicação. ## 12. Estrutura futura e etapas verificáveis O cliente em app/Integrations/SuiteCrm/ e os testes em tests/Feature/SuiteCrm/ já existem e estão descritos em [client.md](client.md). O catálogo lógico está em [mapping-catalog.md](mapping-catalog.md); jobs, eventos, listeners, mapeamento técnico confirmado na instalação e contratos completos dos domínios continuam por implementar. 1. Decisão e preparação da instalação isolada (esta entrega). 2. Instalação, conta técnica, OAuth, descoberta dos módulos e prova de contrato de API. 3. Catálogo detalhado, campos, mapeamento e endpoints; testes de contrato primeiro. 4. Cliente HTTP, autenticação segura, circuit breaker e testes com respostas simuladas. 5. Outbox/idempotência e jornada completa numa base de homologação. 6. Reconciliação, webhooks, documentos, painéis e restantes domínios. 7. Migração, reconciliação integral, congelamento da escrita comercial local e Go/No-Go. ## Migração e rollback Criar backup e inventário; ensaiar importação pela API numa instalação limpa. Associar cada registo local a um UUID externo antes de migrar relações. Não fundir pessoas automaticamente. Comparar contagens, vínculos, responsáveis e consentimentos; resolver divergências. Durante o corte, congelar escrita comercial local, escoar a outbox, reconciliar e só depois activar o CRM como principal. Não eliminar tabelas antigas. Desactivar a integração pára novos envios, mas não desfaz alterações já feitas no CRM. Um rollback após escrita no SuiteCRM exige exportação/reconciliação dessas alterações antes de reabrir o CRM local; restaurar simplesmente um backup perderia trabalho. ## Go/No-Go e estado da entrega NO-GO para produção. Faltam instalação real, OAuth técnico, ligação do cliente aos fluxos, módulos, contratos completos, testes ponta a ponta, validação de segurança/privacidade/Produto e ensaio de recuperação. Os testes do cliente com HTTP simulado não comprovam uma integração real. Esta alteração acrescenta documentação e um modelo Docker de homologação. Não altera rotas, migrations, dados ou comportamento do portal. Para desfazer esta preparação basta deixar de usar o directório de implantação; não há migração de dados a reverter. ## Fontes oficiais - [Release 8.10.2](https://github.com/SuiteCRM/SuiteCRM-Core/releases/tag/v8.10.2) - [Compatibilidade](https://docs.suitecrm.com/8.x/admin/compatibility-matrix/) - [Instalação](https://docs.suitecrm.com/8.x/admin/installation-guide/downloading-installing/) - [Servidor web](https://docs.suitecrm.com/8.x/admin/installation-guide/webserver-setup-guide/) - [Instalador CLI](https://docs.suitecrm.com/8.x/admin/installation-guide/running-the-cli-installer/) - [OAuth2](https://docs.suitecrm.com/developer/integration-api/v8/authentication/)