Investidor-V2/docs/investmoz/runbook.md

Execução, migração de dados e rollback

Pré-requisitos

PHP 8.4.1+ para o composer.lock instalado; composer.json declara ^8.3. Runtime compatível com composer.lock, pdo_pgsql, dependências Composer, PostgreSQL/PostGIS. Referência: PostgreSQL 16 com PostGIS 3.4 ou superior compatível; confirmar no servidor. Usar base isolada terminada em _test. Configurar DB_CONNECTION=pgsql, DB_DATABASE=investmoz_test, DB_HOST, DB_PORT, DB_USERNAME e DB_PASSWORD no ambiente seguro; nunca versionar credenciais. O administrador pode provisionar postgis/pgcrypto antes; caso contrário a conta de migrations necessita dessa capacidade.

Comandos Artisan

Os ficheiros já estão criados. Para futuras alterações: php artisan make:migration descricao_da_alteracao php artisan migrate --pretend php artisan migrate --seed php artisan migrate:status

Apenas numa base de desenvolvimento descartável: php artisan migrate:fresh --seed php artisan migrate:rollback php artisan migrate --seed

Idempotência é assegurada pelo ledger migrations; não se usa IF NOT EXISTS para esconder deriva de tabelas. Extensões partilhadas usam IF NOT EXISTS. Funções próprias investmoz_* usam CREATE OR REPLACE porque migrate:fresh remove tabelas, mas conserva funções PostgreSQL. Cada migration usa a transacção gerida pelo Laravel, sem BEGIN/COMMIT embutidos. Uma falha deixa o ficheiro pendente, preservando os anteriores.

Testes

php artisan config:clear
php artisan test
php artisan test --configuration=phpunit.investmoz.xml
python tools/investmoz/validate.py
python tools/investmoz/generate.py --source "caminho/do/documento.docx" --check

O ensaio dedicado exige INVESTMOZ_SCHEMA_TESTS=1 e base terminada em _test; executa migrate:fresh e elimina dados dessa base. As novas migrations rejeitam SQLite explicitamente. A suite principal deve usar PostgreSQL. Testes estáticos não equivalem a execução PostgreSQL/PostGIS. Desempenho usa EXPLAIN sem limiar inventado.

MySQL -> PostgreSQL

1. Inventariar versão, charset, collation, contagens, moedas, fusos e ligações da origem real.
2. Obter snapshot e backup com restauração verificada e manifesto SHA-256.
3. Criar destino vazio e executar migrations sem seeds de demonstração.
4. Preservar IDs bigint do legado; atribuir UUID às novas entidades com mapa persistente origem/ID/UUID. Resolver P-08 antes de mapear opportunities para projects/CRM.
5. Transportar decimais como strings, sem float. Normalizar datas com fuso aprovado; colocar zero dates e datas inválidas em quarentena.
6. Validar JSON e geometrias 2D SRID 4326; recusar correcções geográficas silenciosas.
7. Importar por dependências em lotes transaccionais; deduplicar por source_system/external_id e comparar version_no atomicamente.
8. Guardar checkpoint na transacção do lote; não colocar dados pessoais nos logs.
9. Reconciliar contagens, somas, hashes canónicos, duplicados, órfãos e geometrias; tolerâncias ainda pendentes.
10. Ajustar sequences bigint com setval após verificar MAX(id); guardar origem para reversão.
11. Ensaiar corte, deltas e restauro antes de transferir tráfego. Esta entrega não executa importação.

Rollback

down remove triggers, índices avançados, FKs/checks/PKs e tabelas em ordem inversa, depois funções próprias. Não remove extensões nem usa DROP CASCADE. Reverter tabelas POPULADAS destrói os seus dados, mesmo sem CASCADE. Não é reversão sem perda. Antes de rollback fora do ensaio: suspender escritores, exportar tabelas, verificar restauração separada e guardar ledger. Preferir migration compensatória. Num upgrade, migrate:rollback reverte o lote novo. Após migrate:fresh, todas as migrations podem pertencer ao mesmo lote; rollback pode remover também o legado. RESTRICT deve bloquear dependências externas; não contornar com CASCADE. Manter aplicação compatível com o esquema restaurado. Rollback de esquema não reconverte automaticamente dados para MySQL.

Fontes técnicas

https://www.postgresql.org/docs/16/ddl-constraints.html https://postgis.net/docs/ST_IsValid.html https://postgis.net/docs/ST_IsEmpty.html

Checklist para cada ambiente

Consultar validation.md para as evidencias do ensaio local ja executado. Os itens seguintes devem ser repetidos no ambiente de destino.

• Reconciliação autorizada e migrations históricas preservadas.
• Catálogo, dicionário e SQL gerados da mesma representação.
• UUID novos, FKs compatíveis, decimais, geometrias e índices explícitos.
• Contactos N:N e documentos tipados.
• Extensões preservadas no rollback.
• Lacunas documentadas e fora do DDL.
• migrate:fresh --seed e rollback confirmados em PostgreSQL/PostGIS.
• Suite da aplicação executada em PostgreSQL.
• Matriz de permissões, importação real, reconciliação e restauro validados.
• Desempenho confirmado com volume e SLO aprovados.