Files
Investidor-V2/docs/investmoz/suitecrm/architecture.md
T
nala e65cb26901
tests / ci (push) Canceled after 0s
varias alteracoes
2026-10-06 14:50:12 +02:00

141 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/)