Files
Investidor-V2/docs/investmoz/gis/territorial-mvp.md
T
nala 1106509116
tests / ci (push) Canceled after 0s
vrsao 2
2026-10-08 14:02:01 +02:00

7.9 KiB
Raw Blame History

MVP territorial — implementação incremental

28/09/2026. Fonte funcional: novo documento «InvestMoz — Modelo de Dados Geográficos, Plano de Implementação do MVP e APIs Territoriais», recebido nesta sessão com autorização integral. Branch feature/territorial-mvp, preservando o Mercado de Negócios já implementado. Esta entrega é um subconjunto funcional; não é conclusão integral do MVP.

Decisão de compatibilidade

Manter geo_locations como identidade única referenciada pelos módulos existentes. Não criar cinco cadastros independentes que dupliquem os UUID. O discriminador passa a admitir admin_post e locality, além dos tipos existentes. geo_territory_profiles acrescenta proveniência, vigência, estado, ISO e capital por referência. Nomes multilingues ficam em geo_names, com índice de um nome oficial por idioma/entidade. As cinco tabelas geo_country/geo_province/etc. do documento são representadas por tipos e perfis; views com esses nomes ainda não foram criadas.

O índice legado de código/tipo é global, mais restritivo que código de província por país. Não foi relaxado nem recodificado o legado sem mapeamento; a importação deverá distinguir código canónico e código oficial da fonte. Não se inventaram códigos oficiais ou coordenadas. O Excel conhecido tem 20.407 linhas após o cabeçalho, mas ainda não foi transformado numa hierarquia aprovada.

Modelo e regras implementadas

Migration 2026_09_28_150000_territorial_registry.php acrescenta cinco tabelas:

Tabela Finalidade e controlos
geo_sources Fonte, entidade, referência, licença, checksum, versão, data, CRS original e estado; checksum/versão únicos; editor/revisor e evidência da decisão
geo_territory_profiles FK única para geo_locations; fonte, ISO2/ISO3 opcionais únicos, capital por FK, vigência, estado, editor/revisor/publicador
geo_names Nomes/idiomas por FK; nome normalizado e oficial; unicidade por entidade/idioma/nome e um oficial por idioma
geo_territory_revisions Snapshot e motivo cifrados, actor, versão e checksum; UPDATE/DELETE recusados pelo trigger
geo_write_receipts Actor, chave UUID, escopo, hash do pedido e resposta cifrada; unicidade e serialização contra duplicação concorrente

Hierarquia validada no serviço: país sem pai, província→país, distrito→província, posto→distrito e localidade→posto. Tipo é imutável; pai apagado, salto de nível e código/nome duplicado sob o mesmo pai são rejeitados. Alterações são serializadas, com versão esperada, snapshot e invalidação de publicação. Excepções de localidades sem posto ainda não têm workflow; não se cria pai fictício.

Publicação exige fonte aprovada, vigência actual e pai publicado. Editor, revisor e publicador distintos; técnico com manage-portal não recebe função editorial automaticamente. A consulta percorre ascendentes e oculta toda a descendência se qualquer fonte/ascendente for revogado, arquivado, privado, expirado ou eliminado. Não depende de cache. Capital não publicada não é exposta por FK na resposta.

APIs implementadas

  • GET /api/v1/geo/countries, /provinces, /districts, /admin-posts, /localities, /search.
  • GET /api/v1/geo/territories/{type}/{id}.
  • POST /api/v1/geo/sources e /sources/{id}/transitions.
  • GET /api/v1/geo/sources e /drafts: metadados e fila editorial para gestores com MFA; não são consultas públicas.
  • POST /api/v1/geo/territories, PATCH /territories/{id}, POST /territories/{id}/transitions.

Listagens usam cursor e limite 1–100. Pesquisa por nome/código e nomes alternativos; filtros por pai e ascendentes. Caracteres de wildcard na pesquisa são escapados. Dados devolvidos por allowlist; revisões e motivos não entram na consulta publicada.

OpenAPI do subconjunto, gerado por tools/territorial-openapi.mjs. Sessão Laravel e email verificado são o adaptador local; OAuth2/OIDC ainda não implementado. Escritas exigem CSRF/origin, gestor com MFA, papel configurado e Idempotency-Key UUID. Replay revalida permissões e recusa corpo diferente com a mesma chave. Correlation ID é gerado por pedido. Erros capturados no middleware territorial usam Problem Details; auth/rate-limit exteriores continuam no formato global da aplicação.

Flag INVESTMOZ_TERRITORIAL_ENABLED desactivada por defeito. Papéis: INVESTMOZ_TERRITORIAL_EDITORS, INVESTMOZ_TERRITORIAL_REVIEWERS, INVESTMOZ_TERRITORIAL_PUBLISHERS, todos sem nomeações por defeito. A nomeação técnica não prova mandato institucional. Aprovação de fonte exige entidade/licença preenchidas e referência de evidência, analisadas por pessoa diferente do editor; não equivale a verificação automática externa.

Testes e limites

Testes focados iniciais: 5 testes / 40 verificações aprovadas. Incluem invisibilidade de rascunhos, hierarquia, duplicados, conflito de versão, filtros por ascendente, revogação, MFA, idempotência, revisão/publicação independente e rollback vazio seguido de recusa com dados. PHPStan e Pint aprovados. Fixtures exclusivamente sintéticas na base isolada, incluindo nomes e aprovação de teste.

Nenhuma geometria nova, transformação, importação real, fonte institucional ou nomeação de responsáveis foi inventada. As geometrias/PostGIS/GiST legadas são preservadas. Este incremento não implementa boundary versions, centróides aprovados, containment, resolve, near, bbox, percentagem de cobertura, territorial_assignment, árvore histórica, pipeline de importação ou UI administrativa. Parâmetros geométricos nas listagens são rejeitados, não ignorados como se tivessem sido aplicados.

Também faltam integração dos selectores nos módulos, migração dos textos legados, métricas de qualidade/p95, carga, acessibilidade/UAT, homologação do provedor OIDC e operações de limites/capitais/nomes pela API. Campos presentes no schema não representam jornadas implementadas.

Gates e rollback

Execução local: backup storage/app/private/zones-backup-20260928-184538/ com restauro isolado e 108 tabelas reconciliadas. Migration 150000 aplicada; base passou a 113 tabelas e 41 migrations. As 108 tabelas anteriores conservaram contagens, excepto o ledger de migrations (40→41). As cinco tabelas territoriais novas estão vazias; nenhum território/fonte/geometria real foi criado. Configuração anterior preservada privadamente; INVESTMOZ_TERRITORIAL_ENABLED=true apenas local. Papéis editoriais continuam sem nomeações.

Suite completa anterior às duas consultas administrativas: 162 testes, 1687 verificações aprovadas, 33790 ms; PHPStan e Pint aprovados. Consultas administrativas verificadas depois nos testes focados. Não houve frontend novo neste incremento nem alegação de validação visual do MVP territorial.

G1: desenho adaptado documentado; fontes/licenças/códigos reais continuam por comprovar. G2: núcleo técnico e testes de reversão executados em ambiente isolado. G3: subconjunto de APIs testado; OAuth, contratos completos e UI pendentes. G4: No-Go para produção ou conclusão integral do MVP.

down() recusa evidências ou novos tipos territoriais existentes antes de qualquer DROP; não usa CASCADE nem DROP EXTENSION. Quando há dados, suspender a flag e corrigir progressivamente, preservando revisões. Nenhuma aprovação genérica substitui autorização de divulgação de um limite ou homologa a qualidade territorial do Excel.