Investidor-V2/docs/investmoz/land-assistance/implementation.md

# Terra e DUAT — implementação técnica e limites

## Estado

Implementação interna preparada; não activar como checklist jurídico nem como canal oficial de submissão. A Lei de Terras, o regulamento aplicável, formulários oficiais e procedimentos locais ainda não foram validados em cópias legíveis. O inventário de ficheiros disponíveis e hashes está em [source-inventory.md](source-inventory.md).

O confronto com o prompt consolidado está detalhado em [requirement-traceability.md](requirement-traceability.md). A triagem legislativa está em [legal-source-review-2026-10-03.md](legal-source-review-2026-10-03.md). A checklist jurídica permanece bloqueada até revisão do Boletim da República e aprovação competente. O pedido de apoio aceita email ou telefone: a migration aditiva permite `interest_requests.email = NULL`, sem email fictício. Integrações downstream que exijam email precisam de validação operacional.

## Funcionalidade incluída

- Guia público, modelo em branco imprimível e fluxo autenticado de rascunho privado.
- Formulário progressivo com dados do requerente, localização por selecção territorial publicada, uso e situação declarados, antecedentes, plano facultativo de exploração, preparação/informação sobre consulta e estado comunicado pelo próprio requerente.
- Referência interna e versões optimistas; cada alteração guarda snapshot cifrado e evento sem conteúdo pessoal.
- Pedido de apoio encaminhado ao CRM `InterestSubmission`, com consentimento, chave idempotente por caso, recibo interno e evento outbox. Um contacto utilizável (email ou telefone) é aceite; a coluna email foi tornada anulável por migration aditiva e reversível com guarda para preservar pedidos telefónicos.
- Acompanhamento e vista de gestão com estados internos. “Encaminhamento preparado” não confirma envio nem recepção por órgão público.
- Cópia preenchida é HTML imprimível/guardar como PDF pelo navegador; não é um PDF oficial preenchível.
- Ficheiros privados limitados a PDF/JPG/PNG e 10 MB. Sem antivírus configurado, ficam em quarentena e não são descarregáveis.

## Limites funcionais e jurídicos

- O selector territorial identifica apenas entradas do catálogo público. Não valida cadastro, limites, titularidade, disponibilidade ou direito.
- Consulta comunitária e dados associados são informação declarada/preparatória; a aplicação não certifica convocatória, presença, acta, consentimento ou suficiência legal.
- Não há submissão electrónica, pagamento de taxas, consulta a processos governamentais nem integração com órgãos públicos.
- Os scans em `Scan/Terras` são imagens sem OCR pesquisável. `DUAT.docx` estava bloqueado por outro processo; não foi contornado. Os originais não foram alterados. Conteúdo exige OCR/abertura autorizada e revisão humana.
- Sem publicação de requisitos legais, prazos, elegibilidade, taxas ou promessa de emissão.

## Confronto com o prompt consolidado

- Percursos, dados condicionais, múltiplas parcelas, plano facultativo, consulta preparatória e acompanhamento interno estão representados no formulário existente.
- As versões em branco e preenchida são páginas imprimíveis. Não são chamadas oficiais nem afirmam recepção pela autoridade. A cópia preenchida reflecte os dados guardados e a versão interna; não tem assinatura simulada.
- A checklist por modalidade/jurisdição/fase não foi activada: os scans ainda não foram lidos e fontes legais integrais não foram reconciliadas. Não substituir esta lacuna por itens presumidos.
- O requisito de contacto “email ou telefone” está coberto no intake local. Consumidores, notificações e exports que não tolerem email nulo ainda exigem verificação antes de operar com pedidos exclusivamente telefónicos.
- Antimalware continua ausente; uploads permanecem em quarentena sem libertação automática.

## Ficheiros principais

- `routes/land-assistance.php`, incluído em `routes/web.php`.
- `app/Http/Controllers/LandAssistanceController.php`
- `app/Http/Requests/StoreLandAssistanceCaseRequest.php`
- `app/Models/LandAssistanceCase.php`
- `database/migrations/2026_10_03_200000_create_land_assistance_cases.php`
- `resources/js/pages/land-assistance/` e `resources/js/layouts/portal-navigation.tsx`
- `docs/investmoz/land-assistance/source-inventory.md`
- `docs/investmoz/land-assistance/requirement-traceability.md`
- `tests/Feature/LandAssistanceTest.php`

## Verificações executadas

- PHP 8.5.11: lint sintáctico dos três ficheiros PHP principais e do teste.
- `npm.cmd run types:check`: TypeScript passou.
- `php artisan route:list --path=terra-duat`: 16 rotas registadas.
- `php artisan test --filter=LandAssistanceTest`: 6/6 testes, 46 asserções, em PostgreSQL 17 QA descartável na porta 55441; a suite PHP integral passou 253/253 (2.590 asserções) nesse ambiente. Nenhuma migration foi aplicada à base operacional; a porta 5432 não foi usada.

## Riscos e pendências

1. Completar confronto artigo a artigo com Boletins da República integrais; registar diploma, artigo, vigência, URL/cópia e revisão jurídica antes de transformar qualquer item em requisito executável.
2. Identificar e revisar por OCR os sete scans, em cópias de trabalho, sem substituir ou publicar os originais.
3. Configurar serviço antivírus/quarentena com estados, auditoria e política de retenção antes de permitir download de uploads.
4. Fazer teste de navegador de passos condicionais, seletores em cascata, gravação/retoma, impressão e permissões de gestão; a evidência automatizada específica desta interface ainda não está registada.
5. Confirmar política de retenção/eliminação de dados pessoais e tratamento de dados sensíveis de comunidade/ocupantes.

## Reversão

A migration tem `down()` protegido: recusa eliminar as tabelas quando há registos. Para reversão depois de uso, preservar exportação cifrada e referências CRM, validar retenção/apagamento, separar/arquivar os registos e só então planear reversão. Não apagar tabelas com casos activos. As rotas/UI podem ser desactivadas por remoção do `require` em `routes/web.php` e do link de navegação, mantendo dados intactos.

## Gate proposto

`PENDENTE — revisão humana`. Fluxo interno implementado; integração de CRM e controles técnicos preparados. Gate público para requisitos legais, checklist e submissão oficial não satisfeito.