Investidor-V2/docs/investmoz/zones/operations.md

# Administração e operação do núcleo local

## Acesso e preparação

1. Usar uma conta gestora existente, email verificado e dois factores confirmados nas definições da conta.
2. A administração designa revisores através de `INVESTMOZ_ZONE_LEGAL_REVIEWERS`, `INVESTMOZ_ZONE_GIS_REVIEWERS` e `INVESTMOZ_ZONE_PUBLISHERS` (emails separados por vírgula). Depois de alterar o ambiente, limpar/recriar a cache de configuração. Não incluir credenciais nos relatórios ou no Git.
3. Estas listas são controlo de acesso ao software, não uma atribuição de competência pública. O próprio editor não pode validar/publicar o seu registo, mesmo constando de todas as listas.
4. Entrar em `/management/investment/zones`. Um gestor sem MFA recebe 403 e deve configurar a conta antes de continuar. Acesso público em `/zonas`.

## Cadastro e validação

- Criar rascunho com código interno único, nome e categoria proposta. Usar pendente se o enquadramento não estiver comprovado.
- Abrir a ficha e completar PT/EN, território, operador já cadastrado e referência jurídica. Os selectores administrativos apresentam até 200 registos de destino e 100 fontes; para catálogos maiores falta pesquisa paginada específica. Não criar uma organização apenas para ultrapassar a validação.
- Registar fonte HTTPS, diploma, artigo, entidade indicada, início e fim de vigência. Não há download automático do URL. Outra pessoa designada para revisão jurídica confere e valida a referência. Alteração do texto/documento exige nova referência; revogar retira a fonte dos resultados dependentes.
- Guardar alterações gera nova versão em rascunho. Outra pessoa designada para publicação revê conteúdo e referência; publicar exige os campos previstos e fonte vigente. Esta publicação editorial não equivale a certificado/licença.
- Se a página estiver desactualizada, o servidor responde 409; recarregar e rever as diferenças antes de repetir. Suspender retira a ficha sem eliminar o histórico.

## Associações e GIS

- Seleccionar oportunidade, cluster, corredor ou projecto existente. Indicar papel, natureza da associação, fonte, justificação e vigência. Relações potenciais continuam potenciais depois da validação; a validação não as torna oficiais.
- Relação oficial exige referência jurídica própria. Uma âncora pode pertencer a várias zonas e parques; não há exclusividade implícita. Outro gestor revê a associação; par repetido responde 409.
- Submeter GeoJSON 2D no SRID 4326 com até 200 KB, fonte, finalidade e data. Perímetro oficial exige polígono/multipolígono e referência jurídica; não se deve desenhar fronteira estimada como oficial.
- Revisor GIS distinto valida e autoriza divulgação. Sobreposição de perímetros já autorizados bloqueia a operação e exige esclarecimento documental; não existe botão para declarar automaticamente regular a sobreposição.
- Mapa público só inclui geometrias autorizadas de zonas e fontes vigentes. É esquema sem mapa-base, não planta de demarcação. A API limita a 100 feições e aceita janela `bbox[]`; a ficha e o apoio mantêm-se disponíveis quando o mapa falha.

## Atendimento e reconciliação

«Manifestar interesse», «Solicitar dossier» e «Pedir reunião» abrem o percurso privado existente. São pedidos assistidos, não decisões administrativas, agendamentos confirmados ou distribuição automática de documentos. O investidor completa os dados e consentimento; recebe protocolo único. A origem zona/versão/finalidade segue no registo interno do pedido. A passagem por uma oportunidade mantém o contexto `zone_id` validado no servidor.

Para identidade canónica, executar primeiro `php artisan investment:reconcile-identities` com o PHP validado. Rever o relatório privado e fazer backup/restauro. Só então `php artisan investment:reconcile-identities --apply`. O comando mapeia chaves existentes; não altera estado, fonte, URL ou título legado, não une projectos por semelhança e não publica registos. Reexecutar é idempotente.

## Recuperação e monitorização

Preservar a chave Laravel juntamente com os backups protegidos: snapshots encriptados dependem dela. Antes de alterações de esquema, exportar a base, restaurar isoladamente e conferir contagens/checksum. Reverter migrations vazias em ordem inversa; se houver dados, restaurar um backup numa base isolada e reconciliar, nunca apagar tabelas para resolver um erro.

Monitorizar 403/409/422/429, erros 5xx, crescimento de `failed_jobs`, pendências de revisão e validade das fontes. Alertas automáticos de expiração, SLO/SLA de produção e formação com utilizadores reais continuam pendentes. Não activar SuiteCRM/Alfândegas externos sem acordo e ensaio próprios.

Go local: núcleo testado e backups reconciliados. No-Go de produção: fontes reais, mandatos, segurança integral, carga, acessibilidade assistiva, UAT, suporte e recuperação operacional ainda não homologados.