# 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.
- [x] Reconciliação autorizada e migrations históricas preservadas.
- [x] Catálogo, dicionário e SQL gerados da mesma representação.
- [x] UUID novos, FKs compatíveis, decimais, geometrias e índices explícitos.
- [x] Contactos N:N e documentos tipados.
- [x] Extensões preservadas no rollback.
- [x] 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.