Investidor-V2/docs/investmoz/reference-schema-reconciliation.md

Reconciliação do DDL de referência — 30/09/2026

Origem: anexo ce3b9157-6463-4c3f-af50-6d53cba78a23/Pasted text.txt, capítulo 22. A instrução «Assumir que todas as fase estão aprovadas» substitui a pendência de autorização de fases do diagnóstico anterior. Não se exige nova aprovação genérica. O requisito de concluir a correspondência antes do DDL continua aplicável.

Evidência executada

tools/inventory-reference-schema.php consulta PostgreSQL numa transacção REPEATABLE READ, READ ONLY. Inventaria tabelas e vistas, colunas/tipos/defaults, constraints, índices, triggers e contagens, sem exportar registos pessoais nem credenciais.

Resultado: 237 tabelas, 2.343 colunas, 806 índices, 1.171 constraints. Inventário privado: storage/app/private/reference-reconciliation-20260930-042147/inventory.json; SHA-256 bbd0cd93d590be0d4121efad6009e66f1a545c280f2491fd845831070712d723.

O total inclui schemas legados e tabelas de extensões. Não significa 237 entidades aplicacionais distintas. A evidência é um inventário, não um backup restaurável nem certificado de qualidade dos dados.

Matriz de correspondência

As decisões abaixo seleccionam objectos reais. «Estender» não significa que a alteração já foi aplicada. Nenhuma equivalência parcial é declarada cobertura integral.

Conceito proposto	Objecto existente / evidência no repositório	Cobertura e lacunas	Decisão técnica
Fontes / data_sources	public.geo_sources (migration territorial_registry); public.investment_legal_sources (investment_zone_foundation); public.ai_sources; investmoz.fontes_dados; mne.source_records	Há cinco mecanismos especializados, com identidades, validações e consumidores diferentes. A fonte jurídica não é automaticamente autorização para IA nem proveniência cartográfica. Não existe correspondência transversal comprovada.	Mapear por compatibilidade, preservando tipo e schema na identidade. Não criar data_sources nem fundir registos por URL apenas. A definição do adaptador e da referência transversal ainda falta.
Diplomas / legal_instruments	public.investment_legal_sources; modelo InvestmentLegalSource; serviço InvestmentZones	Diploma, artigo, entidade competente, URL, vigência, versão, proprietário e revisor já existem. Tipo, número estruturado e publicação não têm colunas próprias.	Estender este mestre com os campos efectivamente necessários; não duplicar diplomas em legal_instruments. Documentos legais do portal conservam a referência ao ficheiro.
Organizações / organisations	public.organizations, memberships; migration investmoz_identity; mne.organizations separado	Mestre público UUID; pertenças existentes. MNE não está integrado como autoridade. Tax identifier, contactos e site não devem ser copiados silenciosamente entre módulos.	Reutilizar public.organizations; mapear MNE apenas por vínculo comprovado. Preservar IDs e contas bigint.
Áreas administrativas	public.geo_locations, geo_territory_profiles, geo_names; seis tabelas investmoz.provincia a aldeia_quarteirao; TerritorialRegistry	Mestre aplicacional UUID e cadastro administrativo inteiro coexistem: 1.990 geo_locations e 21.410 unidades nas seis tabelas. Códigos/níveis precisam de correspondência, não de conversão por posição ou nome.	Mapear por compatibilidade; não criar administrative_areas. Preservar a hierarquia completa, IDs e precisão.
Entidades territoriais	economic_clusters, development_corridors, investment_zones, value_chains, value_chain_links; migrations clusters/corridors/zone_foundation	Tipos especializados e relações já existem. Subcluster/nó territorial não têm um mestre identificado; não confundir elo de cadeia com nó geográfico.	Reutilizar mestres especializados e estender relações explícitas; não criar territorial_entities como segundo cadastro.
Investimentos	investment_items, investment_item_projects, investment_item_opportunities, projects, opportunities, existing_businesses; InvestmentIdentity	6 items ligados a 6 oportunidades, 16 projectos e 0 negócios. O item é identidade de ligação, não cópia completa da ficha. IDs UUID e bigint têm contratos distintos.	Reutilizar InvestmentIdentity e os mestres. Não criar investments; não cadastrar projectos em massa só para preencher a ponte.
Relações	cluster_projects, corridor_projects, corridor_clusters, opportunity_*, investment_zone_links, investment_zone_relations	FK explícitas; relações de zona já têm fonte, vigência, validação, associação, prioridade e justificação. Nem todos os pivots têm essa cobertura.	Estender somente pivots deficientes; manter os actuais. Não criar investment_relations polimórfica concorrente.
Dependências	complementary_project_links, migration investmoz_clusters	Direcção anchor→complementary, tipos dependency/enabler/supplier/market, auto-relação recusada. Não foi identificado controlo de ciclos indirectos ou concorrentes.	Estender esta tabela e o serviço de escrita para dependency; não tratar supplier/market como dependência acíclica. Falta implementar/testar controlo de ciclos.
Geometrias	geo_geometries, project_locations, investment_zone_geometries; migrations geography/zone_foundation	PostGIS 4326, 2D, não vazio, válido, tipo consistente e limites geográficos já impostos. Zonas distinguem perímetro oficial/influência/site e fonte legal.	Reutilizar. Não criar spatial_features nem duplicar geometria em cada entidade. Pertença jurídica nunca inferida por ST_Intersects.
Instalações	existing_business_objects; mne.assets, real_estates, real_estate_units, improvements; respectivas migrations e serviços	Existem activos/instalações de negócios, mas não um inventário operacional de lotes/capacidade de zonas. Payload privado não é uma tabela de reservas.	Criar apenas a relação/entidade operacional de instalação territorial ausente, após distinguir instalação de activo patrimonial. Não copiar os activos MNE. Ainda não implementada.
Regras regulatórias	investment_legal_sources, regras de publicação em InvestmentZones, mne.restrictions, portal_resources	Diplomas, restrições patrimoniais e recursos existem; não foi encontrado cadastro de regras territoriais versionadas dos cinco tipos do anexo.	Criar regras territoriais referenciando o diploma existente, com FK explícitas; preservar restrições patrimoniais. Ainda não implementado.
Documentos	public.documents, pivots *_documents, portal_resources; mne.documents e qualificações skills_edu	Mestre público tem UUID, chave, MIME, checksum, classificação e versão; domínios mantêm ligações próprias. Novos campos de vigência/título/fonte exigem mapeamento.	Reutilizar documents e pivots; não criar outro documents nem copiar ficheiros. MNE conserva contrato enquanto não reconciliado.
Indicadores	Contagens calculadas em EducationController; skills_edu.skill_gaps; conteúdo de investment_dossiers	Existem métricas calculadas, mas não série genérica com definição, unidade, natureza, período, fonte e aprovação. Lacuna de competências não equivale a qualquer indicador.	Criar série de indicadores apenas para essa lacuna, com proprietário por FK explícita. Não persistir cópia das contagens dos dashboards. Ainda não implementado.
Manifestações	interest_requests, interest_submission_receipts, leads, contacts, consents, outbox_events; InterestSubmission e ConvertInterestToLead	Fluxo de interesse e CRM existente; consentimentos e recibos separados. Manifestação não é acto administrativo nem candidatura.	Reutilizar fluxo e IDs; estender contexto/SLA onde faltar, sem expressions_of_interest paralelo.
Versões	version_no dos mestres; investment_zone_revisions, geo_territory_revisions, existing_business_revisions, investment_submission_revisions	Snapshots especializados existem; version_no isolado não permite reconstrução. Não há histórico completo de todos os mestres.	Reutilizar históricos por domínio e estender cobertura; não criar entity_versions que duplique snapshots existentes.
Auditoria	public.audit_events, PortalAudit, trigger imz_audit_events_immutable; auditorias especializadas mne/skills_edu	Auditoria pública já recusa UPDATE/DELETE/TRUNCATE por statement, incluindo zero linhas. Conta proprietária pode alterar DDL.	Reutilizar; preservar tipos e segregação de dados. Não substituir UUID por bigserial nem criar outro audit_events público.

