varias alteracoes
tests / ci (push) Canceled after 0s

This commit is contained in:
2026-10-06 14:50:12 +02:00
parent 4f35313d06
commit e65cb26901
333 changed files with 54656 additions and 2058 deletions
+4 -4
View File
@@ -6,9 +6,9 @@ Data: 25/09/2026. O utilizador delegou a escolha da solução e confirmou que n
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. `InterestRequestController` não aceita chave de idempotência; a conversão em lead é idempotente por pedido, mas a submissão pública ainda não. Outbox/inbox/reconciliação existem como tabelas, sem processadores. O agregado da outbox exige UUID, enquanto pedidos usam bigint. A referência IR não é credencial de acesso.
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.
Não existe SuiteCrmClient, instalação SuiteCRM ou implantação Docker do portal. Docker não foi encontrado e o executável WSL informa que o subsistema não está instalado. Não foi alterado o sistema operativo.
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
@@ -88,7 +88,7 @@ sequenceDiagram
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 detalhado e a matriz de 15 colunas ainda serão entregues antes da implementação funcional.
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.
@@ -108,7 +108,7 @@ Eventos previstos incluem ExpressionOfInterestSubmitted, InvestorRegistered, Org
## 12. Estrutura futura e etapas verificáveis
O cliente em `app/Integrations/SuiteCrm/` e os testes em `tests/Feature/SuiteCrm/` foram acrescentados na entrega seguinte, descrita em [client.md](client.md). Jobs, eventos, listeners e contratos completos dos domínios ainda estão por implementar.
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.
@@ -0,0 +1,47 @@
# 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`.