154 lines
13 KiB
Markdown
154 lines
13 KiB
Markdown
# Preparação para publicação
|
|
|
|
Destino definido: Linux, domínio `investemoz.tempo.co.mz`. Os modelos Nginx,
|
|
systemd e .env de produção estão em [deploy/linux](../../deploy/linux/README.md).
|
|
Assumem `/var/www/investemoz`, utilizador `www-data` e PHP 8.5; adaptar os caminhos
|
|
à distribuição e validar com nginx -t e systemd-analyze verify no servidor.
|
|
|
|
Verificação local em 25/09/2026: suite PHP com 57 testes passou; os cinco testes
|
|
operacionais foram repetidos após acrescentar a protecção transaccional da fila
|
|
(26 verificações). Nenhum email real foi enviado. O diagnóstico confirmou ligação
|
|
PostgreSQL, PostGIS e migrations aplicadas; produção, HTTPS, cookies seguros,
|
|
desactivação de debug, remoção de public/hot do artefacto e correio real continuam
|
|
como tarefas do servidor. Não foram alteradas estas definições de desenvolvimento.
|
|
|
|
Não foi feita qualquer publicação nem activado o envio de emails. A conta pode
|
|
ser configurada posteriormente em `/acesso-gestao`.
|
|
|
|
## Requisitos
|
|
|
|
PHP compatível com composer.lock (>= 8.4.1), PDO PostgreSQL, PostgreSQL/PostGIS,
|
|
Node compatível com package-lock.json para compilar assets, servidor HTTPS e
|
|
processo permanente para a fila. Apontar o document root exclusivamente para
|
|
`public`. Impedir acesso HTTP a `.env`, vendor, storage e restantes ficheiros.
|
|
Dar escrita ao utilizador da aplicação apenas em storage e bootstrap/cache.
|
|
|
|
## Configuração do servidor
|
|
|
|
Provisionar os segredos no servidor, sem os incluir no repositório:
|
|
|
|
```dotenv
|
|
APP_ENV=production
|
|
APP_DEBUG=false
|
|
APP_URL=https://SEU-DOMINIO
|
|
SESSION_SECURE_COOKIE=true
|
|
DB_CONNECTION=pgsql
|
|
QUEUE_CONNECTION=database
|
|
PORTAL_NOTIFICATIONS_ENABLED=false
|
|
PORTAL_NOTIFICATION_RECIPIENTS=
|
|
```
|
|
|
|
Definir APP_KEY, ligação PostgreSQL, PORTAL_MANAGER_EMAILS e correio SMTP com
|
|
remetente autorizado. Manter a APP_KEY existente nas actualizações. Usar contas
|
|
distintas para migrations e execução, conforme os privilégios definidos para o
|
|
servidor. A configuração de proxy deve confiar apenas no proxy efectivamente usado.
|
|
|
|
## Instalação e actualização
|
|
|
|
1. Fazer backup PostgreSQL e dos ficheiros persistentes; ensaiar a recuperação
|
|
numa instância separada. Guardar a versão anterior da aplicação.
|
|
2. Instalar dependências de produção com `composer install --no-dev --prefer-dist --optimize-autoloader`.
|
|
3. No ambiente de build, executar `npm ci` e `npm run build`. Publicar public/build;
|
|
o artefacto de produção não deve incluir public/hot, node_modules nem .env local.
|
|
4. Na primeira instalação, gerar APP_KEY com `php artisan key:generate`.
|
|
5. Rever e executar `php artisan migrate --force`. Não executar migrate:fresh
|
|
nem os seeders de demonstração em produção.
|
|
6. Executar `php artisan config:cache`, `php artisan route:cache` e
|
|
`php artisan view:cache`. Reiniciar PHP/OPcache e `php artisan queue:restart`.
|
|
7. Executar `php artisan portal:readiness`. Corrigir os itens pendentes antes
|
|
da publicação; o comando não apresenta credenciais nem altera registos.
|
|
8. Verificar `/up`, `/api/v1/home`, catálogo e login. Confirmar que utilizadores
|
|
sem autorização recebem 403 nas rotas de gestão. Ensaiar emails com destinatário
|
|
controlado antes de activar notificações públicas.
|
|
|
|
## Activação da biblioteca documental
|
|
|
|
Para uma entrega que inclui o catálogo documental ou a análise antimalware, não
|
|
usar uma migração global se existirem migrações pendentes não relacionadas. Fazer
|
|
e validar primeiro um backup recuperável. Confirmar que a aplicação aponta para a
|
|
base prevista e executar, nesta ordem, apenas as duas migrações desta entrega:
|
|
|
|
```sh
|
|
php artisan migrate --path=database/migrations/2026_10_05_120000_extend_portal_document_catalogue.php --force
|
|
php artisan migrate --path=database/migrations/2026_10_05_130000_add_document_malware_scanning.php --force
|
|
php artisan portal:check-document-library-schema
|
|
```
|
|
|
|
O último comando tem de terminar com sucesso antes de disponibilizar o catálogo.
|
|
As migrações mantêm os direitos anteriores como `unconfirmed` e as análises
|
|
anteriores como `pending`; não marcar registos antigos como públicos ou limpos.
|
|
Se a compatibilidade falhar, manter os controlos de publicação e análise e
|
|
consultar o diagnóstico interno. O comando não altera dados.
|
|
|
|
## Notificações
|
|
|
|
Definir PORTAL_NOTIFICATION_RECIPIENTS com emails da equipa separados por vírgulas.
|
|
Activar PORTAL_NOTIFICATIONS_ENABLED apenas após testar SMTP. Esta opção é
|
|
independente dos emails de verificação da conta enviados pelo Fortify.
|
|
|
|
O registo de pedido e a inserção dos jobs usam a mesma transacção PostgreSQL.
|
|
Manter DB_QUEUE_CONNECTION vazio (ligação por omissão) e after_commit=false na
|
|
ligação database. Não usar uma base externa para jobs deste fluxo.
|
|
Executar sob o supervisor do servidor:
|
|
|
|
```shell
|
|
php artisan queue:work database --queue=default --sleep=3 --tries=3 --timeout=30
|
|
```
|
|
|
|
O worker precisa de reiniciar automaticamente, guardar logs e ser reiniciado em
|
|
cada release. Garantir timeout SMTP inferior ao timeout do worker e retry_after
|
|
superior a 30 segundos. Consultar `php artisan queue:failed`; investigar a causa
|
|
antes de repetir jobs com `php artisan queue:retry ID`. Uma repetição após entrega
|
|
sem confirmação pode duplicar um email (entrega pelo menos uma vez).
|
|
Desactivar a opção impede também o envio de jobs pendentes. Se os destinatários
|
|
forem removidos, os respectivos jobs deixam de enviar. As notificações contêm
|
|
apenas referência e ligação protegida; não incluem contactos nem mensagens.
|
|
|
|
## Histórico e recuperação
|
|
|
|
`/management/history` mostra alterações efectuadas por gestores a partir desta
|
|
versão. Os eventos e a alteração são gravados na mesma transacção. Reutiliza-se
|
|
audit_events, protegido contra alterações e remoções; não há limpeza automática.
|
|
Para entidades legadas bigint, o identificador fica em before_data/after_data.record_id;
|
|
entity_id UUID fica nulo. Registam-se os campos alterados e valores operacionais
|
|
permitidos, nunca textos livres, contactos ou palavras-passe. Este histórico cobre
|
|
as acções de gestão, não alterações directas por SQL ou importações externas.
|
|
|
|
Em incidente, desactivar notificações, colocar a aplicação em manutenção e
|
|
reverter o código apenas se compatível com o esquema. Não executar rollback de
|
|
migrations indiscriminadamente; recuperar backup só mediante plano validado.
|
|
Monitorizar espaço em disco, jobs falhados, logs, HTTPS e backups. Testes PHPUnit
|
|
devem usar exclusivamente bases descartáveis terminadas em `_test`.
|
|
|
|
## Preparação delimitada do relatório financeiro — homologação, 20/11/2026
|
|
|
|
**PREPARAÇÃO TÉCNICA CONCLUÍDA; INSTALAÇÃO E PUBLICAÇÃO NÃO AUTORIZADAS.** Não executar os comandos genéricos de instalação deste guia por inferência deste aditamento. Relatório integral APTO EM QA e encerrado funcionalmente em `c34670ef`; esta preparação não reabre o desenvolvimento.
|
|
|
|
Destino proposto e já identificado nos recibos existentes: `https://teste-investidor.tempo.co.mz`. O endpoint público `/build/revision.json` declarou `bae996e10d0473805c51be30422da3b415f40853`, ramo `main`, build de 18/11/2026 e manifesto `9f03e42c76491a1f3c03faf7b0507bc634ed6d4996f8763a1ca06466ed0594e9`. Esta observação pública não substitui a confirmação autenticada da release, ficheiros, base, flags e executor antes de instalar. O guia Linux genérico de produção não identifica por si só os caminhos efectivos da homologação.
|
|
|
|
| Elemento preparado | Resultado |
|
|
| --- | --- |
|
|
| Fonte QA aceite | `c34670efdc392d7ac04260deea28bda0c4723f2d`, incluindo Etapa 1 e os cinco pacotes |
|
|
| Delta funcional delimitado | 29 ficheiros funcionais e 17 de testes, com dependências do cenário aprovado, simulador/persistência, tabelas, dossier, exportações e CAE |
|
|
| Alterações anteriores excluídas | Páginas `funding/index.tsx`, `investment/company-comparison.tsx` e respectivos testes de critérios/coerência de financiamento; não transportar o ramo completo por arrastamento |
|
|
| Também fora do artefacto | Base/dossier/contas sintéticas QA, credenciais, ligações assinadas, sessões, logs, `.env`, `AGENTS.md`, auxiliares/routers de QA e build marcado como QA |
|
|
| Schema, dependências e configuração | Sem delta em migrations, composer/npm e locks, permissões, ambiente ou executor; não propor migração, publicação de serviços/CAE geral ou activação de módulos |
|
|
| Aplicação e reversão | Patches completos verificados em índice Git isolado sobre a base e a candidata exactas; nenhum worktree ou servidor alterado |
|
|
| Compatibilidade de reversão | Leitor/gravador de `bae996e1` aceita os snapshots sintéticos v16/v19 e conserva CAE, mercado, pressupostos e saldos dos rácios; verificação de leitura, sem recalcular finanças |
|
|
|
|
Artefactos privados locais em `outputs/controlled-5f7db7cd-20261120/homologation-preparation/`: `manifest.json` com caminhos e blobs Git por ficheiro, `target-revision.json`, `forward.patch`, `reverse.patch` e `rollback-compatibility.json`. SHA256 do patch de aplicação: `fc2746c5d8a03a33f01e5140426f3ce495b5465e4ba464873bdf273f3b0b6b4d`; reversão: `a838651d1482ac0301721207a6b7e84209bd3bd0ab2e9a564d6270bf8de07b7d`. Os patches são propostas locais verificáveis, não instruções autorizadas para execução.
|
|
|
|
### Sequência proposta para uma futura entrega expressamente autorizada
|
|
|
|
1. Confirmar autenticamente o destino, a release actual e os hashes dos ficheiros do manifesto. Reconfirmar schema, configuração, flags e regras de acesso efectivas sem as modificar. Se a base já não for `bae996e1` ou houver alterações nos ficheiros, invalidar a aplicação directa do patch e preparar apenas a integração necessária em checkout limpo. O workspace local principal está em `4ca54e76` e contém alterações alheias, incluindo ficheiros partilhados: não sobrescrever, limpar, copiar integralmente ou instalar a partir dele.
|
|
2. Constituir a candidata de entrega sobre a base exacta confirmada, usando o delta delimitado e preservando evoluções entretanto instaladas. Construir assets pelo perfil normal do destino, com os locks existentes; não copiar `public/build-qa-opportunities`. Preservar APP_KEY e chaves anteriores, `.env`, storage e permissões. Cumprir os controlos do executor e CI existentes, sem os alterar ou dispensar. A verificação dos patches não certifica a CI/build de uma futura integração diferente da QA aceite.
|
|
3. Antes da troca de release, obter backup fresco da base, ficheiros persistentes e configuração/chaves por mecanismo privado existente; conservar a release e assets anteriores. Demonstrar restauro numa instância isolada, com contagens/hashes e leitura dos snapshots cifrados por actor/contexto equivalentes. Não reutilizar um recibo antigo como backup actual. Esta execução não efectuou backup/restauro remoto nem reservou caminhos no servidor.
|
|
4. A futura autorização deverá identificar a candidata exacta, destino, janela, recibo do backup/restauro, mecanismo de aplicação/reversão e limites. Só depois executar pelo mecanismo de releases já existente. Não fazer push/merge/alteração de ponteiro ou reinício nesta preparação: podem accionar a entrega. Nenhuma migração ou publicação de serviços integra o delta financeiro.
|
|
5. Na entrega autorizada, confirmar `/build/revision.json`, saúde, autenticação e o fluxo sintético em homologação: mesmo proprietário/dossier/plano/versão, onze tabelas, CAE, avisos não bloqueantes, gravação/recuperação, Word/impressão, computador/móvel e rejeição de outra conta. Criar ou reutilizar ensaio normal autorizado nesse ambiente; não transportar contas, sessões ou base QA. Reutilizar as provas financeiras aceites e conferir apenas o transporte e os ficheiros efectivamente integrados.
|
|
|
|
### Reversão e condições de paragem
|
|
|
|
Falha de saúde, acesso indevido, perda de recuperação, divergência de valores/versões ou indisponibilidade dos ficheiros/colunas necessários impede a troca ou exige a reversão prevista. Usar a release anterior preservada e o mecanismo efectivo confirmado, mantendo os dados gravados depois da entrega. O patch inverso só é aplicável aos ficheiros e hashes exactos, sem edições posteriores. Não executar rollback de schema, restauração da base ou eliminação de dados por rotina; qualquer recuperação que possa substituir gravações posteriores exige decisão e plano próprio. A reversão de código pode retirar temporariamente as novas apresentações, mesmo conservando os campos opcionais nos snapshots; a prova local de compatibilidade não certifica todos os dados reais do destino.
|
|
|
|
**Pendente antes de instalar:** inventário autenticado actual do ambiente/executor; candidata de entrega exacta com CI/build; backup fresco e restauro demonstrado; autorização expressa de instalação. Nenhuma destas pendências retira a aceitação funcional em QA. Histórico QA perdido e tradução HTTP 503 continuam independentes. Não há novas funcionalidades a desenvolver nesta preparação.
|