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

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.
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.
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.
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.
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.

20 KiB Raw Blame History Unescape Escape