Decisões e limites

Responsável pela autorização das fases: utilizador, instrução de 30/09/2026. Decisões técnicas: reconciliação acima, baseada no inventário e no código. Esta identificação não inventa revisores humanos, mandatos públicos, aprovação jurídica ou testes não executados.

Não executar o bloco BEGIN…COMMIT do anexo: criaria mestres paralelos e IF NOT EXISTS ocultaria divergências, por exemplo em documents e audit_events. Não eliminar os schemas existentes ou aplicar DROP CASCADE. Nenhuma migration nova foi preparada nesta etapa: ainda faltam contratos de compatibilidade e desenho detalhado das extensões/criações identificadas. O gate técnico de fecho da reconciliação está, por isso, incompleto, apesar da autorização de todas as fases.

Reconciliação, testes e rollback a executar com as migrations

1. Guardar inventário e backup restaurável de todos os schemas; restaurar isoladamente e reconciliar contagens. O inventário acima não substitui este passo.
2. Congelar por migration os objectos/colunas/restrições novos e a decisão desta matriz que os justifica. Não reescrever migrations já aplicadas.
3. Validar FK, unicidade e duplicados lógicos com relatório de excepções; não eliminar ou fundir por semelhança de nome.
4. Verificar geometrias por validade, vazio, SRID e igualdade geométrica quando houver transformação. Manter geometrias restritas fora de respostas públicas.
5. Exercitar dependências directas/indirectas, updates, restauro lógico e duas sessões concorrentes. A auto-relação actualmente recusada não prova ausência de ciclos.
6. Exercitar autorização, datas, versões, consentimento, idempotência e contratos de URL/API. Testes devem usar dados sintéticos numa base isolada, nunca limpar a base operacional.
7. Comparar contagens/checksums antes/depois e IDs dos mestres. Aceitar somente as diferenças explicitadas no plano da migration.
8. DOWN remove apenas objectos introduzidos, com RESTRICT, recusando perda de novos dados. Consolidar dados exige mapa reversível de IDs e restauro testado; não foi realizada consolidação nesta etapa.

Estado real da entrega

Executados: inventário real e análise dos 16 conceitos, com decisões de reaproveitamento e lacunas identificadas. Não executados: novas migrations, consolidação, testes de concorrência, reserva de instalações, motor regulatório, séries de indicadores, alterações de UI ou deploy. O pacote completo pedido ainda não está concluído. A aprovação das fases não está pendente; o trabalho restante é técnico.