# Simulador Fiscal InvestMoz — Governação do MVP **Fase:** 0 — Governação **Estado:** gate da Fase 0 **APROVADO PARA CONTINUAÇÃO** por instrução explícita do utilizador em 2026-10-01; blockers específicos de domínio continuam sujeitos aos gates das fases correspondentes. **Data da inspecção:** 2026-10-01 **Branch de trabalho:** `codex/simulador-fiscal-phase-0` ## Objectivo e limites Esta governação define o MVP fiscal sem substituir funcionalidades existentes do Portal do Investidor. O âmbito funcional do Simulador Fiscal fica limitado ao que está aprovado nesta especificação; não declara homologação, publicação de regras, integração operacional ou cobertura fiscal que não tenha evidência. | Tratamento | Âmbito aprovado para o MVP | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Calcular | IRPC; IRPS sobre remunerações; IVA; ISPC; retenções na fonte; INSS; valor aduaneiro; direitos aduaneiros; ICE; IVA na importação; obrigações fiscais/cambiais; cenários; relatórios PDF e JSON. | | Identificar e orientar, sem cálculo automático | Imposto do selo; impostos autárquicos; mais-valias; preços de transferência; convenções completas de dupla tributação; benefícios complexos ZEE/ZFI; regimes sectoriais. | | Fora desta release | Manifestações formais; oportunidades de negócio; conversões para projecto/oportunidade; CRM completo; conta avançada do investidor; assistente inteligente. | Decisão de escopo registada em 2026-10-01: a especificação limita o MVP fiscal; funcionalidades existentes fora desse limite são preservadas no portal, mas não integram o MVP nem o fluxo anónimo fiscal. ## Baseline técnico inspeccionado - Backend Laravel 13.30.1; PHP 8.5.11 CLI; React 19/Inertia/Vite; Node 24.20.0 e npm 11.19.0. Não é uma aplicação Next.js. - `composer.lock` e `package-lock.json` existem. `vendor/` e `node_modules/` estão presentes. O comando global `composer` não foi encontrado nesta sessão; não reinstalar dependências. - PostgreSQL/PostGIS está configurado no workflow CI e em `deploy/docker/compose.yaml`. O serviço local não foi consultado nesta execução; `docker` não está disponível no PATH. - Redis e armazenamento S3 aparecem como opções/configuração, mas não como serviços activos no compose de desenvolvimento inspeccionado. Não foi confirmada conectividade a IAM/SSO externo. - O workflow CI usa PHP 8.5, Node 24 e PostgreSQL/PostGIS 17/3.5. O PHPUnit 12.5.34 está instalado. - Existem contratos OpenAPI por domínio: alguns 3.1.0 e outros 3.0.3. Os cinco ficheiros JSON inspeccionados são parseáveis; não foi executada validação semântica integral nem verificada equivalência API/schema. - Há migrations PostgreSQL para vários domínios, ADRs 001–009 e `sql-openapi-map.csv`. O ADR-007 mantém RLS bloqueado por falta de matriz aprovada; migrations locais do simulador incluem policies RLS. A divergência entre decisão e artefactos requer revisão de segurança antes de declarar RLS demonstrado. - `.env.example` foi lido apenas para inventariar nomes de configuração. `.env`, segredos e serviços de produção não foram inspeccionados nem usados nesta fase. ## Matriz de conformidade e rastreabilidade | Requisito/fase | Evidência actual | Estado | Lacuna ou divergência | Ficheiros/áreas de referência | Próximo gate | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Fase 0 — governação | Baseline, decisões e ADRs; este documento acrescenta escopo, RACI funcional, riscos, backlog e gates | CONFORME PARA INICIAR A FASE 1 | Responsáveis nominais e aprovações fiscal/jurídica/segurança/ops continuam necessários antes dos gates que delas dependem | `docs/implementation/baseline.md`, `docs/implementation/adr/`, este ficheiro | Gate da Fase 1 | | Fase 1 — fundação e contratos executáveis | Migrations, mapa SQL/OpenAPI, contratos por domínio e teste de ciclo de schema | PARCIAL | Contratos fragmentados em 3.0.3/3.1.0; validação integral e reconciliação de todos os caminhos/colunas não demonstradas neste gate | `database/migrations/`, `docs/implementation/sql-openapi-map.csv`, `docs/investmoz/*/openapi.json` | Inventário aprovado, validação OpenAPI integral e testes seguros em DB descartável | | Fase 2 — repositório legislativo | Existe rota de consulta de fontes legislativas e registos jurídicos noutros domínios | PARCIAL | Não há evidência suficiente de repositório fiscal versionado com disposições, vigência, hashes, relações, ingestão e pesquisa integral | `app/Http/Controllers/Api/V1/LegislationSourceController.php`, migrations, `routes/api.php` | Contrato e fontes oficiais aprovadas; verificar CRUD/importação e integridade | | Fase 3 — regras e publicação | Há catálogos versionados e padrões de revisão noutros domínios | AUSENTE para regras fiscais | Não foi identificada evidência de rule sets fiscais, parâmetros com fonte oficial, elegibilidade, revisão de quatro olhos, testes dourados e publicação imutável | migrations, models/services fiscais (a inventariar na Fase 3) | Aprovação de fontes, regras, responsabilidade fiscal/jurídica e vigência | | Fase 4 — API e formulário | `/Simulador`, catálogos, snapshots e execução aritmética existem | BLOQUEADO por divergência | O formulário contém identidade/contactos e finalidade de manifestação/oportunidade; a especificação limita o modo anónimo a dados económicos/fiscais/territoriais/operacionais e exclui esses fluxos. Decidir compatibilidade semântica antes de alterar a UI/API | `resources/js/lib/simulation-form.ts`, `resources/js/components/simulation-form.tsx`, `StoreSimulationFormDraftRequest.php`, `SimulationFormDrafts.php` | Decisão de produto/privacidade sobre fluxo anónimo e separação de funcionalidades fora da release | | Fase 5 — motor fiscal | Motor actual executa aritmética genérica introduzida pelo utilizador | AUSENTE para o âmbito fiscal | Não há evidência de cálculos fiscais oficiais de IRPC, IVA, ISPC, IRPS, INSS ou retenções com regras/fontes aprovadas, Decimal, arredondamento fiscal e casos dourados | `app/Services/SimulationExecution.php`, `app/Jobs/RunSimulation.php`, `docs/investmoz/simulations/openapi.json` | Aprovação de regras fiscais e especificação matemática antes de implementação | | Fase 6 — aduanas, câmbios e calendário | Campos/estrutura parcial de simulação e jobs genéricos | AUSENTE para os cálculos e calendário pedidos | Valor aduaneiro, direitos, ICE, IVA de importação, obrigações cambiais/fiscais e calendário não estão demonstrados como motor completo | app/migrations de simulação e integrações | Fontes e regras oficiais; contratos de moedas/origem e jobs/retries | | Fase 7 — relatórios e homologação | Snapshot de relatório JSON e hashes existem | PARCIAL | PDF, reconciliação integral API/DB/PDF/JSON, homologação, acessibilidade manual, resiliência e DR não demonstrados | `SimulationReport`, controller/serviço de simulação, testes | Contrato PDF/JSON, casos dourados, acessibilidade e prova de recuperação | | Fase 8 — release e estabilização | Workflow CI e compose de desenvolvimento existem | PARCIAL | Não há evidência de Go/No-Go fiscal, release imutável, backup/restauro, rollout/rollback ensaiados ou hypercare | `.github/workflows/tests.yml`, `deploy/docker/compose.yaml` | Aprovação de release, owners operacionais e evidência de rollout/rollback | ### Divergências que não serão resolvidas por inferência 1. **Identidade no modo anónimo:** decisão de escopo do utilizador aplica a regra da especificação: o simulador fiscal anónimo pede apenas dados económicos, fiscais, territoriais e operacionais. O formulário actual oferece campos pessoais; a Fase 4 deve separar esses fluxos sem apagar código/dados do portal. 2. **Oportunidades/manifestações:** decisão de escopo do utilizador mantém esses fluxos fora desta release fiscal e preserva código/dados existentes. A Fase 4 deve removê-los da experiência fiscal sem declarar funcionalidades do portal como MVP fiscal. 3. **RLS:** ADR-007 bloqueia activação sem matriz actor/recurso/operação e papéis SQL, enquanto migrations locais contêm policies. A prova de política eficaz, grants e papel runtime permanece BLOQUEADA. 4. **Aprovação normativa:** nenhum cálculo ou taxa fiscal pode ser codificado/publicado com base apenas na fórmula aritmética existente ou em defaults do cliente. Cada regra necessita fonte oficial, período de vigência, aprovador fiscal e revisão jurídica. 5. **Dados/ambientes:** estado actual de migrations e serviços só pode ser confirmado em ambiente de teste isolado; não inferir por CI ou documentação o estado de desenvolvimento/produção. ## RACI funcional proposto Não foram atribuídos nomes. A nomeação de responsáveis e a aprovação desta matriz são pendências do gate. | Actividade | Responsável (R) | Accountable (A) | Consultados (C) | Informados (I) | | ---------------------------------------------- | ------------------------------ | ------------------------- | ---------------------------- | ------------------- | | Aprovar fonte, regra, vigência e casos fiscais | Especialista fiscal | Dono de produto fiscal | Jurídico, dados, engenharia | QA, operações | | Publicar regra versionada | Engenharia fiscal | Dono de produto fiscal | Fiscal, jurídico, segurança | QA, operações | | Aprovar privacidade e fluxo anónimo | Privacidade/protecção de dados | Dono de produto | Jurídico, segurança, fiscal | Engenharia, QA | | Aprovar IAM/RLS/grants | DBA/segurança | Arquitectura de segurança | Engenharia, operações | Dono de produto, QA | | Homologar cálculos e relatórios | QA fiscal | Dono de produto fiscal | Fiscal, jurídico, engenharia | Operações | | Autorizar release, rollback e DR | Operações/release | Dono de serviço | DBA, segurança, QA, produto | Stakeholders | RACI é uma proposta de funções e não atribui autoridade a pessoas. Gate bloqueado até os responsáveis formais serem indicados e aceitarem. ## Backlog e gates de aceitação | Prioridade | Item | Dependência | Critério de conclusão | | ---------- | --------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------- | | P0 | Resolver divergência do modo anónimo, PII e funcionalidades fora da release | Decisão de produto e privacidade | Formulário e contrato aprovados sem recolha anónima vedada; decisão registada | | P0 | Aprovar fontes, regras, vigência e arredondamento de cada cálculo | Autoridade fiscal e jurídico | Fonte oficial/hash, regra versionada, casos dourados e dupla revisão registados | | P0 | Aprovar matriz IAM/RLS e papéis SQL | Segurança/DBA | Testes actor×recurso×operação com papel runtime sem bypass e contexto limpo | | P1 | Reconciliar OpenAPI integral, migrations e esquema | API/DBA | Validação semântica de contratos e cobertura de operações/campos no CI | | P1 | Implementar cálculos e obrigações do escopo | Regras aprovadas | Testes críticos 100%, totais aplicáveis ≥95%, Decimal e resultados explicáveis | | P1 | Aduanas, câmbios, calendário e jobs | Fontes/regras e contrato operacional | Casos dourados, idempotência/retry, reconciliação e dead-letter demonstrados | | P1 | PDF/JSON e acessibilidade/homologação | Schema de relatório e casos aprovados | API/DB/PDF/JSON reconciliados; teclado/leitor de ecrã/zoom e homologação registados | | P1 | Preparar release, backup/restauro e rollback | Operações/DBA | Release imutável, backup restaurado em prova, smoke tests e rollback ensaiados | ## Métrica, aprovação e bloqueio - Go exige 100% dos testes críticos aplicáveis aprovados e pelo menos 95% de todos os testes aplicáveis aprovados. Cobertura de código é métrica separada. - Ignorados, instáveis, não executados ou sem evidência não contam como aprovados. Um teste aplicável inexistente é lacuna a criar na fase correspondente. - Não há excepção para falha crítica. Uma falha alta só pode ter excepção formal com impacto, controlo compensatório, responsável, prazo e aprovação; após expiração volta a ser bloqueio. - É bloqueio de release qualquer cálculo sem fonte aprovada, elegibilidade presumida, inconsistência API/DB/relatórios, fuga de dados, OpenAPI inválido, RLS não demonstrado, migration irreversível ou recuperação/rollback não provados. ## Evidência desta execução - Branch `codex/simulador-fiscal-phase-0` criada e seleccionada. O working tree tinha alterações locais em `main`; todas foram preservadas e transitam sem commit para a branch. A autoria/intenção de cada alteração anterior não foi auditada nesta fase. - A execução PHPUnit 12.5.34 com PHP 8.5.11 mais recente, anterior a esta fase, iniciou 15 testes de `SimulationExecutionTest|SimulationFormDraftTest`; os 15 pararam antes das asserções com `Unregistered skills_edu schema exists; reconcile before migration.`. A suite não foi aprovada. O `phpunit.xml` define `DB_DATABASE=investmoz_test`, mas não fixa host/porta/credenciais; esses valores podem vir do `.env`. Como o destino não foi confirmado antes daquela execução, o isolamento da base não pode ser afirmado. Não executar testes que migrem/escrevam até confirmar explicitamente uma base descartável isolada. Nesta Fase 0 não se repetiu a execução nem se inspeccionou `.env`. - `node` validou parsing dos cinco contratos OpenAPI indicados acima; não é validação semântica. - Node 24.20.0 e npm 11.19.0 disponíveis. O comando `composer` global e `docker` não foram encontrados no PATH desta execução. Nenhuma dependência foi instalada ou actualizada. - Nesta Fase 0 não foi iniciada ligação a base de dados ou serviço externo. Não se inspeccionou `.env` nem se usaram credenciais de produção nesta fase. O destino da tentativa PHPUnit anterior é uma pendência de segurança operacional, não uma evidência de ambiente de teste seguro. ## Rollback Esta fase cria apenas este documento e uma branch Git. Para reverter o artefacto, remover `docs/implementation/simulador-fiscal-governance.md`. A branch pode ser abandonada sem afectar `main`; não apagar/resetar a branch enquanto o working tree contiver alterações locais. Nenhuma migration, dado ou serviço foi alterado. ## Gate da Fase 0 **Estado proposto: APROVADO PARA AVANÇAR À FASE 1** por instrução explícita do utilizador em 2026-10-01. A decisão aprova o escopo e a continuação faseada; não aprova regras/taxas fiscais nem substitui as aprovações fiscais, jurídicas, de segurança e operacionais exigidas para publicação ou release. **Próxima acção:** executar apenas a Fase 1 com inventário SQL/OpenAPI e validação em ambiente de teste isolado; parar no respectivo gate.