58 lines
7.9 KiB
Markdown
58 lines
7.9 KiB
Markdown
# 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](territorial-openapi.json), 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.
|