Investidor-V2/deploy/suitecrm/README.md

# SuiteCRM 8.10.2 — preparação de homologação

Estado: modelo preparado; **build e arranque Docker ainda não executados**. Este Windows não tem Docker nem WSL instalado. Não aplicar em produção. O cliente Laravel e a captura na outbox existem; utilizador técnico, OAuth e envio real continuam pendentes.

Para os scripts de arranque e o bloqueio identificado no Windows Parallels ARM, consultar [instalação local](LOCAL.md). Está disponível o diagnóstico `php artisan suitecrm:probe` para verificar OAuth e metadados após configurar um CRM acessível por HTTPS.

A [decisão de arquitectura](../../docs/investmoz/suitecrm/architecture.md) define SuiteCRM como futuro sistema principal comercial. O portal continua operacional e não envia dados para este ambiente.

## Dependências verificadas

- Release oficial pré-compilada 8.10.2: download e SHA-256 conferidos; arquivo com `bin/console` e aplicação na raiz.
- PHP 8.4/Apache e MariaDB 11.4: combinação suportada na matriz oficial. Imagens fixadas pelos digests consultados no registry oficial em 25/09/2026.
- Motor Docker Linux e Compose v2 ainda necessários. JSON é usado como formato compatível com YAML para o ficheiro Compose.
- Dockerfile instala extensões do CRM; não altera PHP ou dependências Laravel.

## Preparar e instalar numa máquina Linux de testes

Executar a partir deste directório. Os comandos abaixo são instruções preparadas, não resultados de execução.

1. Confirmar `docker version` e `docker compose version`.
2. Criar `.secrets` com acesso apenas ao operador. Criar os ficheiros `db_password` e `db_root_password` com valores aleatórios distintos, sem newline, usando um gestor de segredos. Não colocar segredos em argumentos de comandos, no Git ou no chat. O Compose local monta ficheiros; não constitui um cofre de segredos encriptado.
3. Validar a configuração e construir:

```sh
docker compose -f compose.json config --quiet
docker compose -f compose.json build web
docker compose -f compose.json up -d db web
docker compose -f compose.json ps
docker compose -f compose.json exec --user www-data web php bin/console suitecrm:app:install
```

O instalador interactivo deve usar host `db`, base `suitecrm`, utilizador `suitecrm`, password definida no ficheiro privado e uma conta administradora exclusiva da homologação. Desactivar dados de demonstração se o ensaio de migração precisar de contagens exactas. Não usar a conta administradora como identidade da integração.

O HTTP está exposto **apenas em 127.0.0.1:8088**, para bootstrap com dados fictícios. Para homologação partilhada/API, colocar proxy HTTPS diante desse listener, configurar o site URL definitivo, confiar apenas no proxy conhecido e activar cookies seguros. Não abrir a porta na rede nem transmitir credenciais/dados reais por HTTP. Não foram criados DNS ou certificados.

Depois da instalação e da configuração do transporte:

```sh
docker compose -f compose.json exec --user www-data web php bin/console messenger:setup-transports
docker compose -f compose.json --profile installed up -d worker
docker compose -f compose.json exec --user www-data web php bin/console schedulers:run
```

Agendar o último comando a cada minuto no host, sem TTY (`exec -T`), usando o caminho absoluto real para este compose e sem execuções sobrepostas. Validar o último processamento no painel Schedulers. O perfil `installed` impede iniciar o worker antes da configuração inicial. Não multiplicar workers antes dos testes de concorrência.

## Conta técnica e OAuth — após arranque

Criar utilizador técnico exclusivo sem administração, exportação geral ou acesso a módulos não usados. Configurar papéis/grupos e testar permissões com essa identidade. Criar cliente OAuth2 para client credentials associado à identidade técnica conforme as opções da instalação. Guardar o segredo num cofre acessível apenas ao backend/worker Laravel. Verificar obtenção, expiração, revogação e nova emissão de token. Não presumir refresh token neste grant.

Confirmar o prefixo efectivo da API V8 nesta instalação SuiteCRM 8 e descobrir nomes de campos/relacionamentos pelos endpoints oficiais. Antes de ligar Laravel, comprovar criação, leitura, actualização e relação de registos fictícios, incluindo negação de operações fora do âmbito.

## Persistência, logs e actualizações

A base e a aplicação completa usam volumes nomeados para preservar configuração, chaves, extensões e uploads durante os ensaios. **Reconstruir a imagem não actualiza o código num volume existente.** Uma actualização requer procedimento oficial e backup compatível, ou nova instalação isolada; nunca apagar o volume para tentar actualizar uma instalação com dados.

Não configurar SMTP, importações reais ou webhooks enquanto os controlos e o contrato não forem testados. O access log preparado não inclui URL/query, cabeçalhos ou corpo; rever também logs próprios do SuiteCRM e do PHP para dados sensíveis. Não activar debug em ambiente com dados pessoais.

## Validação e rollback

Verificações locais realizadas: existência da release/imagens, integridade SHA-256 e estrutura do ZIP, análise estática do Compose. Pendentes: build, extensões em runtime, instalação, autenticação, TLS, schedulers, worker, permissões e restauro.

Para parar o ensaio preservando volumes:

```sh
docker compose -f compose.json --profile installed stop
```

Antes de qualquer migração/upgrade, obter backup consistente da base, aplicação, uploads e segredos; ensaiar restauro em projecto Compose separado. Não executar `down -v`. A produção permanece NO-GO até testes funcionais, segurança, privacidade e recuperação.

## Fontes

- [Release oficial](https://github.com/SuiteCRM/SuiteCRM-Core/releases/tag/v8.10.2)
- [Matriz de compatibilidade](https://docs.suitecrm.com/8.x/admin/compatibility-matrix/)
- [Instalador CLI](https://docs.suitecrm.com/8.x/admin/installation-guide/running-the-cli-installer/)
- [Messenger](https://docs.suitecrm.com/8.x/admin/async-tasks/messenger-setup/)
- [Schedulers](https://docs.suitecrm.com/8.x/admin/administration-panel/schedulers/)