19.1 Prompt final para 
Codex
Actua como agente principal de implementação do Simulador Fiscal 
InvestMoz
. Usa esta especificação para determinar o estado pretendido e usa o repositório real para determinar o estado actualmente implementado. Quando existir conflito entre ambos, 
mantem a versão instalada se for a melhor opção
.
OBJECTIVO
Implementar apenas as lacunas comprovadas do MVP fiscal, preservando tudo o que já esteja conforme, funcional, testado e compatível. Executa uma única fase por vez e não avances sem aprovação humana explícita do gate anterior.
REGRA DE ACTUALIZAÇÃO INCREMENTAL
Antes de criar ou alterar qualquer artefacto, inspecciona o repositório, o ambiente e os serviços disponíveis. Para cada requisito, classifica o estado como CONFORME, PARCIAL, AUSENTE ou BLOQUEADO. Mantém sem reescrever o que estiver CONFORME. Corrige somente o que estiver PARCIAL ou AUSENTE. Para itens BLOQUEADOS, não improvises nem contornes controlos: documenta a causa, impacto, dependência e decisão necessária. Não substituas soluções funcionais por preferência técnica.
INSPECÇÃO INICIAL OBRIGATÓRIA
Identifica 
stack
, versões, estrutura, convenções, comandos, CI/CD, testes, manifestos, 
lockfiles
, contentores, variáveis, serviços e restrições. Confirma Laravel, React/Next.js, PostgreSQL/
PostGIS
, Redis, armazenamento de objectos, IAM/
SSO
, 
OpenAPI
 e ferramentas de teste apenas quando existirem. Não assumes nomes, caminhos ou comandos. Antes de alterar, apresenta: plano curto; matriz requisito/evidência/estado/alteração/ficheiros/testes/gate; e lista exacta de ficheiros a criar ou alterar.
DEPENDÊNCIAS
Não actualizes versões fora do escopo. Não reinstales dependências desnecessariamente. Instala ou restaura dependências somente quando faltarem para executar a fase, usando o gestor e o 
lockfile
 existentes, sem alterar versões bloqueadas; regista o comando e qualquer alteração resultante. Se não existir 
lockfile
 ou o ambiente não puder ser reproduzido com segurança, BLOQUEIA.
SEGURANÇA E PRESERVAÇÃO
Trabalha numa 
branch
 dedicada. Não uses produção nem credenciais de produção. Não apagues dados. Não edites migrations já executadas; cria migrations novas e reversíveis. Não uses 
migrate:fresh
, 
reset
, 
drop
 ou 
truncate
 excepto numa base descartável de testes, isolada e explicitamente confirmada. Não alteres interfaces públicas sem versionamento. Não publiques taxas, fórmulas, benefícios ou interpretações sem fonte oficial e aprovação fiscal e jurídica. Não uses 
eval
 ou execução arbitrária. Não guardes 
tokens
 em claro, 
PII
 em 
logs
 ou 
URLs
 assinadas na base. Preserva 
RLS
, 
RBAC
, 
ETag
/
If
-Match, 
idempotência
, 
snapshots
, auditoria, soft delete, retenção e compatibilidade.
ESCOPO DO MVP FISCAL
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 e 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 de ZEE/ZFI; regimes sectoriais.
FORA DESTA 
RELEASE
: manifestações formais; oportunidades de negócio; conversões para projecto ou oportunidade; integração CRM completa; conta avançada do investidor; assistente inteligente. Não declares nem testes estas funcionalidades como implementadas no MVP. Apenas preserva pontos de extensão existentes.
MODO ANÓNIMO
Recolhe apenas dados económicos, fiscais, territoriais e operacionais necessários ao cálculo. Não solicita nome, NUIT, contactos, identificação, documentos de manifestação ou consentimentos de publicação. Emite o 
token
 uma única vez, persiste apenas SHA-256, aplica retenção e expurgo, protege por 
RLS
 e não expõe 
token
 ou 
hash
 em 
logs
 ou respostas. Para guardar numa conta ou iniciar futura manifestação, exige autenticação e consentimento separado.
FORMULÁRIO
Implementa /Simulador conforme o 
schema
 aprovado. Todo campo com duas ou mais opções usa controlo de selecção acessível apropriado; listas extensas devem ser pesquisáveis. Campos 
multivalor
 permitem selecção e remoção por teclado. Dependências limpam filhos inválidos e “Outro” abre campo condicional. Não definas taxas, regimes, elegibilidade ou pressupostos fiscais por defeito. 
MZN
 pode ser apenas sugestão operacional confirmável pelo utilizador; se o modelo de dados exigir moeda, a escolha explícita prevalece e qualquer 
default
 técnico deve ser neutro ou documentado. Implementa 
autosave
, retoma, 
loading
, erro, conflito, sessão expirada, validação cliente/servidor, móvel, teclado, leitor de ecrã, contraste, zoom e prevenção de submissão duplicada.
FASES E GATES
Executa pela ordem 0–8: 0 Governação; 1 Fundação e contratos executáveis; 2 Repositório legislativo; 3 Regras e publicação; 4 API e formulário; 5 Motor fiscal; 6 Aduanas, câmbios, cenários e calendário; 7 Relatórios e homologação; 8 
Release
 e estabilização. Em cada fase, executa apenas os testes aplicáveis que existam ou que a própria fase deva criar. Um teste inexistente que seja requisito da fase é AUSENTE, não “falhado”; cria-o dentro do escopo antes de avaliar o gate. Um serviço externo indisponível deve ser simulado apenas por 
mock
 oficial do projecto e nunca contado como validação de integração real.
MÉTRICA ÚNICA DE APROVAÇÃO
Go
 exige 100% dos testes críticos aplicáveis aprovados e pelo menos 95% dos testes aplicáveis aprovados. “Cobertura de código” é uma métrica separada e não substitui a percentagem de testes aprovados. Testes não aplicáveis exigem justificação e aprovação formal e não entram no numerador nem no denominador. Testes ignorados, instáveis, não executados ou sem evidência não contam como aprovados.
PRIORIDADE DOS ARTEFACTOS
1. decisões e escopo formalmente aprovados; 2. requisitos desta especificação; 3. contrato 
OpenAPI
 integral validado; 4. migrations e 
schema
 executáveis; 5. código e testes; 6. exemplos e extractos. O repositório demonstra o estado actual, mas não pode contrariar silenciosamente o escopo aprovado. Extractos SQL/
OpenAPI
 deste documento são referências, não substituem artefactos integrais validados.
EXECUÇÃO POR FASE
Inspecciona; compara; preserva; propõe alterações mínimas; 
verifica pré-condições; implementa; executa comandos reais; testa; corrige somente erros do escopo; actualiza documentação; gera evidências; propõe AVANÇAR, CORRIGIR ou BLOQUEAR; e pára. Não avances automaticamente. Não afirmes ter executado comandos, testes, revisões ou aprovações que não executaste ou não recebeste.
GO/
NO-GO
BLOQUEIA perante fórmula crítica incorrecta, regra sem fonte, benefício sem elegibilidade, sobreposição temporal, fuga de dados, divergência entre API/base/PDF/JSON, 
auto-aprovação
, 
migration
 irreversível, 
OpenAPI
 integral inválido, 
RLS
 não demonstrado, vulnerabilidade crítica, vulnerabilidade alta sem excepção válida, 
rollback
 ou recuperação não demonstrados. Uma falha crítica nunca admite excepção. Uma falha alta requer impacto, controlo compensatório, responsável, prazo e aprovação formal; ao expirar, torna-se bloqueio.
SAÍDA OBRIGATÓRIA
Entrega: fase; objectivo; estado proposto; matriz de conformidade actualizada; itens conformes preservados; itens parciais corrigidos; itens ausentes implementados; bloqueios; ficheiros criados e alterados; 
diff
 lógico por ficheiro; comandos efectivamente executados; testes, resultados e evidências; aprovações verificadas; riscos; pendências; 
rollback
; gate avaliado; próxima acção recomendada; e próxima fase potencialmente autorizável.
REGRA FINAL
Inspecciona → compara → preserva o conforme → implementa apenas lacunas → testa → apresenta evidências → propõe AVANÇAR, CORRIGIR ou BLOQUEAR → aguarda aprovação humana.
19.2 Versão 
Markdown
 optimizada para 
Codex
# Simulador Fiscal 
InvestMoz
 — Especificação Executável para 
Codex
## 1. Regra principal
- O repositório real é a fonte de verdade sobre o estado implementado.
- Inspeccionar antes de alterar.
- Classificar cada requisito: `CONFORME`, `PARCIAL`, `AUSENTE` ou `BLOQUEADO`.
- Preservar tudo o que já estiver conforme.
- Implementar apenas lacunas comprovadas.
- Executar uma fase por vez e aguardar revisão humana.
## 2. Escopo do MVP fiscal
### 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 e cambiais.
- Cenários e relatórios PDF/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 da 
release
 inicial
- Manifestações formais.
- Oportunidades de negócio.
- Conversões para projecto ou oportunidade.
- Integração CRM completa.
- Conta avançada do investidor.
- Assistente inteligente.
## 3. 
Stack
 alvo
- Backend: Laravel, adaptado à versão encontrada.
- Frontend: React/Next.js, adaptado à estrutura encontrada.
- Dados: PostgreSQL/
PostGIS
.
- Contrato: 
OpenAPI
 3.1 integral.
- Serviços: Redis, armazenamento de objectos compatível com S3, IAM/
SSO
 e serviço PDF, apenas quando disponíveis.
## 4. Restrições não negociáveis
- Não editar migrations executadas; criar novas migrations reversíveis.
- Não apagar dados nem usar produção.
- Não instalar novamente dependências existentes.
- Não actualizar versões fora do escopo.
- Não codificar taxas fiscais no código.
- Não publicar regras sem fonte e aprovação fiscal/jurídica.
- Não usar `
eval
` ou execução arbitrária.
- Não guardar 
tokens
 em claro, 
PII
 em 
logs
 ou 
URLs
 assinadas na base.
- Manter 
RLS
, 
RBAC
, 
ETag
/
If
-Match, 
idempotência
, 
snapshots
, soft delete e auditoria.
## 5. Fluxo obrigatório por fase
1. Inspeccionar.
2. Produzir matriz de conformidade.
3. Propor plano e ficheiros exactos.
4. Validar pré-condições.
5. Aplicar alterações mínimas.
6. Executar testes reais.
7. Corrigir apenas erros do escopo.
8. Produzir evidências e 
rollback
.
9. Propor `AVANÇAR`, `CORRIGIR` ou `BLOQUEAR`.
10. Aguardar aprovação humana.
## 6. Fases
### Fase 0 — Governação
Escopo, exclusões, 
RACI
, riscos, 
ADRs
, 
backlog
, rastreabilidade e gates.
### Fase 1 — Fundação executável
Reconciliar 
DDL
, migrations, modelos e 
OpenAPI
. Gates: `SQL-01`, `SQL-02`, `OAS-01`, `OAS-02`.
### Fase 2 — Repositório legislativo
Instrumentos, versões, disposições, relações, jurisdições, actividades, documentos, 
hashes
, pesquisa e importação 
idempotente
.
### Fase 3 — Regras e publicação
Parâmetros, rule sets, fontes, elegibilidade, obrigações, revisão de quatro olhos, testes e imutabilidade.
### Fase 4 — API e formulário React
JWT
/scopes, 
RBAC
, 
RLS
, 
token
 anónimo com 
hash
, 
ETag
, 
idempotência
, 
autosave
, validação cliente/servidor, 
dropdowns
 pesquisáveis e acessíveis, dependências, móvel e 
WCAG
. Sem 
defaults
 fiscais.
### Fase 5 — Motor fiscal
IRPC, IVA, ISPC, IRPS, INSS e retenções; regras vigentes; Decimal; arredondamento; transacção atómica; explicabilidade e casos dourados.
### Fase 6 — Aduanas, câmbios e calendário
Valor aduaneiro, direitos, ICE, IVA na importação, moedas, origem, cenários, obrigações, jobs, 
retries
 e 
dead-letter
.
### Fase 7 — Relatórios e homologação
PDF/JSON, checksum, reconciliação, segurança, desempenho, acessibilidade, resiliência, retenção, backup/restauro e E2E.
### Fase 8 — 
Release
Go
/
No-Go
, 
release
 imutável, backup, implantação controlada, 
smoke
 
tests
, 
rollback
, 
hypercare
 e actualização normativa contínua.
## 7. Formulário fiscal
- Configuração da simulação.
- Perfil do contribuinte.
- Actividade e localização.
- Investimento e financiamento.
- Vendas, custos e IVA.
- Trabalho, IRPS e INSS.
- Pagamentos e retenções.
- Importações.
- Obrigações cambiais.
- Revisão e cálculo.
- Modo anónimo não solicita identificação pessoal, NUIT, contactos ou documentos.
## 8. Gates mínimos
- 100% dos testes críticos aprovados.
- Pelo menos 95% dos testes aplicáveis aprovados.
- Zero vulnerabilidades críticas ou altas sem excepção válida.
- SQL e 
OpenAPI
 integrais executáveis.
- PDF, JSON, API e base reconciliados.
- 
Rollback
 e DR demonstrados.
- Aprovações fiscal, jurídica, segurança, operação e homologação registadas.
## 9. Saída de cada execução
```
text
Fase:
Estado proposto: AVANÇAR | CORRIGIR | BLOQUEAR
Itens conformes preservados:
Itens parciais corrigidos:
Itens ausentes implementados:
Bloqueios:
Ficheiros alterados:
Comandos executados:
Testes e resultados:
Evidências:
Riscos:
Rollback
:
Próxima acção autorizável:
```
Recomendo que o 
Simulador Fiscal do InvestMoz
, acessível em 
/Simulador
, seja desenvolvido como uma ferramenta de 
orientação fiscal, legal e financeira
, e não apenas como uma calculadora de impostos.
1. Objectivo
Permitir que investidores, empresários e cidadãos:
estimem os impostos aplicáveis a um investimento;
identifiquem incentivos fiscais disponíveis;
conheçam obrigações declarativas e prazos;
avaliem custos de importação, contratação e operação;
compreendam regras cambiais para entrada e repatriamento de capitais;
consultem a legislação aplicável;
obtenham um relatório preliminar do enquadramento fiscal do projecto.
O portal deve apresentar claramente que os resultados são 
simulações indicativas
 e não substituem pareceres da Autoridade Tributária, do Banco de Moçambique, da APIEX ou de consultores habilitados.
2. Fluxo do simulador
Etapa 1 — Perfil do utilizador
Pessoa singular ou colectiva;
Investidor nacional ou estrangeiro;
Empresa existente ou projecto a constituir;
Residência fiscal;
Forma jurídica;
Pequeno contribuinte, PME ou grande empresa.
Etapa 2 — Caracterização do investimento
Sector de actividade;
Província, distrito e localidade;
Montante do investimento;
Capital próprio e financiamento;
Origem nacional ou estrangeira dos fundos;
Número previsto de trabalhadores;
Trabalhadores nacionais e expatriados;
Volume de negócios estimado;
Custos operacionais;
Importações previstas;
Exportações previstas;
Localização em ZEE, ZFI ou fora de regime especial;
Duração e calendário do projecto.
Etapa 3 — Apuramento fiscal
O motor deve calcular, conforme o perfil e a data de referência, apenas os tributos incluídos no MVP fiscal. Imposto do selo, impostos autárquicos, mais-valias, preços de transferência, convenções completas de dupla tributação, benefícios complexos de ZEE/ZFI e regimes sectoriais devem ser identificados como matérias potencialmente aplicáveis e encaminhados para validação especializada, sem cálculo automático nesta 
release
.
IRPC;
IRPS;
IVA;
ISPC;
ICE;
retenções na fonte;
direitos aduaneiros;
imposto do selo;
contribuições para a segurança social;
impostos autárquicos;
tributação de dividendos, juros, royalties e serviços;
mais-valias;
preços de transferência;
dupla tributação;
impostos e regimes específicos do sector;
benefícios fiscais aplicáveis ao projecto.
Etapa 4 — Obrigações cambiais
Registo do investimento estrangeiro;
Entrada de capitais;
Contas em moeda estrangeira;
Pagamento de importações;
Empréstimos externos;
Repatriamento de lucros e dividendos;
Pagamento de juros, royalties e serviços ao exterior;
Desinvestimento;
Documentos de suporte e intervenção de bancos autorizados.
A matéria cambial deve considerar a 
Lei n.º 28/2022, de 29 de 
Dezembro
, o respectivo regulamento aprovado pelo 
Decreto n.º 56/2023, de 3 de 
Outubro
, e as normas operacionais do 
Aviso n.º 3/GBM/2024
.
 Cada referência deve ser confirmada na fonte oficial, registada no repositório legislativo e submetida à validação jurídica antes da publicação.
3. Resultado da simulação
O relatório gerado deve apresentar:
Perfil do investimento;
Pressupostos utilizados;
Impostos potencialmente aplicáveis;
Base tributável, taxa e valor estimado;
Benefícios fiscais identificados;
Custos aduaneiros estimados;
Obrigações cambiais;
Obrigações declarativas;
Calendário fiscal;
Cenários optimista, base e conservador;
Riscos e matérias que exigem validação;
Legislação utilizada;
Data de actualização das regras;
Declaração de limitação de responsabilidade.
O utilizador deverá poder exportar o relatório em PDF e guardar a simulação na sua conta do InvestMoz.
4. Repositório de legislação
O repositório deve ser organizado por domínio.
A. Sistema tributário geral
Lei de Bases do Sistema Tributário;
Lei Geral Tributária;
legislação do contencioso tributário;
regime das infracções tributárias;
execução fiscal;
Número Único de Identificação Tributária;
facturação, documentos fiscalmente relevantes e arquivo;
declarações electrónicas e obrigações acessórias.
B. Impostos sobre o rendimento
Código do IRPC e regulamento;
Código do IRPS e regulamento;
retenções na fonte;
tributação de não residentes;
preços de transferência;
convenções para evitar a dupla tributação;
regras sobre dividendos, juros, royalties e serviços.
A
 Autoridade Tributária disponibiliza conteúdos processuais sobre IRPC e formulários fiscais, mas algumas páginas podem conservar informação histórica
. Por
 isso, 
todos 
os parâmetros do simulador devem ser confirmados 
no
 Boletim da República
, registados com a versão
 e 
a data de vigência e submetidos à validação fiscal e jurídica antes da publicação.
C. Tributação do consumo
Código do IVA e regulamento;
Código do ICE;
ISPC;
isenções;
regimes especiais;
reembolsos;
importação e exportação.
As
 alterações fiscais recentes
 relativas ao
 IRPC, IVA, IRPS e ISPC 
devem ser confirmadas nos diplomas publicados
 no 
Boletim da República antes
 de 
serem parametrizadas. A
 base normativa deve 
manter
 controlo de vigência
,
 versões
, diplomas alteradores, data da última validação e responsável pela aprovação.
D. Aduanas e comércio externo
Lei n.º 17/2022 — Pauta Aduaneira;
Instruções Preliminares da Pauta;
direitos aduaneiros;
ICE na importação;
IVA na importação;
regimes suspensivos;
importação temporária;
trânsito;
regras de origem;
acordos comerciais aplicáveis;
benefícios para projectos de investimento.
A Lei n.º 17/2022 aprovou a Pauta Aduaneira e revogou a Lei n.º 11/2016.
 A aplicação desta referência, incluindo alterações posteriores, instruções preliminares, classificações e taxas, deve ser confirmada na fonte oficial antes da parametrização.
E. Investimento privado
Lei de Investimentos;
regulamento da Lei de Investimentos;
Código dos Benefícios Fiscais;
procedimentos de registo e autorização;
garantias ao investidor;
investimento directo estrangeiro;
repatriamento de capitais;
Zonas Económicas Especiais;
Zonas Francas Industriais;
projectos de grande dimensão;
parcerias público-privadas e concessões.
O simulador deve 
apresentar
 separadamente os benefícios 
potenciais 
de ZEE e ZFI, incluindo isenções 
ou
 reduções de IRPC e encargos aduaneiros
 quando previstas nas regras vigentes. Nenhum benefício pode ser aplicado ao cálculo sem
 elegibilidade
,
 certificação 
válida, período aplicável, fundamento legal e aprovação das evidências.
F. Legislação cambial e financeira
Lei Cambial;
Regulamento da Lei Cambial;
avisos do Banco de Moçambique;
regras sobre investimento estrangeiro;
operações de capitais;
dívida externa;
contas bancárias em moeda estrangeira;
exportação e importação de capitais;
repatriamento de receitas de exportação;
prevenção do branqueamento de capitais.
G. Trabalho, imigração e segurança social
Lei do Trabalho;
contratação de trabalhadores estrangeiros;
vistos e autorizações de residência;
contribuições para o INSS;
remunerações e benefícios tributáveis;
retenções sobre salários;
quotas de trabalhadores estrangeiros;
segurança e saúde no trabalho.
H. Legislação sectorial
O motor deve activar regras próprias para:
mineração;
petróleo e gás;
energia;
agricultura;
pescas;
turismo;
construção e imobiliário;
telecomunicações;
banca, seguros e microfinanças;
transportes e logística;
indústria;
comércio;
ambiente;
concessões e PPP;
economia digital.
5. Estrutura técnica recomendada
A legislação e os parâmetros não devem ficar directamente gravados no código. Recomendo uma base configurável com:
instrumento legal;
número, data e entidade emissora;
tipo de diploma;
artigos relevantes;
imposto ou obrigação abrangida;
sector;
localização;
perfil do contribuinte;
taxa;
fórmula;
limite ou escalão;
benefício fiscal;
data de entrada em vigor;
data de revogação;
diploma alterador;
fonte oficial;
estado: vigente, alterado ou revogado;
data da última validação;
responsável pela validação.
6. Governação e segurança jurídica
Antes da publicação, deverão existir:
validação jurídica e fiscal;
validação pela Autoridade Tributária, quando possível;
validação cambial pelo Banco de Moçambique;
validação dos incentivos pela APIEX;
histórico de versões;
regra de “quatro olhos” para alterações;
testes automatizados das fórmulas;
data de vigência de cada parâmetro;
auditoria de mudanças;
revisão periódica do Boletim da República.
A área de legislação do Ministério das Finanças deve integrar o conjunto de fontes oficiais monitorizadas. Cada diploma ou alteração recolhido deve ser confirmado no Boletim da República, registado com URL, 
hash
, data de consulta, vigência e responsável pela validação e submetido ao 
workflow
 de revisão antes da publicação.
7. Evolução funcional proposta
Fase Zero:
 levantamento e validação integral da legislação e das fórmulas.
MVP fiscal:
 inclui IRPC, IRPS sobre remunerações, IVA, ISPC, retenções na fonte, INSS, valor aduaneiro, direitos aduaneiros, ICE e IVA na importação, obrigações fiscais e cambiais, cenários e relatórios. Imposto do selo, impostos autárquicos, mais-valias, preços de transferência, convenções completas de dupla tributação, benefícios complexos de ZEE/ZFI e regimes sectoriais ficam fora do cálculo do MVP e são apresentados apenas como matérias a validar, salvo requisito legal indispensável formalmente aprovado.
Fase 2:
 benefícios fiscais, ZEE, ZFI, convenções de dupla tributação e relatórios comparativos.
Fase 3:
 mineração, petróleo, energia, agricultura, turismo e outros regimes sectoriais.
Fase 4:
 integração com CRM, oportunidades de investimento, mapas geográficos, conta do investidor e assistente inteligente.
A expressão “toda a legislação” deve ser tratada como um 
repositório jurídico continuamente actualizado
, e não como uma lista estática, porque diplomas, taxas, regulamentos e procedimentos podem ser alterados ao longo do tempo.
Matriz de decisão do escopo fiscal:
 para cada tributo ou regime, registar estado da 
release
 — calcular, identificar e orientar, ou fora do escopo —, perguntas associadas, fórmula, fonte, testes, responsável fiscal e gate. Qualquer alteração do estado exige 
actualização coordenada do questionário, motor, 
OpenAPI
, modelo de dados, matriz de testes, relatório e critérios 
Go
/
No-Go
.
8. Arquitectura técnica do Simulador Fiscal
Princípios:
 arquitectura modular, API-
first
, configuração sem taxas gravadas no código, vigência temporal das regras, separação entre cálculo e conteúdo jurídico, explicabilidade de cada resultado, auditoria integral, segurança por desenho e integração sem duplicação com os cadastros do 
InvestMoz
.
Camada
Componentes
Responsabilidade
Experiência
React/Next.js em /Simulador; interface responsiva e acessível; assistente por etapas; painel administrativo
Recolher dados, validar entradas, apresentar explicações, comparação de cenários e relatório.
API
Laravel; 
REST
/JSON; 
OpenAPI
; autenticação do 
InvestMoz
; limitação de pedidos
Orquestrar simulações, legislação, parâmetros, relatórios e integrações.
Domínio
Motor de elegibilidade; motor de regras; motor de cálculo; motor de obrigações; motor de explicação
Determinar impostos aplicáveis, calcular valores e ligar cada resultado à regra e ao fundamento legal vigentes.
Dados
PostgreSQL; 
PostGIS
 para jurisdições; armazenamento de documentos compatível com S3; Redis
Guardar legislação 
versionada
, regras, taxas, simulações, resultados, ficheiros, cache e filas.
Integração
InvestMoz
 IAM/
SSO
, cadastro do investidor, APIEX, fontes oficiais, notificações e serviço PDF
Reutilizar dados mestre, importar metadados e entregar relatórios sem criar cadastros paralelos.
Operação
Contentores; CI/CD; observabilidade; cofre de segredos; cópias de segurança
Garantir implantação reversível, monitorização, recuperação e segregação entre desenvolvimento, testes e produção.
Fluxo de execução:
 a interface envia um conjunto de respostas 
versionado
; o serviço de elegibilidade selecciona regimes; o motor carrega apenas regras aprovadas cuja vigência inclui a data de referência; cada fórmula produz base, taxa, montante, arredondamento, pressupostos e referências legais; o serviço de obrigações acrescenta prazos e alertas; o resultado é persistido como instantâneo imutável e entregue em ecrã e relatório.
Serviços 
lógicos
:
 Identity, Questionnaire, Simulation, Rules, Legislation, Customs, Obligations, Reporting, Administration e Audit.
Endpoints 
principais
:
 GET /api/simulator/schema; POST /api/simulations; POST /api/
simulations/{id}/
calculate; GET /api/
simulations/{id};
 GET /api/
simulations/{id}/
report; GET /api/legislation; GET /api/rules/effective; POST /api/admin/
rules/{id}/
submit e /approve.
Controlo editorial:
 rascunho → revisão técnica → revisão jurídica → aprovado → publicado → suspenso/arquivado; autor e aprovador distintos.
Segurança:
 
RBAC
, encriptação em trânsito e repouso, minimização de dados pessoais, registo de acessos administrativos, protecção contra adulteração de fórmulas e retenção configurável.
Qualidade:
 testes unitários por regra, casos dourados validados por fiscalista, testes de vigência, regressão e reconciliação do relatório com o resultado JSON.
Disponibilidade:
 cálculo síncrono para cenários simples; fila assíncrona para relatórios; 
idempotência
; cache identificada pela versão do conjunto de regras.
9. Modelo de dados do repositório legislativo
Entidade
Campos essenciais
Relações e regras
legal_domains
id, code, name, 
parent_id
Taxação, investimento, câmbios, aduanas, trabalho e sectores; hierarquia sem duplicação.
legal_instruments
id, type, number, year, title, 
issuer_id
, 
publication_date
, 
gazette_ref
, status
Registo canónico do diploma; unicidade por tipo, número e ano.
legal_versions
id, 
instrument_id
, 
version_no
, 
effective_from
, 
effective_to
, 
publication_url
, 
file_hash
, 
review_status
Múltiplas versões; intervalos aprovados do mesmo diploma não se sobrepõem.
legal_provisions
id, 
version_id
, article, paragraph, item, heading, text, 
search_vector
Unidade citável do diploma; pesquisa textual integral.
legal_relations
source_instrument_id
, 
target_instrument_id
, 
relation_type
, 
effective_date
, notes
Altera, regulamenta, revoga, 
republica
 ou complementa.
tax_types
id, code, name, 
authority_id
, periodicity
IRPC, IRPS, IVA, ISPC, INSS, direitos, ICE e retenções.
tax_parameters
id, 
tax_type_id
, 
parameter_key
, 
value_decimal
, 
value_json
, unit, currency, 
effective_from
, 
effective_to
, 
source_provision_id
, status
Taxas, escalões, limites e arredondamento; nenhum valor fiscal fica no código.
calculation_rules
id, code, name, expression, 
condition_json
, priority, 
output_code
, 
effective_from
, 
effective_to
, status
Expressão validada e condicionais declarativas; versão imutável após publicação.
rule_sources
rule_id
, 
provision_id
, justification
Relação muitos-para-muitos entre fórmula e disposições legais.
regimes
id, code, name, 
regime_type
, 
authority_id
Geral, simplificado, ZEE, ZFI e outros regimes.
eligibility_rules
id, 
regime_id
, 
condition_json
, 
evidence_json
, 
effective_from
, 
effective_to
Determina elegibilidade e documentos necessários.
obligations
id, code, name, 
trigger_json
, frequency, 
due_rule
, 
authority_id
, 
source_provision_id
Declaração, pagamento, registo, autorização ou retenção.
jurisdictions
id, 
parent_id
, type, code, name, geometry
Província, distrito, autarquia, ZEE e ZFI; suporte 
PostGIS
.
economic_activities
id, code, name, 
parent_id
Classificação sectorial usada nas regras e no questionário.
simulations
id, 
user_id
 nullable, 
reference_date
, status, currency, 
rule_set_version
, 
input_json
, 
created_at
Permite utilização anónima e autenticada; dados de entrada preservados.
simulation_results
id, 
simulation_id
, 
output_code
, 
taxable_base
, rate, amount, 
formula_snapshot
, 
assumptions_json
Resultado reproduzível, incluindo fórmula e parâmetros utilizados.
result_sources
result_id
, 
provision_id
, 
legal_version_id
Rastreabilidade do valor até ao artigo e versão legal.
change_audit
id, 
entity_type
, 
entity_id
, action, 
before_json
, 
after_json
, 
actor_id
, timestamp
Auditoria inviolável das alterações administrativas.
Integridade temporal:
 consultas usam a data de referência da simulação; exclusões por intervalo impedem sobreposição de versões, parâmetros e regras aprovadas.
Proveniência:
 toda regra publicada deve ter pelo menos uma disposição legal, ficheiro com 
hash
, fonte oficial e validação registada.
Pesquisa:
 índices por número/ano, estado, vigência, domínio e vector textual; índice espacial para jurisdições.
Publicação:
 um conjunto de regras é promovido atomicamente e recebe versão; simulações antigas continuam reproduzíveis.
Documentos:
 o ficheiro original fica no armazenamento de objectos; a base mantém metadados, 
hash
, localização e texto extraído.
10. Perguntas e fórmulas do MVP
O questionário deve ser dinâmico: perguntas dependentes só aparecem quando a resposta anterior as torna relevantes. Todos os valores monetários são introduzidos em 
MZN
 ou convertidos por uma taxa de câmbio e data claramente registadas.
Grupo
Perguntas obrigatórias ou condicionais
Uso
Contexto
Data de referência? Simulação anual ou mensal? Moeda? Pretende cenário único ou três cenários?
Seleccionar vigência, período e apresentação.
Contribuinte
Pessoa singular, colectiva ou trabalhador por conta própria? Residente fiscal? Actividade existente ou nova? Forma jurídica? NUIT opcional?
Seleccionar IRPC, IRPS, ISPC e obrigações.
Actividade e localização
Sector e código de actividade? Província, distrito, autarquia? Está certificado em ZEE/ZFI? Qual entidade e validade do certificado?
Regras sectoriais, locais e benefícios; benefício não é presumido sem prova.
Investimento
Montante total? Capital próprio? Financiamento nacional e externo? Data de início? Vida útil? Activos por classe?
Perfil financeiro, depreciação futura e obrigações cambiais.
Operação
Vendas sem IVA? Vendas isentas, taxa zero e exportações? Outros rendimentos? Custos dedutíveis? Gastos não dedutíveis? Prejuízos reportáveis?
IVA e lucro tributável.
Trabalho
Número de trabalhadores? Remuneração bruta e adicionais por trabalhador ou faixa? Trabalhadores estrangeiros? Trabalhador por conta própria?
IRPS, INSS e alertas laborais.
Pagamentos
Dividendos, juros, royalties, rendas ou serviços? Valor? Beneficiário residente? País? Existe convenção aplicável e documentação?
Retenções e alerta de dupla tributação.
Importações
Descrição, código pautal, origem, quantidade, valor da factura, frete, seguro, moeda, taxa de câmbio, ICE, isenção e documentação?
Valor aduaneiro, direitos, ICE e IVA de importação.
Regime simplificado
Volume de negócios previsto? Reúne requisitos do ISPC? Pretende comparar regime simplificado e geral?
Elegibilidade e comparação.
Câmbios
Há capital estrangeiro, empréstimo externo, pagamento ao exterior, exportação, dividendos ou desinvestimento?
Checklist cambial, sem converter obrigação em imposto.
Cálculo
Fórmula funcional
Observações do MVP
Lucro tributável IRPC
LT = rendimentos tributáveis − gastos fiscalmente dedutíveis + correcções positivas − correcções negativas − prejuízos dedutíveis
IRPC bruto = 
max
(
0, LT) × 
taxa_IRPC
; benefícios e pagamentos por conta em linhas separadas.
IRPC estimado
IRPC a pagar = 
max
(
0, IRPC bruto − crédito por benefício − retenções/créditos admissíveis)
Taxa, limites e elegibilidade são parâmetros vigentes; não presumir benefício.
IVA de operações
IVA liquidado = 
soma(
base tributável por operação × taxa aplicável)
Separar operações tributadas, isentas, taxa zero e fora do âmbito.
IVA a pagar
IVA a pagar = 
max
(
0, IVA liquidado − IVA dedutível − crédito anterior)
Se negativo, apresentar crédito estimado; dedutibilidade deve ser perguntada ou justificada.
ISPC
ISPC = base definida no regime × 
taxa_ISPC
 ou valor por escalão
Executar somente após regra de elegibilidade; comparar com regime 
geral sem aconselhamento conclusivo.
IRPS de trabalho
Rendimento colectável = remuneração tributável − deduções admitidas; IRPS = parcela fixa do escalão + (rendimento colectável − limite inferior) × taxa marginal
Tabela, periodicidade, deduções e situação familiar são dados versionados.
INSS — empregador
Contribuição da entidade = remuneração contributiva × 
taxa_empregador
Como configuração inicial sujeita a validação: 4% para entidade empregadora.
INSS — trabalhador
Desconto do trabalhador = remuneração contributiva × 
taxa_trabalhador
Como configuração inicial sujeita a validação: 3%; total 7%. Para TCP, taxa configurável própria.
Retenção na fonte
Retenção = pagamento bruto sujeito × taxa por natureza, residência e convenção
Uma regra por dividendos, juros, royalties, rendas e serviços; exigir documentação para taxa convencional.
Valor aduaneiro
VA = valor da factura convertido + frete + seguro + ajustamentos incluíveis
Aplicar método e câmbio aduaneiro vigentes.
Direitos aduaneiros
DA = VA × 
taxa_pautal
Taxa depende do código pautal, origem e preferência; nunca usar taxa genérica.
ICE na importação
ICE = 
base_ICE
 configurada × 
taxa_ICE
 específica ou ad valorem
Produto, unidade, taxa e base provêm da Pauta/ICE vigente.
IVA na importação
IVA_importação
 = (VA + DA + ICE + outras imposições incluíveis) × 
taxa_IVA
Componentes exactos da base são parametrizados e citados.
Custo fiscal total
CFT
 = impostos não recuperáveis + direitos + ICE + retenções suportadas + contribuição patronal
Mostrar separadamente IVA recuperável, desconto do trabalhador e fluxos meramente retidos.
Taxa efectiva
Taxa efectiva = 
CFT
 ÷ base económica seleccionada × 100
O relatório identifica se a base é lucro, receita ou investimento.
10.1 Validações e critérios de aceitação
Montantes não podem ser negativos; percentagens ficam entre 0 e 100; somas de financiamento devem reconciliar com o investimento ou ser sinalizadas.
O código pautal é obrigatório para cálculo aduaneiro; sem ele, apresentar apenas uma estimativa incompleta e pedir classificação.
Benefícios exigem regime, certificado, período e critérios satisfeitos; caso contrário, são apresentados como oportunidade a validar.
Cada linha calculada exibe fórmula, valores substituídos, versão da regra, data de vigência e fundamento legal.
Casos de teste cobrem limites de escalões, datas de mudança de taxa, zero, valores elevados, isenções, arredondamento e combinações incompatíveis.
O total do relatório deve reconciliar com os resultados da API e com o instantâneo guardado.
Uma regra vencida, sem fonte ou não aprovada não pode ser usada em produção.
Nota de implementação:
 antes do 
Go
-Live, as taxas do IRPC, IRPS, IVA, ISPC, retenções, pauta, ICE e benefícios devem ser carregadas a partir dos diplomas vigentes e aprovadas por revisão fiscal e jurídica. A fonte oficial consultada confirma, para o INSS, a repartição de 4% para a entidade empregadora e 3% para o trabalhador; a Lei n.º 17/2022 aprovou a Pauta Aduaneira; e a Lei Cambial n.º 28/2022 é regulamentada pelo Decreto n.º 56/2023. Alterações posteriores devem entrar apenas através de nova versão efectiva do conjunto de regras.
11. Esquema SQL corrigido e consistente
Versão de referência para PostgreSQL 
17
/
PostGIS
. Corrige os bloqueadores identificados: vigência dos rule sets, escopo temporal dos parâmetros, 
ETag
, eliminação lógica, 
token
 anónimo, cenários, jobs, 
idempotência
 composta, integridade das fontes e evidências de revisão/teste.
CREATE EXTENSION IF NOT EXISTS 
pgcrypto
;
CREATE EXTENSION IF NOT EXISTS 
postgis
;
CREATE EXTENSION IF NOT EXISTS 
btree_gist
;
CREATE TYPE 
publication_status
 AS ENUM ('draft','technical_review','legal_review','approved','published','suspended','archived');
CREATE TYPE 
simulation_status
 AS ENUM ('draft','validated','calculating','completed','failed','expired');
CREATE TYPE 
job_status
 AS ENUM ('queued','running','completed','failed','
dead_letter
');
CREATE TYPE 
review_stage
 AS ENUM ('
technical','legal','publication
');
CREATE TYPE 
review_decision
 AS ENUM ('
approve','return
');
CREATE OR REPLACE FUNCTION 
set_updated_at
() RETURNS trigger LANGUAGE 
plpgsql
 AS $$ BEGIN 
NEW.updated_at
=now(); IF 
TG_TABLE_NAME
='simulations' THEN 
NEW.lock_version
=OLD.lock_version+1; END IF; RETURN NEW; END $$;
CREATE TABLE authorities(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),code varchar(50) UNIQUE NOT 
NULL,name
 text NOT 
NULL,created_at
 
timestamptz
 NOT NULL DEFAULT now(),
updated_at
 
timestamptz
 NOT NULL DEFAULT now());
CREATE TABLE 
legal_instruments
(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),
instrument_type
 varchar(60) NOT 
NULL,number
 varchar(30) NOT 
NULL,year
 
smallint
 NOT 
NULL,title
 text NOT 
NULL,issuer_id
 
uuid
 REFERENCES authorities(id),
publication_date
 
date,gazette_reference
 
text,created_at
 
timestamptz
 NOT NULL DEFAULT now(),
updated_at
 
timestamptz
 NOT NULL DEFAULT now(),UNIQUE(
instrument_type,number,year
));
CREATE TABLE 
legal_versions
(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),
instrument_id
 
uuid
 NOT NULL REFERENCES 
legal_instruments
(id) ON DELETE 
CASCADE,version_no
 integer NOT NULL CHECK(
version_no
>0),
effective_period
 
daterange
 NOT 
NULL,object_key
 
text,file_hash
 char(64) NOT 
NULL,review_status
 
publication_status
 NOT NULL DEFAULT 'draft',
created_at
 
timestamptz
 NOT NULL DEFAULT now(),
updated_at
 
timestamptz
 NOT NULL DEFAULT now(),UNIQUE(
instrument_id,version_no
));
ALTER TABLE 
legal_versions
 ADD CONSTRAINT 
legal_versions_no_overlap
 EXCLUDE USING gist(
instrument_id
 WITH =,
effective_period
 WITH &&) WHERE(
review_status
 IN ('
approved','published
'));
CREATE TABLE 
legal_provisions
(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),
legal_version_id
 
uuid
 NOT NULL REFERENCES 
legal_versions
(id) ON DELETE 
CASCADE,article
 varchar(40),
paragraph_no
 varchar(40),
item_no
 varchar(40),heading 
text,provision_text
 text NOT 
NULL,sequence_no
 integer NOT 
NULL,search_vector
 
tsvector
 GENERATED ALWAYS AS(
to_tsvector
('
portuguese
',coalesce(heading,'')||' '||
provision_text
)) 
STORED,UNIQUE
(
legal_version_id,sequence_no
));
CREATE INDEX 
legal_provisions_search_gin
 ON 
legal_provisions
 USING gin(
search_vector
);
CREATE TABLE 
tax_types
(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),code varchar(30) UNIQUE NOT 
NULL,name
 text NOT NULL);
CREATE TABLE regimes(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),code varchar(50) UNIQUE NOT 
NULL,name
 text NOT NULL);
CREATE TABLE 
tax_parameters
(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),
tax_type_id
 
uuid
 NOT NULL REFERENCES 
tax_types
(id),
regime_id
 
uuid
 REFERENCES regimes(id),
jurisdiction_id
 
uuid,activity_id
 
uuid,currency
 char(3),
parameter_key
 varchar(100) NOT 
NULL,scope_key
 text GENERATED ALWAYS AS(tax_type_id::text||':'||coalesce(regime_id::text,'*')||':'||coalesce(jurisdiction_id::text,'*')||':'||coalesce(activity_id::text,'*')||':'||coalesce(currency,'*')) 
STORED,value_decimal
 numeric(24,8),
value_text
 
text,value_json
 
jsonb,effective_period
 
daterange
 NOT 
NULL,source_provision_id
 
uuid
 NOT NULL REFERENCES 
legal_provisions
(id),status 
publication_status
 NOT NULL DEFAULT 'draft',
submitted_by
 
uuid,approved_by
 
uuid,created_at
 
timestamptz
 NOT NULL DEFAULT now(),
updated_at
 
timestamptz
 NOT NULL DEFAULT now(),CHECK(num_nonnulls(value_decimal,value_text,value_json)=1),CHECK(approved_by IS NULL OR 
approved_by
 IS DISTINCT FROM 
submitted_by
));
ALTER TABLE 
tax_parameters
 ADD CONSTRAINT 
tax_parameter_scope_no_overlap
 EXCLUDE USING gist(
scope_key
 WITH =,
parameter_key
 WITH =,
effective_period
 WITH &&) WHERE(status IN ('
approved','published
'));
CREATE TABLE 
rule_sets
(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),version varchar(40) UNIQUE NOT 
NULL,name
 text NOT 
NULL,scope_key
 text NOT NULL DEFAULT 'GLOBAL',
effective_period
 
daterange
 NOT 
NULL,status
 
publication_status
 NOT NULL DEFAULT '
draft',checksum
 char(64),
submitted_by
 
uuid,approved_by
 
uuid,published_at
 
timestamptz,created_at
 
timestamptz
 NOT NULL DEFAULT now(),CHECK(
approved_by
 IS NULL OR 
approved_by
 IS DISTINCT FROM 
submitted_by
));
ALTER TABLE 
rule_sets
 ADD CONSTRAINT 
rule_sets_no_overlap
 EXCLUDE USING gist(
scope_key
 WITH =,
effective_period
 WITH &&) WHERE(status='published');
CREATE TABLE 
calculation_rules
(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),
rule_set_id
 
uuid
 NOT NULL REFERENCES 
rule_sets
(id),
tax_type_id
 
uuid
 REFERENCES 
tax_types
(id),code varchar(100) NOT 
NULL,name
 text NOT 
NULL,expression
 text NOT 
NULL,condition_json
 
jsonb
 NOT NULL DEFAULT '{}'::
jsonb,input_schema
 
jsonb
 NOT NULL DEFAULT '{}'::
jsonb,output_code
 varchar(100) NOT 
NULL,priority
 integer NOT NULL DEFAULT 100,rounding_scale 
smallint
 NOT NULL DEFAULT 2,rounding_mode varchar(20) NOT NULL DEFAULT '
HALF_UP',status
 
publication_status
 NOT NULL DEFAULT '
draft',checksum
 char(64),UNIQUE(
rule_set_id,code
));
CREATE TABLE 
rule_sources
(
rule_id
 
uuid
 NOT NULL REFERENCES 
calculation_rules
(id) ON DELETE 
CASCADE,provision_id
 
uuid
 NOT NULL REFERENCES 
legal_provisions
(id),justification text NOT 
NULL,PRIMARY
 KEY(
rule_id,provision_id
));
CREATE TABLE 
review_decisions
(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),
resource_type
 varchar(40) NOT 
NULL,resource_id
 
uuid
 NOT 
NULL,stage
 
review_stage
 NOT 
NULL,decision
 
review_decision
 NOT 
NULL,reviewer_id
 
uuid
 NOT 
NULL,comment
 
text,created_at
 
timestamptz
 NOT NULL DEFAULT now(),UNIQUE(
resource_type,resource_id,stage,reviewer_id
));
CREATE TABLE 
rule_set_test_runs
(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),
rule_set_id
 
uuid
 NOT NULL REFERENCES 
rule_sets
(id),status varchar(20) NOT NULL CHECK(status IN('
passed','failed
')),
critical_total
 integer NOT 
NULL,critical_passed
 integer NOT 
NULL,total
 integer NOT 
NULL,passed
 integer NOT 
NULL,evidence_uri
 
text,checksum
 char(64) NOT 
NULL,executed_at
 
timestamptz
 NOT NULL DEFAULT now(),CHECK(critical_passed<=critical_total),CHECK(passed<=total));
CREATE TABLE 
questionnaire_versions
(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),version varchar(40) UNIQUE NOT 
NULL,schema_json
 
jsonb
 NOT 
NULL,ui_schema_json
 
jsonb
 NOT NULL DEFAULT '{}'::
jsonb,status
 
publication_status
 NOT NULL DEFAULT 'draft',
effective_period
 
daterange
 NOT NULL);
CREATE TABLE simulations(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),
owner_user_id
 
uuid,anonymous_token_hash
 char(64),
questionnaire_version_id
 
uuid
 NOT NULL REFERENCES 
questionnaire_versions
(id),
rule_set_id
 
uuid
 REFERENCES 
rule_sets
(id),
parent_simulation_id
 
uuid
 REFERENCES simulations(id),
scenario_name
 varchar(20) CHECK(
scenario_name
 IN('
optimistic','base','conservative
')),
scenario_changes
 
jsonb,reference_date
 date NOT 
NULL,period_type
 varchar(20) NOT NULL CHECK(
period_type
 IN('
monthly','annual','project
')),currency char(3) NOT NULL DEFAULT '
MZN',status
 
simulation_status
 NOT NULL DEFAULT 'draft',
input_json
 
jsonb
 NOT NULL DEFAULT '{}'::
jsonb,input_hash
 char(64),
lock_version
 
bigint
 NOT NULL DEFAULT 1,error_json 
jsonb,expires_at
 
timestamptz,deleted_at
 
timestamptz,deleted_by
 
uuid,deletion_reason
 
text,created_at
 
timestamptz
 NOT NULL DEFAULT now(),
updated_at
 
timestamptz
 NOT NULL DEFAULT now(),
completed_at
 
timestamptz,CHECK
(
owner_user_id
 IS NOT NULL OR 
anonymous_token_hash
 IS NOT NULL),CHECK(
parent_simulation_id
 IS NOT NULL OR 
scenario_name
 IS NULL));
CREATE UNIQUE INDEX 
simulation_scenario_unique
 ON simulations(
parent_simulation_id,scenario_name
) WHERE 
deleted_at
 IS NULL AND 
parent_simulation_id
 IS NOT NULL;
CREATE TABLE 
simulation_results
(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),
simulation_id
 
uuid
 NOT NULL REFERENCES simulations(id) ON DELETE 
CASCADE,rule_id
 
uuid
 NOT NULL REFERENCES 
calculation_rules
(id),
output_code
 varchar(100) NOT 
NULL,taxable_base
 numeric(24,2),rate numeric(16,8),amount numeric(24,2) NOT 
NULL,currency
 char(3) NOT 
NULL,formula_snapshot
 text NOT 
NULL,parameter_snapshot
 
jsonb
 NOT 
NULL,assumptions_json
 
jsonb
 NOT NULL DEFAULT '[]'::
jsonb,warnings_json
 
jsonb
 NOT NULL DEFAULT '[]'::
jsonb,sequence_no
 integer NOT 
NULL,UNIQUE
(
simulation_id,output_code,sequence_no
));
CREATE TABLE 
result_sources
(
result_id
 
uuid
 NOT NULL REFERENCES 
simulation_results
(id) ON DELETE 
CASCADE,provision_id
 
uuid
 NOT NULL REFERENCES 
legal_provisions
(id),PRIMARY KEY(
result_id,provision_id
));
CREATE TABLE reports(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),
simulation_id
 
uuid
 NOT NULL REFERENCES simulations(id) ON DELETE 
CASCADE,format
 varchar(10) NOT NULL CHECK(format IN('pdf','
json
')),status 
job_status
 NOT NULL DEFAULT 'queued',
object_key
 
text,checksum
 char(64),
generated_at
 
timestamptz,expires_at
 
timestamptz,error_json
 
jsonb,created_at
 
timestamptz
 NOT NULL DEFAULT now());
CREATE TABLE jobs(id 
uuid
 PRIMARY KEY DEFAULT 
gen_random_uuid
(),
owner_user_id
 
uuid,simulation_id
 
uuid
 REFERENCES simulations(id) ON DELETE 
CASCADE,job_type
 varchar(30) NOT NULL CHECK(
job_type
 IN('
calculation','report','import','purge
')),status 
job_status
 NOT NULL DEFAULT '
queued',progress
 
smallint
 NOT NULL DEFAULT 0 CHECK(progress BETWEEN 0 AND 100),attempts integer NOT NULL DEFAULT 0,max_attempts integer NOT NULL DEFAULT 3,payload_hash char(64) NOT 
NULL,resource_type
 varchar(30),
resource_id
 
uuid,error_json
 
jsonb,available_at
 
timestamptz
 NOT NULL DEFAULT now(),
started_at
 
timestamptz,completed_at
 
timestamptz,created_at
 
timestamptz
 NOT NULL DEFAULT now());
CREATE TABLE 
idempotency_keys
(
owner_key
 varchar(100) NOT 
NULL,key
 varchar(100) NOT 
NULL,http_method
 varchar(10) NOT 
NULL,request_path
 text NOT 
NULL,request_hash
 char(64) NOT 
NULL,response_code
 
integer,response_body
 
jsonb,expires_at
 
timestamptz
 NOT 
NULL,created_at
 
timestamptz
 NOT NULL DEFAULT now(),PRIMARY KEY(
owner_key,key
));
CREATE INDEX 
idempotency_lookup
 ON 
idempotency_keys
(
owner_key,http_method,request_path,expires_at
);
CREATE TABLE 
change_audit
(id 
bigserial
 PRIMARY 
KEY,entity_type
 varchar(80) NOT 
NULL,entity_id
 
uuid,action
 varchar(40) NOT 
NULL,before_json
 
jsonb,after_json
 
jsonb,actor_id
 
uuid,correlation_id
 
uuid,occurred_at
 
timestamptz
 NOT NULL DEFAULT now());
CREATE TRIGGER 
simulations_updated
 BEFORE UPDATE ON simulations FOR EACH ROW EXECUTE FUNCTION 
set_updated_at
();
11.1 Regras de integridade e geração de código
O 
ETag
 é calculado sobre id, 
lock_version
 e 
updated_at
; 
PATCH
 e 
calculate
 incrementam 
lock_version
 na mesma transacção.
O 
token
 anónimo é devolvido uma única vez; apenas SHA-256 é persistido. A aplicação define 
app.user_id
 e 
app.anonymous
_token_hash
 por ligação, e as políticas 
RLS
 autorizam o proprietário ou o 
hash
 correspondente, sempre com 
deleted_at
 IS 
NULL
.
Regras, parâmetros e versões 
published
 são imutáveis por 
trigger
; correcções 
criam nova
 versão.
A publicação exige fontes legais, decisões técnica e jurídica de revisores distintos do autor e 
rule_set_test_run
 com 
critical_total
=
critical_passed
.
A URL assinada do relatório é gerada na leitura e nunca guardada na base.
Gate SQL: migrations 
up
/
down
 em base vazia; 
pg_dump
 --
schema-only
; validação das exclusões temporais; testes de 
RLS
, concorrência, 
rollback
 e integridade referencial.
12. Contrato 
OpenAPI
 3.1 corrigido
O contrato abaixo elimina a chave components duplicada, explicita o 
token
 anónimo, associa scopes a cada operação protegida e alinha 
IDs
, versões, jobs, cenários, relatórios, 
ETag
 e soft delete com o SQL corrigido.
openapi
: 3.1.0
info: {title: 
InvestMoz
 Fiscal Simulator API, version: 1.0.0}
servers:
  - {url: 'https://investmoz.gov.mz/api/v1'}
components:
  
securitySchemes
:
    
bearerAuth
: {type: http, scheme: bearer, 
bearerFormat
: 
JWT
}
    oauth2Client:
      type: oauth2
      flows:
        
clientCredentials
:
          
tokenUrl
: 'https://identity.investmoz.gov.mz/oauth2/token'
          scopes: {
simulator.read
: 'Ler 
simulações
', 
simulator.write
: '
Alterar
 
simulações
', 
legislation.admin
: 'Gerir 
legislação
', 
rules.admin
: 'Gerir 
regras
', 
audit.read
: 'Ler auditoria'}
  parameters:
    Id: {name: id, in: path, required: true, schema: {type: string, format: 
uuid
}}
    
CorrelationId
: {name: X-Correlation-Id, in: header, schema: {type: string, format: 
uuid
}}
    
IdempotencyKey
: {name: Idempotency-Key, in: header, required: true, schema: {type: string, 
minLength
: 16, 
maxLength
: 100}}
    
IfMatch
: {name: If-Match, in: header, required: true, schema: {type: string}}
    
AnonymousToken
: {name: X-Anonymous-Simulation-Token, in: header, required: false, schema: {type: string, 
minLength
: 32}}
  schemas:
    ErrorResponse: {type: object, required: [error], properties: {error: {type: object, required: [code,message,correlation_id], properties: {code: {type: string}, message: {type: string}, correlation_id: {type: string, format: uuid}, fields: {type: array, items: {type: object}}}}}}
    VersionRef: {type: object, required: [id,version], properties: {id: {type: string, format: uuid}, version: {type: string}}}
    SimulationCreate: {type: object, additionalProperties: false, required: [reference_date,period_type,currency,questionnaire_version_id,answers], properties: {reference_date: {type: string, format: date}, period_type: {type: string, enum: [monthly,annual,project]}, currency: {type: string, pattern: '^[A-Z]{3}$'}, questionnaire_version_id: {type: string, format: uuid}, answers: {type: object}}}
    Simulation: {type: object, required: [id,status,lock_version,reference_date,period_type,currency,questionnaire,answers], properties: {id: {type: string, format: uuid}, status: {type: string, enum: [draft,validated,calculating,completed,failed,expired]}, lock_version: {type: integer, minimum: 1}, reference_date: {type: string, format: date}, period_type: {type: string}, currency: {type: string}, questionnaire: {$ref: '#/components/schemas/VersionRef'}, rule_set: {oneOf: [{$ref: '#/components/schemas/VersionRef'},{type: 'null'}]}, parent_simulation_id: {type: [string,'null'], format: uuid}, scenario_name: {type: [string,'null'], enum: [optimistic,base,conservative,null]}, answers: {type: object}, results: {type: array, items: {type: object}}, obligations: {type: array, items: {type: object}}}}
    Job: {type: object, required: [id,type,status,progress,attempts,max_attempts], properties: {id: {type: string, format: uuid}, type: {type: string, enum: [calculation,report,import,purge]}, status: {type: string, enum: [queued,running,completed,failed,dead_letter]}, progress: {type: integer, minimum: 0, maximum: 100}, attempts: {type: integer}, max_attempts: {type: integer}, resource_type: {type: [string,'null']}, resource_id: {type: [string,'null'], format: uuid}, error: {type: [object,'null']}}}
    Report: {type: object, required: [id,simulation_id,format,status], properties: {id: {type: string, format: uuid}, simulation_id: {type: string, format: uuid}, format: {type: string, enum: [pdf,json]}, status: {type: string, enum: [queued,running,completed,failed,dead_letter]}, checksum: {type: [string,'null']}, download_url: {type: [string,'null'], format: uri}, download_expires_at: {type: 
[string,'null'], format: date-time}}}
  responses:
    Unauthorized: {description: Não autenticado, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}}
    Forbidden: {description: Sem permissão, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}}
    NotFound: {description: Não encontrado, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}}
    Conflict: {description: Conflito, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}}
    PreconditionFailed: {description: ETag desactualizado, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}}
    Unprocessable: {description: Validação falhou, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}}
    TooManyRequests: {description: Limite excedido, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}}
    InternalError: {description: Erro interno, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorResponse'}}}}
13. Matriz de testes das fórmulas do MVP
Os valores de taxa marcados como parâmetro de teste são dados controlados do cenário, não afirmações da taxa legal vigente. Assim, os testes permanecem determinísticos quando a legislação muda. Para INSS usam-se, apenas nos casos indicados, 4% e 3% como configuração inicial a validar.
Leitura da matriz:
 cada linha é um caso automatizável. O ID deve ser reutilizado no nome do teste, no relatório de CI/CD e na evidência de aceitação. “Crítica” bloqueia a publicação; “Alta” exige correcção ou excepção formal aprovada antes do 
Go
-Live.
ID
Regra/cenário e entradas
Resultado esperado
Prioridade
IRPC-01
Rendimentos 1 000 000; gastos dedutíveis 600 000; correcções +50 000 e −20 000; prejuízos 30 000; taxa teste 32%.
LT=400 000; IRPC bruto=128 000.
Crítica
IRPC-02
LT calculado −100 000; taxa teste 32%.
Base sujeita=0; imposto=0; prejuízo sinalizado, nunca imposto negativo.
Crítica
IRPC-03
IRPC bruto 128 000; benefício elegível 20 000; créditos 15 000.
IRPC a pagar=93 000; linhas separadas e fontes presentes.
Alta
IRPC-04
Mesmo caso, mas certificado de benefício ausente.
Benefício não aplicado; aviso de evidência; IRPC=113 000 após créditos.
Crítica
IVA-01
Venda tributável 100 000; taxa teste 16%; IVA dedutível 6 000; crédito 2 000.
Liquidado=16 000; IVA a pagar=8 000.
Crítica
IVA-02
Venda tributável 100 000 e exportação 50 000 a taxa zero; taxa teste 16%.
Liquidado=16 000; exportação não gera IVA liquidado e permanece reportada.
Alta
IVA-03
Liquidado 5 000; IVA dedutível 7 500; crédito anterior 1 000.
IVA a pagar=0; crédito estimado=3 500.
Crítica
IVA-04
Operação isenta e IVA de compra sem direito 
a
 dedução.
IVA liquidado=0; IVA de compra não reduz imposto; motivo indicado.
Alta
ISPC-01
Elegível; base 500 000; taxa teste 3%.
ISPC=15 000; versão do parâmetro registada.
Crítica
ISPC-02
Volume acima do limite de elegibilidade configurado.
Não calcular ISPC; encaminhar para regime geral e emitir aviso.
Crítica
IRPS-01
Rendimento colectável exactamente no limite inferior de um escalão.
Aplicar parcela fixa sem diferença marginal; escolher um único escalão.
Crítica
IRPS-02
Rendimento um cêntimo abaixo e um cêntimo acima do limite.
Continuidade conforme tabela parametrizada; sem dupla tributação ou lacuna.
Crítica
INSS-01
Remuneração contributiva 100 000; empregador 4%; trabalhador 3%.
Empregador=4 000; trabalhador=3 000; total=7 000.
Crítica
INSS-02
Salário 80 000 e adicional não contributivo 20 000.
Base=80 000; contribuições não incluem o adicional; pressuposto exibido.
Alta
RET-01
Pagamento bruto 200 000; taxa doméstica teste 20%.
Retenção=40 000.
Crítica
RET-02
Convenção indica taxa teste 10%, mas certificado de residência ausente.
Não aplicar convenção; usar taxa doméstica e emitir aviso.
Crítica
RET-03
Convenção válida, país e certificado presentes; taxa teste 10%.
Retenção=20 000; fundamento doméstico e convencional incluídos.
Alta
ADU-01
Factura 1 000 USD; câmbio 65; frete 10 000 
MZN
; seguro 5 000; ajustamentos 0.
VA=80 000 
MZN
.
Crítica
ADU-02
VA=80 000; taxa pautal teste 20%.
Direitos=16 000.
Crítica
ADU-03
Sem código pautal.
Cálculo de direitos bloqueado com erro de validação; nenhum valor genérico.
Crítica
ICE-01
Base ICE 50 000; taxa ad valorem teste 10%.
ICE=5 000.
Alta
ICE-02
Quantidade 100 unidades; taxa específica teste 25 
MZN
/unidade.
ICE=2 500; unidade e quantidade preservadas.
Alta
IMP-IVA-01
VA 80 000; DA 16 000; ICE 5 000; outras imposições 1 000; taxa IVA teste 16%.
Base=102 000; IVA importação=16 320.
Crítica
CFT-01
IRPC 93 000; direitos 16 000; ICE 5 000; contribuição patronal 4 000; IVA recuperável 16 320.
CFT
=118 000; IVA recuperável excluído do custo e mostrado separadamente.
Crítica
TEF-01
CFT
 118 000; base económica lucro 400 000.
Taxa efectiva=29,50%; rótulo da base “lucro”.
Alta
ID
Teste transversal
Resultado esperado
Prioridade
TMP-01
Data na véspera, no dia e após mudança de taxa.
Cada simulação usa exactamente a versão válida na data; fronteiras [
início,fim
).
Crítica
TMP-02
Duas taxas publicadas com períodos sobrepostos.
Base rejeita a publicação por restrição temporal.
Crítica
RND-01
Valor que produz três ou mais casas decimais.
Arredondamento ocorre no ponto e modo configurados; relatório e API coincidem.
Crítica
CUR-01
Mesma factura com taxa de câmbio e data diferentes.
Resultados distintos e reproduzíveis; valor original, taxa e fonte guardados.
Alta
RULE-01
Regra publicada sem fonte legal.
Publicação bloqueada.
Crítica
RULE-02
Expressão contém função ou identificador não permitidos.
Validação rejeita sem executar código.
Crítica
RULE-03
Duas regras dependem circularmente uma da outra.
Cálculo bloqueado; ciclo identificado no erro administrativo.
Crítica
API-01
Repetir POST 
calculate
 com a mesma 
Idempotency-Key
 e corpo.
Uma execução; resposta original devolvida.
Crítica
API-02
Mesma chave com corpo diferente.
409 
IDEMPOTENCY_CONFLICT
.
Crítica
API-03
PATCH
 com 
ETag
 antigo.
412 
PRECONDITION_FAILED
; nenhuma alteração.
Alta
SEC-01
Utilizador tenta ler simulação de outro utilizador.
404 ou 403 conforme política; nenhum dado revelado.
Crítica
SEC-02
Autor tenta aprovar a própria regra.
Aprovação rejeitada pela segregação de funções.
Crítica
AUD-01
Publicar parâmetro.
Antes/depois, actor, data e correlação registados; registo não editável.
Alta
REP-01
Gerar PDF de simulação concluída.
Totais e referências reconciliam com JSON; checksum e versão presentes.
Crítica
PERF-01
Cenário normal com 100 regras e 500 parâmetros.
p95 do cálculo inferior a 2 segundos no ambiente de referência.
Alta
ACC-01
Navegação integral do questionário apenas por teclado.
Foco visível, ordem lógica, erros associados aos campos e resultado legível.
Alta
13.1 Critérios 
Go
/
No-Go
 do MVP
Go
:
 100% dos testes críticos aprovados; pelo menos 95% do total aprovado; zero vulnerabilidades críticas ou altas abertas sem excepção válida; 
reconciliação integral entre motor, base e relatório; revisão fiscal e jurídica assinada; 
rollback
 ensaiado; cópias de segurança e observabilidade verificadas.
No-Go
:
 qualquer fórmula crítica incorrecta; regra sem fonte; sobreposição de vigência; benefício aplicado sem elegibilidade; fuga de dados; divergência entre PDF e API; possibilidade de 
auto-aprovação
; recuperação ou 
rollback
 não demonstrados.
Gestão de excepções:
 nenhuma falha crítica pode ser aceite por excepção. Uma falha alta só pode permanecer aberta com análise de impacto, controlo compensatório, responsável, prazo e aprovação do 
Product
 
Owner
, segurança, operação e área fiscal ou jurídica afectada. A excepção deve ser 
versionada
, ligada ao requisito e ao teste, revista antes do prazo e convertida automaticamente em bloqueio quando expirar.
Evidências:
 relatório automatizado por versão do 
rule_set
, conjunto de casos dourados, assinatura dos revisores, 
logs
 de CI/CD, resultados de segurança e acta de aceitação operacional.
14. Validação de consistência entre SQL e OpenAPI
Conclusão:
 o SQL de referência e os componentes apresentados do contrato 
OpenAPI
 incorporam correcções para vigência dos rule sets, escopo temporal dos parâmetros, 
ETag
, eliminação lógica, 
token
 anónimo, cenários, jobs, 
idempotência
 composta, integridade das fontes e evidências de revisão e teste. Contudo, a prontidão para implementação directa continua condicionada à validação executável do 
DDL
 completo, do ficheiro 
OpenAPI
 integral e dos testes de contrato. As constatações desta secção devem ser tratadas como histórico das discrepâncias identificadas e reconciliadas com o estado final dos artefactos antes da aprovação.
Área
Estado anterior
Correcção incorporada no documento
Validação executável pendente
Simulações
Parcial
O contrato passou a representar questionário e conjunto de regras com identificador e versão separados, mantendo no SQL as chaves 
UUID
 e resolvendo as versões por relação.
Executar testes de contrato e confirmar a reconciliação entre 
joins
, modelos, 
schemas
 e respostas.
Concorrência
Inconsistente
Foi adicionado 
lock_version
; o 
ETag
 é derivado de id, 
lock_version
 e 
updated_at
, e as operações de alteração exigem 
If
-Match.
Executar API-03 e CON-01, incluindo actualizações e cálculos concorrentes sem duplicação.
Eliminação lógica
Ausente
Foram incorporados 
deleted_at
, 
deleted_by
 e 
deletion_reason
, com exclusão dos registos eliminados nas regras de acesso.
Validar migrações, 
RLS
, retenção, auditoria mínima e impossibilidade de leitura por endpoints normais.
Jobs
Ausente
Foi criada a entidade jobs com tipo, estado, progresso, tentativas, 
payload_hash
, recurso, erro e 
timestamps
.
Executar JOB-01 e testes de 
retry
 
idempotente
, 
backoff
, 
dead-letter
 e consulta do estado final.
Cenários
Ausente
Foram incorporados 
parent_simulation_id
, 
scenario_name
 e 
scenario_changes
, com unicidade das variantes activas.
Validar criação dos três cenários, concorrência, rastreabilidade e reconciliação com relatórios.
Anonimato
Parcial
O contrato define X-
Anonymous
-
Simulation-Token
; o 
token
 é emitido uma única vez e apenas o 
hash
 SHA-256 é persistido.
Executar ANON-01, testes de expiração, retenção, 
RLS
 e não exposição do 
hash
.
Vigência de rule set
Inconsistente
rule_sets
 passou a usar 
effective_period
 e 
scope_key
, com restrição de não sobreposição para conjuntos publicados.
Executar TMP-01, TMP-02 e PUB-01 nas fronteiras temporais e em publicações concorrentes.
Parâmetros
Crítico
Foi criada 
scope_key
 canónica com imposto, regime, jurisdição, actividade e moeda; a exclusão temporal aplica-se por âmbito, chave e período.
Executar SQL-02 e confirmar coexistência de combinações legítimas e rejeição de duplicados no mesmo âmbito.
Idempotência
Inconsistente
A chave primária passou a ser composta por 
owner_key
 e 
key
, com método, rota e expiração no índice de pesquisa.
Executar API-01 e API-02 para repetição equivalente, conflito de corpo e isolamento entre proprietários.
OpenAPI
Inválido
Os componentes foram consolidados num único bloco e os 
schemas
, parâmetros, respostas e mecanismos de segurança foram alinhados com o SQL corrigido.
Executar OAS-01 e OAS-02 sobre o ficheiro integral e formalizar e testar todos os 
paths
 administrativos.
Erros e segurança
Parcial
Foram definidos erros reutilizáveis, 
correlation
 ID, 
JWT
/
OAuth
 scopes, 
RBAC
, 
RLS
, 
ETag
, rate 
limiting
 e controlos de autorização.
Executar AUTH-01, SEC-01, SEC-02, RLS-01 e testes 401, 403, 412, 429 e 500 por operação.
Relatórios
Parcial
O 
schema
 
Report
 representa estado, checksum e URL temporária; a base conserva apenas 
object_key
, checksum e expiração.
Executar REP-01 e REP-02, incluindo propriedade, expiração e reconciliação entre PDF, JSON, API e base.
Fontes legais
Parcial
result_sources
 passou a guardar a disposição, cuja relação determina a versão legal, eliminando a duplicação divergente.
Executar SRC-01 e validar proveniência, vigência, 
hash
 e rastreabilidade até ao artigo aplicável.
Publicação
Parcial
Foram incorporadas 
review_decisions
 e 
rule_set_test_runs
, segregação de funções, fontes obrigatórias e imutabilidade após publicação.
Executar RULE-01, SEC-02, PUB-01 e IMM-01 e confirmar promoção atómica e evidências versionadas.
Gate de consistência:
 
é 
No-Go
 para geração automática de código enquanto 
o
 
OpenAPI
 
integral não passar num 
parser
 3.1, o 
DDL
 completo não
 executar 
migração 
e 
rollback
 
numa base vazia, 
todos os 
paths
 administrativos não estiverem formalizados
 e 
a 
reconciliação campo
 
a
 
campo
 entre SQL, modelos, 
schemas
, pedidos e respostas não estiver concluída. A aprovação exige evidências versionadas dos testes OAS-01, OAS-02, SQL-01 e SQL-02, sem discrepâncias bloqueadoras abertas.
15. Lacunas críticas da matriz de testes
ID proposto
Lacuna/cenário
Resultado esperado
Prioridade
SQL-01
Executar todas as migrações numa base vazia e depois 
rollback
 completo.
Up
 e 
down
 terminam sem erro; extensões, tipos, 
constraints
, 
views
 e 
triggers
 reconciliam.
Crítica
SQL-02
Parâmetros iguais no mesmo período, mas com jurisdição, actividade ou moeda diferentes.
Combinações legítimas coexistem; duplicado no mesmo scope é rejeitado.
Crítica
OAS-01
Validar 
openapi.yaml
 com 
parser
 
OpenAPI
 3.1.
Zero erros, chaves duplicadas ou referências quebradas.
Crítica
OAS-02
Executar testes de contrato positivos e negativos para todos os 
paths
.
Pedidos e respostas conformes; 
campos adicionais proibidos onde definido
.
Crítica
AUTH-01
JWT
 expirado, assinatura inválida e scope insuficiente.
401 ou 403 consistente; nenhum detalhe sensível revelado.
Crítica
ANON-01
Criar simulação anónima e reutilizar 
token
 correcto, ausente e incorrecto.
Acesso apenas com 
token
 correcto; 
hash
 nunca é exposto.
Crítica
RLS-01
Aceder directamente às tabelas com identidades de dois proprietários.
RLS
 impede leitura e alteração cruzadas, incluindo relatórios e soft-
deleted
.
Crítica
CON-01
Dois cálculos concorrentes para a mesma simulação e 
ETag
.
Uma execução vence; a outra recebe conflito/precondição, sem resultados duplicados.
Crítica
TX-01
Falha após gravar parte dos resultados.
Rollback
 integral; não ficam resultados, fontes ou obrigações parciais.
Crítica
JOB-01
Falha transitória e 
retry
 de cálculo/relatório.
Retry
 limitado e 
idempotente
; 
dead-letter
 após máximo; estado final consultável.
Crítica
PUB-01
Publicação concorrente de dois rule sets sobrepostos.
Apenas um é publicado; cache muda somente após 
commit
.
Crítica
IMM-01
Tentar alterar ou eliminar regra, parâmetro ou versão publicada.
Operação bloqueada; correcção exige nova versão.
Crítica
SRC-01
Fonte do resultado aponta para versão legal divergente da disposição.
Constraint
/
trigger
 rejeita ou o modelo derivado impede a inconsistência.
Crítica
IRPC-05
Prejuízo 
reportável
 excede o limite temporal ou quantitativo configurado.
Dedução limitada e saldo remanescente explicado.
Crítica
IVA-05
Pró-rata de IVA dedutível em operações mistas.
Apenas fracção parametrizada é deduzida; arredondamento documentado.
Crítica
IRPS-03
Múltiplos trabalhadores, periodicidade mensal/anual, deduções e situação familiar distintas.
Cálculo individual correcto; agregados não misturam bases.
Crítica
ADU-04
Preferência de origem alegada sem prova válida.
Taxa preferencial não aplicada; taxa geral e aviso apresentados.
Crítica
ADU-05
Frete/seguro em moeda diferente e ajustamento negativo.
Conversão por data/fonte correctas; ajustamento permitido validado.
Alta
CFT-02
Retenção recuperável versus custo definitivo.
Fluxo recuperável não integra 
CFT
; classificação e fonte explícitas.
Crítica
ZERO-01
Base da taxa efectiva igual a zero.
Não dividir por zero; taxa efectiva indisponível com explicação.
Crítica
PREC-01
Valores máximos de 
numeric
 e grande lote de importações.
Sem 
overflow
 ou perda silenciosa de precisão; erro controlado quando excede limites.
Crítica
RETEN-01
Expiração e expurgo de simulação anónima.
Dados operacionais removidos conforme política; auditoria mínima preservada.
Alta
REP-02
URL de relatório expirada ou usada por outro proprietário.
Acesso negado; nova URL pode ser emitida ao proprietário.
Crítica
ACC-02
Leitor de ecrã, zoom 200%, contraste, mensagens de erro e interface móvel.
Fluxo utilizável e conforme critérios 
WCAG
 adoptados.
Alta
DR-01
Restauro de base e objectos a partir de backup.
RPO
/
RTO
 atingidos; 
hashes
 e ligações relatório–simulação reconciliam.
Crítica
Avaliação:
 a matriz original cobre bem fórmulas básicas, fronteiras temporais, 
idempotência
, autorização, relatório e desempenho. As lacunas mais graves estavam na 
executabilidade
 do 
DDL
/
OpenAPI
, isolamento anónimo/
RLS
, concorrência transaccional, publicação, integridade das fontes e casos fiscais compostos. Os casos acima devem integrar a matriz oficial; SQL-01, OAS-01, AUTH-01, RLS-01, TX-01, PUB-01 e ZERO-01 são pré-condições do MVP.
16. Plano de implementação do MVP por sprint
Cadência proposta:
 Sprint 0 de uma semana e seis sprints de duas semanas, totalizando 13 semanas, seguidas de estabilização assistida. Equipa mínima: 
Product
 
Owner
, fiscalista, jurista, UX/UI, dois 
back-end
, dois 
front-end
, 
QA
/automação e 
DevOps
/segurança, com apoio de dados/conteúdo jurídico.
Sprint
Objectivo e entregáveis
Critérios de saída
Dependências
Sprint 0 — Fundação e decisões (1 semana)
Fechar escopo do MVP; corrigir mapa SQL–
OpenAPI
; 
ADRs
 de autenticação, 
token
 anónimo, motor de expressões, moedas, arredondamento e retenção; 
backlog
 e 
Definition
 
of
 
Done
; ambientes e pipeline inicial.
OpenAPI
 e 
DDL
 corrigidos em revisão; riscos e responsáveis aprovados; protótipo do questionário validado; fontes legais 
prioritárias inventariadas.
PO, fiscalista, jurista, arquitectura, IAM e critérios de segurança.
Sprint 1 — Dados e repositório legislativo
Migrações PostgreSQL/
PostGIS
; entidades legais, versões, artigos, relações, jurisdições e actividades; armazenamento de objectos; pesquisa; 
seeds
 não fiscais; auditoria base.
SQL-01 aprovado; restrições temporais testadas; pesquisa e importação de diploma demonstradas; 
rollback
 validado.
DDL
 corrigido, ambiente CI e convenção de migrações.
Sprint 2 — Governação de parâmetros e regras
Tax
 
types
, regimes, parâmetros, rule sets, regras, fontes, elegibilidade, obrigações, decisões de revisão e 
test
 runs; painel administrativo mínimo; 
workflow
 de quatro olhos.
Scope temporal sem ambiguidades; regra sem fonte não publica; 
auto-aprovação
 bloqueada; PUB-01 e IMM-01 aprovados.
Modelo jurídico validado e linguagem de expressões escolhida.
Sprint 3 — API e questionário
OpenAPI
 válido; 
schema
 e catálogos; criar, consultar, editar, validar e eliminar logicamente simulações; 
JWT
, 
token
 anónimo, 
RLS
, 
ETag
, 
idempotência
, erros e rate 
limiting
.
OAS-01/OAS-02, AUTH-01, ANON-01, RLS-01 e API-01–03 aprovados; questionário responsivo navegável por teclado.
IAM/
SSO
, catálogos e JSON 
Schema
 do questionário.
Sprint 4 — Motor fiscal principal
Grafo de dependências; 
sandbox
 segura; parâmetros vigentes; explicabilidade; IRPC, IVA, ISPC, IRPS, INSS e retenções; persistência atómica de resultados e fontes.
Todos os testes críticos destas fórmulas aprovados; TX-01, RULE-02/03, TMP-01 e RND-01 aprovados; casos dourados assinados.
Taxas e escalões oficialmente validados; decisões sobre pró-rata e prejuízos.
Sprint 5 — Aduanas, cenários e obrigações
Valor aduaneiro, direitos, ICE, IVA de importação, câmbio, preferências de origem; cenários; obrigações fiscais/cambiais; jobs persistidos e 
retries
.
ADU-01–05, ICE, IMP-IVA, CUR-01, JOB-01 e cenários aprovados; ausência de código pautal bloqueia cálculo definitivo.
Pauta/códigos, taxas de câmbio e regras de origem carregadas e validadas.
Sprint 6 — Relatórios, endurecimento e 
Go
-Live
PDF/JSON, reconciliação e checksum; observabilidade; backups/restauro; testes de carga, segurança e acessibilidade; conteúdos de aviso; formação e 
runbooks
; homologação.
REP-01/02, PERF-01, ACC-01/02 e DR-01 aprovados; zero falhas críticas; revisão fiscal/jurídica assinada; 
Go
/
No-Go
 aprovado.
Ambiente de produção, certificados, monitorização, suporte e donos operacionais.
16.1 Trilhos transversais e gates
Fiscal e jurídico:
 validar legislação, parâmetros, fórmulas, exemplos, avisos e data de vigência em todas as sprints; nenhuma taxa entra por decisão técnica isolada.
Qualidade:
 teste acompanha a história no mesmo sprint; cada regra tem testes unitários, contrato, integração e caso dourado.
Segurança e privacidade:
 
threat
 
modelling
 no Sprint 0, revisão de código contínua, 
SAST
/DAST, 
RLS
 e testes de autorização antes de cada 
release
.
Acessibilidade:
 revisão de UX desde o protótipo; teclado, leitor de ecrã, contraste, zoom e móvel não ficam apenas para o final.
Dados e conteúdo:
 importação controlada de diplomas e parâmetros decorre em paralelo, com 
hash
, fonte, revisão e evidência.
Gate A — fim do Sprint 2:
 modelo de governação publicável e reversível.
Gate B — fim do Sprint 4:
 motor principal reconciliado com casos dourados.
Gate C — fim do Sprint 6:
 
Go
-Live apenas com 100% dos testes críticos, aceitação operacional, 
rollback
, 
backup/restauro e aprovações fiscal e jurídica
.
Fora do MVP
 fiscal inicial
:
 benefícios complexos 
de 
ZEE/ZFI, convenções completas de dupla tributação, regimes sectoriais, 
integrações directas
 com entidades externas, conta avançada do investidor e assistente inteligente permanecem no 
backlog
, salvo 
requisito legal indispensável
. O formulário integrado, a manifestação formal,
 a 
oportunidade de negócio, o caso CRM e as conversões para projecto ou oportunidade constituem uma extensão funcional posterior. A arquitectura, os contratos e os pontos de integração podem ser preparados no MVP, mas a entrada em produção dessa extensão depende de aprovação específica do seu modelo de dados, 
OpenAPI
, segurança, privacidade, testes e operação
.
16.2 Matriz consolidada de validação
Cobertura e rastreabilidade:
 a aprovação deve demonstrar responsável, evidência e estado para requisitos; legislação e vigência; fórmulas e casos dourados; dados mestre e importações; SQL e migrações; 
OpenAPI
 e contratos; autenticação, autorização e 
RLS
; privacidade e retenção; concorrência e 
idempotência
; relatórios e reconciliação; desempenho e capacidade; acessibilidade e compatibilidade; observabilidade e incidentes; backup, restauro e continuidade; e homologação fiscal, jurídica, operacional e dos utilizadores. Um domínio sem evidência permanece “Não validado” e bloqueia o 
Go
-Live quando classificado como crítico.
Protecção de dados:
 antes da produção, aprovar o inventário de dados pessoais, finalidades, bases de tratamento, minimização, prazos de retenção, direitos dos titulares, acesso administrativo, partilha com terceiros, localização do armazenamento e procedimento de incidente. Os testes devem confirmar avisos ou consentimentos aplicáveis, expiração e expurgo de simulações anónimas, anonimização de métricas, restrição de 
logs
 e impossibilidade de recuperar dados eliminados fora das excepções de auditoria legalmente justificadas.
Qualidade dos dados importados:
 cada carga deve comprovar completude, unicidade, validade, consistência, actualidade e proveniência. A reconciliação 
deve comparar contagens de origem e destino, 
hashes
, períodos de vigência, códigos de actividade, jurisdições, moedas, códigos pautais e referências legais. Registos rejeitados permanecem numa fila de correcção, sem publicação parcial silenciosa, e toda recarga deve ser 
idempotente
 e 
auditável
.
Compatibilidade e resiliência:
 testar navegadores e dispositivos oficialmente suportados, falhas de rede, repetição de pedidos, sessões expiradas e indisponibilidade do IAM, armazenamento de objectos, serviço PDF, Redis e fontes externas. O utilizador deve conservar o rascunho quando possível, receber mensagens accionáveis e nunca obter resultados parcialmente persistidos. Devem existir testes de degradação controlada, 
circuit
 
breaker
, 
timeouts
, filas acumuladas e recuperação após indisponibilidade.
Continuidade:
 definir e aprovar 
RTO
, 
RPO
, frequência e retenção de backups, responsabilidades de recuperação, dependências críticas e periodicidade dos ensaios. O teste DR-01 deve medir os tempos efectivos, confirmar a integridade dos 
hashes
, reconciliar base e armazenamento de objectos e demonstrar recuperação num ambiente isolado. Qualquer resultado acima dos limites aprovados determina 
No-Go
.
Obrigações e calendário fiscal:
 testar periodicidade, primeiro e último período, dias úteis, fins-de-semana, feriados, prorrogações, início e cessação de actividade, obrigações sem imposto a pagar e alterações de prazo durante a vigência. Cada prazo deve indicar regra, autoridade, data de referência, fórmula de vencimento e fonte legal. O calendário apresentado no ecrã, no JSON e no PDF deve reconciliar integralmente.
Cobertura fiscal adicional:
 
imposto do selo e impostos autárquicos ficam 
fora do cálculo
 do MVP fiscal. O questionário deve recolher apenas os dados necessários para identificar a possível aplicabilidade, e o resultado deve apresentar a limitação, o fundamento disponível e o encaminhamento para validação especializada. A inclusão futura exige
 perguntas, parâmetros, fórmulas, fontes, 
vigência, testes de fronteira e 
aprovação fiscal e jurídica.
Teste E2E-01 — Jornada integral:
 criar uma simulação anónima e uma autenticada, preencher o questionário, validar dados, calcular, gerar três cenários, consultar explicações e fontes, produzir PDF e JSON, guardar ou retomar o rascunho e eliminar logicamente a simulação. O resultado esperado é consistência entre interface, API, base, relatório, auditoria e permissões, sem perda, duplicação ou exposição de dados.
17. Fases de implementação e respectivos prompts
Regra de execução:
 as fases devem ser executadas pela ordem indicada. Cada 
prompt
 começa pela inspecção do repositório e dos artefactos existentes, preserva compatibilidade, evita alterações destrutivas, exige migrações reversíveis, testes 
automatizados, evidências versionadas e relatório de ficheiros alterados. O avanço depende da aprovação dos critérios de saída da fase anterior. Nenhuma taxa, fórmula, obrigação ou interpretação legal pode ser publicada sem fonte oficial e validação fiscal e jurídica.
Fase 0 — Preparação, escopo e governação
Objectivo:
 fechar o âmbito do MVP e estabelecer as condições de governação, segurança jurídica e controlo da execução.
Entregáveis:
 escopo e exclusões; 
RACI
; 
backlog
 priorizado; 
Definition
 
of
 
Ready
 e 
Definition
 
of
 
Done
; matriz de riscos; inventário inicial de fontes; 
ADRs
; matriz de rastreabilidade; critérios 
Go
/
No-Go
.
Dependências:
 
Product
 
Owner
, fiscalista, jurista, arquitectura, segurança, IAM e representantes operacionais.
Critérios de saída:
 decisões bloqueadoras atribuídas; requisitos críticos rastreáveis; fontes prioritárias identificadas; risco, responsável e evidência definidos.
Prompt de execução:
 “Inspeccione integralmente o repositório e a documentação do Simulador Fiscal 
InvestMoz
. Sem alterar código funcional, consolide o escopo do MVP, exclusões, actores, matriz 
RACI
, 
backlog
, riscos, 
Definition
 
of
 
Ready
, 
Definition
 
of
 
Done
, critérios de aceitação, fluxo de validação fiscal/jurídica e gates. Produza 
ADRs
 para autenticação, 
token
 anónimo, motor de expressões, versionamento temporal, moedas, arredondamento, retenção, backup e recuperação. Não invente requisitos nem dados legais. Preserve os artefactos existentes e registe conflitos e decisões pendentes. Entregue matriz requisito–responsável–evidência–teste–gate. Termine com recomendação AVANÇAR, CORRIGIR ou BLOQUEAR.”
Fase 1 — Fundação técnica e validação dos contratos
Objectivo:
 garantir uma base técnica executável, coerente e reversível antes da implementação funcional.
Entregáveis:
 
DDL
 e migrações; 
OpenAPI
 3.1 integral; mapa SQL–modelos–
schemas
–endpoints; ambientes; CI/CD; gestão de segredos; observabilidade inicial; backup e 
rollback
.
Dependências:
 decisões da Fase 0 e acesso aos ambientes de desenvolvimento e teste.
Critérios de saída:
 SQL-01, SQL-02, OAS-01 e OAS-02 aprovados; migração e 
rollback
 numa base vazia; zero referências quebradas ou discrepâncias bloqueadoras.
Prompt de execução:
 “Compare campo a campo o 
DDL
 PostgreSQL/
PostGIS
, as migrações Laravel, os modelos e o 
OpenAPI
 3.1. Corrija incrementalmente 
IDs
, versões, vigência temporal, 
ETag
, soft delete, 
token
 anónimo, cenários, jobs, 
idempotência
, relatórios e erros. Não altere interfaces públicas sem versionamento nem execute operações irreversíveis. Configure ambientes e pipeline com 
lint
, testes, 
SAST
, análise de dependências, segredos, 
SBOM
, migrações verificadas, backup e 
rollback
. Valide o 
OpenAPI
 num 
parser
 3.1 e execute migrações 
up
/
down
 numa base vazia. Entregue matriz de reconciliação, comandos, resultados e riscos. Bloqueie a fase seguinte se SQL-01/02 ou OAS-01/02 falharem.”
Fase 2 — Repositório legislativo e qualidade dos dados
Objectivo:
 criar a fonte única, 
versionada
 e 
auditável
 de legislação, parâmetros e dados mestre.
Entregáveis:
 autoridades, instrumentos, versões, disposições, relações, jurisdições 
PostGIS
, actividades, documentos com 
hash
, pesquisa textual, importadores 
idempotentes
 e fila de rejeições.
Dependências:
 
DDL
 validado e fontes oficiais inventariadas.
Critérios de saída:
 proveniência completa; ausência de sobreposição de vigência; reconciliação de origem e destino; 
rollback
 e recarga 
idempotente
 aprovados.
Prompt de execução:
 “Implemente por migrações Laravel reversíveis o repositório legislativo e os catálogos territoriais e económicos. Crie modelos, relações, 
constraints
 temporais, policies, 
services
, armazenamento documental, 
hashes
 e pesquisa. Desenvolva importadores 
idempotentes
 que validem completude, unicidade, validade, consistência, actualidade e proveniência; compare contagens, 
hashes
, vigências, códigos e referências. Mantenha registos rejeitados numa fila de correcção e proíba publicação parcial silenciosa. Não carregue taxas ou regras de demonstração como vigentes. Execute testes de importação, duplicação, sobreposição, 
rollback
 e reconciliação. Termine apenas quando cada registo publicado tiver fonte e estado de revisão.”
Fase 3 — Governação de regras, parâmetros e publicação
Objectivo:
 assegurar que parâmetros, fórmulas e obrigações são governados por 
workflow
, segregação de funções e evidência.
Entregáveis:
 tipos de imposto, regimes, parâmetros, rule sets, regras, fontes, elegibilidade, obrigações, decisões de revisão, 
test
 runs e painel administrativo mínimo.
Dependências:
 repositório legislativo operacional e linguagem segura de expressões aprovada.
Critérios de saída:
 regra sem fonte não publica; autor não se 
auto-aprova
; versões publicadas são imutáveis; PUB-01 e IMM-01 aprovados.
Prompt de execução:
 “Implemente a governação de tipos de imposto, regimes, parâmetros, conjuntos de regras, fórmulas, fontes, elegibilidade e obrigações. Aplique o fluxo rascunho → revisão técnica → revisão jurídica → aprovação → publicação, com revisores distintos, promoção atómica, histórico e imutabilidade após publicação. Utilize uma linguagem de expressões restrita, sem 
eval
 ou execução arbitrária, com validação de identificadores, funções e ciclos. Exija fonte legal, decisões válidas e execução de testes críticos antes da publicação. Crie testes RULE-01–03, SEC-02, PUB-
01, IMM-01 e TMP-02. Preserve resultados históricos e implemente 
rollback
 por nova versão, nunca por alteração do publicado.”
Fase 4 — API, segurança, privacidade e questionário
Objectivo:
 disponibilizar uma jornada segura, acessível e consistente para utilizadores anónimos e autenticados.
Entregáveis:
 API Laravel; 
JWT
 e 
scopes; 
RBAC
; 
RLS
; 
token
 anónimo; 
ETag
; 
idempotência
; rate 
limiting
; retenção; questionário React/Next.js 
versionado
; 
dropdowns
 pesquisáveis e acessíveis; dependências entre catálogos; ausência de 
defaults
 fiscais; 
gravação e retoma de rascunho.
Dependências:
 
OpenAPI
 aprovado, IAM/
SSO
, 
endpoints de catálogo estáveis, desenho de campos aprovado e 
workflow
 de regras.
Critérios de saída:
 AUTH-01, ANON-01, RLS-01, API-01–03, SEC-01/02
, testes
 de privacidade
, interface, teclado, leitor de ecrã, 
autosave
 e validação cliente/servidor
 aprovados
.
Prompt de execução:
 
“Implemente a API conforme o 
OpenAPI
 aprovado e o questionário React/Next.js baseado em JSON 
Schema
 
versionado
. 
Todo campo com 
mais de duas opções
 deve usar dropdown pesquisável e acessível; campos 
multivalor
 devem permitir selecção e remoção por teclado; 
dropdowns
 dependentes devem limpar filhos inválidos; e ‘Outro’ deve abrir campo condicional. Não defina 
defaults
 fiscais. 
Use 
DTOs
, 
Form
 Requests, 
Resources
, serviços de domínio, transacções e erros com 
correlation
 ID. Aplique 
JWT
/
OAuth
 scopes, 
RBAC
, 
RLS
, 
token
 anónimo persistido apenas como SHA-256, 
ETag
/
If
-Match, 
idempotência
, rate 
limiting
, encriptação, minimização, retenção e soft delete. Implemente etapas condicionais, validação cliente/servidor, 
estados de 
loading
 e erro, 
rascunho
,
 retoma segura
 e experiência móvel.
 Teste sessões expiradas, falhas de rede e indisponibilidade do IAM sem perda ou exposição de dados. Não duplique cadastros do 
InvestMoz
. Entregue evidências de segurança, privacidade e acessibilidade.”
Fase 5 — Motor fiscal principal e explicabilidade
Objectivo:
 implementar cálculos determinísticos, reproduzíveis e ligados às regras e fontes vigentes.
Entregáveis:
 motor de elegibilidade; grafo de dependências; IRPC, IVA, ISPC, IRPS, INSS e retenções; precisão e arredondamento; instantâneos de fórmulas, parâmetros, pressupostos e fontes.
Dependências:
 rule set publicado e taxas, escalões e decisões fiscais oficialmente validados.
Critérios de saída:
 casos dourados assinados; testes críticos das fórmulas aprovados; TX-01, TMP-01, RND-01, ZERO-01 e PREC-01 aprovados.
Prompt de execução:
 “Implemente um motor fiscal determinístico que seleccione apenas regras e parâmetros publicados cuja vigência inclua a data de referência. 
Resolva dependências como grafo acíclico, utilize tipos decimais e arredondamento configurado e grave numa única transacção a fórmula, os valores substituídos, parâmetros, pressupostos, avisos e fontes. Desenvolva elegibilidade e cálculos de IRPC, IVA, ISPC, IRPS, INSS e retenções sem codificar taxas no código nem presumir benefícios ou convenções. Implemente limites, pró-rata, prejuízos, ausência de evidência, zero, fronteiras e grandes valores. Execute todos os testes críticos e casos dourados; faça 
rollback
 integral se qualquer resultado ou fonte falhar.”
Fase 6 — Aduanas, câmbios, cenários e calendário
Objectivo:
 completar o custo fiscal do investimento e as obrigações associadas a importações, câmbios e prazos.
Entregáveis:
 valor aduaneiro, direitos, ICE, IVA de importação, moedas, origem, preferências, cenários, obrigações fiscais/cambiais, calendário e jobs persistidos.
Dependências:
 pauta, códigos, regras de origem, taxas de câmbio e normas cambiais validadas.
Critérios de saída:
 ADU-01–05, ICE, IMP-IVA, CUR-01, CON-01, JOB-01 e testes de calendário aprovados; ausência de código ou prova bloqueia taxa definitiva.
Prompt de execução:
 “Implemente o cálculo do valor aduaneiro, direitos, ICE e IVA de importação, preservando valor original, moeda, taxa, data e fonte. Exija código pautal para cálculo definitivo e prova válida para qualquer preferência de origem. Implemente cenários optimista, base e conservador, obrigações fiscais e cambiais, cálculo de vencimentos, feriados, prorrogações, início e cessação de actividade e obrigações sem imposto a pagar. Crie jobs persistidos, 
retries
 
idempotentes
, 
backoff
 e 
dead-letter
. Separe obrigações cambiais de impostos. Execute ADU-01–05, ICE, IMP-IVA, CUR-01, CON-01, JOB-01 e reconcilie calendário entre ecrã, JSON e PDF.”
Fase 7 — Relatórios, qualidade integral e homologação
Objectivo:
 demonstrar que todas as camadas funcionam em conjunto e preparar a aceitação formal.
Entregáveis:
 interface /Simulador; explicações; PDF e JSON; checksum; observabilidade; testes unitários, integração, contrato, segurança, desempenho, acessibilidade, resiliência, backup/restauro e E2E-01.
Dependências:
 motores, API, UI e conteúdos legais concluídos.
Critérios de saída:
 100% dos testes críticos e pelo menos 95% do total aprovados; PDF, JSON, API e base reconciliados; homologação fiscal, jurídica, operacional e dos utilizadores assinada.
Prompt de execução:
 “Integre a jornada completa em /Simulador, incluindo progresso, validações, cenários, explicações, fontes, obrigações, avisos e relatórios PDF/JSON. Garanta que 
URLs
 assinadas são emitidas apenas ao proprietário e que relatórios reconciliam com o instantâneo persistido. Execute testes unitários, integração, contrato, regressão, segurança, 
RLS
, concorrência, transacções, desempenho, 
acessibilidade, compatibilidade, degradação, retenção, backup/restauro e E2E-01 para utilizador anónimo e autenticado. Não marque testes ignorados ou instáveis como aprovados. Gere relatório de cobertura, falhas, severidade, riscos residuais e acta de homologação.”
Fase 8 — 
Go
-Live, estabilização e evolução contínua
Objectivo:
 publicar de forma controlada, estabilizar o serviço e instituir actualização normativa contínua.
Entregáveis:
 decisão 
Go
/
No-Go
; 
release
 imutável; plano de implantação e 
rollback
; monitorização; 
hypercare
; gestão de incidentes; processo de actualização de normas; roadmap pós-MVP.
Dependências:
 homologação assinada, ambiente de produção, suporte, responsáveis operacionais e continuidade aprovada.
Critérios de saída:
 zero falhas críticas; nenhuma vulnerabilidade alta aberta sem excepção válida; 
rollback
 e DR-01 demonstrados; serviço estável; processo de nova versão 
auditável
.
Prompt de execução:
 “Execute o checklist 
Go
/
No-Go
 a partir das evidências do CI/CD e da homologação. Bloqueie o 
Go
 se existir teste crítico falhado, cobertura abaixo de 95%, vulnerabilidade crítica ou alta sem excepção válida, regra sem fonte, divergência de relatório, 
auto-aprovação
, sobreposição temporal, 
rollback
 ou recuperação não demonstrados. Após decisão 
Go
 assinada, prepare uma 
release
 imutável do código, questionário, migrações e rule set; faça backup, implantação controlada, 
smoke
 
tests
, observabilidade e 
rollback
 automático em caso de falha. Implemente 
hypercare
 com métricas e incidentes. Para alterações legais futuras, 
crie sempre nova
 versão, repita validação e casos dourados, preserve simulações anteriores e publique atomicamente. Produza relatório final e roadmap das funcionalidades pós-MVP.”
Prompt mestre de controlo sequencial:
 “Actue como coordenador técnico da implementação do Simulador Fiscal 
InvestMoz
. Antes de iniciar uma fase, leia o relatório e as evidências da fase anterior; confirme critérios de saída, testes, aprovações e riscos. Decida apenas entre AVANÇAR, CORRIGIR ou BLOQUEAR. Nunca avance porque o código apenas compilou; não elimine dados, não force migrações, não contorne testes, não publique taxas ou regras sem validação e não altere interfaces públicas sem versionamento. Em cada ciclo apresente estado, evidências, desvios, acções correctivas, responsável sugerido, riscos residuais e próximo 
prompt
 autorizado.”
17.1 Pacote de execução sequencial para 
Codex
Modo de utilização:
 copiar para o 
Codex
 primeiro o 
prompt
 da fase e depois fornecer o respectivo script como modelo de orquestração. O 
Codex
 deve adaptar comandos, nomes e caminhos à estrutura real detectada, sem assumir que Laravel, Next.js, 
PostgreSQL, Docker ou ferramentas de teste estão instalados nos locais exemplificados. Os scripts usam modo estrito, geram evidências em 
artifacts
/fase-N
, não publicam taxas fiscais, não alteram migrações já executadas e não avançam quando um gate falha. Antes da primeira execução, criar uma 
branch
 de trabalho e rever manualmente o plano e os ficheiros propostos.
Fase 0 — Preparação, escopo e governação
Prompt para 
Codex
:
 “Inspecciona o repositório e a documentação sem alterar código funcional. Identifica 
stack
, versões, comandos, estrutura, CI, testes, convenções e restrições. Consolida o âmbito do MVP fiscal, exclusões, 
RACI
, 
backlog
, riscos, 
ADRs
, matriz de rastreabilidade e gates. Não inventes taxas, regras ou fontes. Cria apenas documentação 
versionada
 e um relatório de bloqueios. Entrega plano, ficheiros alterados, evidências e decisão AVANÇAR, CORRIGIR ou BLOQUEAR.”
Script de 
orquestração
 — 
scripts/codex/fase-0-governacao.sh
:
#!/
usr/bin/env bash
set -
Eeuo
 
pipefail
PHASE=0; OUT="artifacts/
fase
-$PHASE"; 
mkdir
 -p "$OUT"
test -
d .git
 || 
{ echo
 "
BLOQUEAR
: 
repositório
 Git 
ausente
" | tee "$OUT/gate.txt"; exit 2
; }
git status --short | tee "$OUT/git-status-before.txt"
find .
 -
maxdepth
 2 -type f \( -name '
composer.json
' -o -name '
package.json
' -o -name '
openapi
*.y*ml' -o -name 'docker-compose*.y*ml' \) -print | sort | tee "$OUT/inventory.txt"
mkdir
 -p docs/governance docs/
adr
 docs/traceability
test -f docs/governance/mvp-scope.md || 
printf
 '# 
Âmbito
 do MVP\n\
nPendente
 de 
validação
 humana.\n' > docs/governance/mvp-scope.md
test -f docs/governance/raci.md || 
printf
 '# 
Matriz
 RACI\n' > docs/governance/raci.md
test -f docs/traceability/requirements-matrix.csv || 
printf
 '
requirement,owner,evidence,test,gate,status
\n' > docs/traceability/requirements-matrix.csv
git diff --check | tee "$OUT/diff-check.txt"
git diff --stat | tee "$OUT/diff-stat.txt"
APPROVAL="${
GOVERNANCE_APPROVAL_ID
:-}"
if test -n "$APPROVAL" && ! grep -
Rqs
 'Pendente de 
validação
 humana' docs/governance docs/
adr
 docs/traceability; then 
printf
 '
AVANÇAR
 approval=%s\n' "$APPROVAL" | tee "$OUT/gate.txt"; else echo '
CORRIGIR
: 
completar
 
artefactos
 e 
informar
 
GOVERNANCE_APPROVAL_ID
' | tee "$OUT/gate.txt"; exit 3; fi
Gate:
 âmbito, exclusões, responsáveis, riscos e decisões bloqueadoras aprovados; nenhuma alteração funcional introduzida.
Fase 1 — Fundação técnica e contratos executáveis
Prompt para 
Codex
:
 “Reconcilia 
DDL
, migrações Laravel, modelos e 
OpenAPI
 3.1 campo a campo. Corrige apenas discrepâncias comprovadas, 
cria novas
 migrações reversíveis, valida referências, contratos, 
ETag
, 
idempotência
, soft delete, 
token
 anónimo, jobs e relatórios. Configura CI sem expor segredos. Executa SQL-01, SQL-02, OAS-01 e OAS-02. Se qualquer teste falhar, pára e regista o bloqueio.”
Script — 
scripts/
codex
/fase-1-fundacao.sh
:
#!/usr/bin/env 
bash
set -
Eeuo
 
pipefail
PHASE
=1; OUT="
artifacts
/fase-$
PHASE
"; 
mkdir
 -p "$OUT"
git
 
diff
 --
quiet
 || { 
echo
 'BLOQUEAR: árvore de trabalho não está limpa' | tee "$OUT/gate.txt"; exit 2; }
test
 "${
APP_ENV
:-}" = 
testing
 || { 
echo
 'BLOQUEAR: 
APP_ENV
 deve ser 
testing
' | tee "$OUT/gate.txt"; exit 2; }
test
 "${
ALLOW_DESTRUCTIVE_TEST_DB
:-false}" =
 
true
 || { 
echo
 'BLOQUEAR: 
ALLOW_DESTRUCTIVE_TEST_DB
=
true
 ausente' | tee "$OUT/gate.txt"; exit 2; }
case "${
DB_DATABASE
:-}" in *
prod
*|*
production
*|'') 
echo
 'BLOQUEAR: base de teste não comprovada' | tee "$OUT/gate.txt"; exit 2;; 
esac
OAS=$(
find
 .
 -
maxdepth
 4 \( -
name
 '
openapi.yaml
' -o -
name
 '
openapi.yml
' \) | 
head
 -n1 || 
true
)
test
 -n "$OAS" || { 
echo
 'BLOQUEAR: 
OpenAPI
 integral não encontrado' | tee "$OUT/gate.txt"; exit 2; }
npx
 --
yes
 @redocly/cli 
lint
 "$OAS" 2>&
1 | tee "$OUT/oas-lint.txt"
test
 -f 
artisan
 || { 
echo
 'BLOQUEAR: Laravel não detectado' | tee "$OUT/gate.txt"; exit 2; }
php
 
artisan
 
migrate:fresh
 --
env
=
testing
 2>&1 | tee "$OUT/migrate-up.txt
"
php
 
artisan
 
migrate:rollback
 --step=999 --
env
=
testing
 2>&1 | tee "$OUT/migrate-down.txt
"
php
 
artisan
 
migrate:fresh
 --
env
=
testing
 2>&1 | tee "$OUT/migrate-reapply.txt
"
composer
 
validate
 --
strict
 2>&1 | tee "$OUT/composer-validate.txt
"
test
 -f package
-
lock
.json
 &&
 
npm
 ci
 || 
true
npm
 
run
 
lint
 --
if-present
 2>&
1 | tee "$OUT/npm-lint.txt
"
npm
 
test
 --
if-present
 -- --
runInBand
 2>&1 | tee "$OUT/npm-test.txt
"
git
 
diff
 --
check
 | tee "$OUT/diff-check.txt"
test
 -n "${
TECHNICAL_APPROVAL_ID
:-}" || { 
echo
 'CORRIGIR: aprovação técnica ausente' | tee "$OUT/gate.txt"; exit 3; }
echo
 "AVANÇAR 
approval
=${
TECHNICAL_APPROVAL_ID
}"
 | tee "$OUT/gate.txt"
Rollback
:
 reverter apenas as novas migrações e 
commits
 da fase; nunca editar migrações executadas em produção.
Fase 2 — Repositório legislativo e qualidade dos dados
Prompt para 
Codex
:
 “Implementa autoridades, instrumentos, versões, disposições, relações, jurisdições 
PostGIS
, actividades, documentos com 
hash
, pesquisa e importadores 
idempotentes
. Usa novas migrações Laravel, 
constraints
 temporais e serviços de domínio. Não publiques dados sem fonte e revisão. Rejeita cargas parciais silenciosas e gera reconciliação de origem/destino.”
Script — 
scripts/codex/fase-2-legislacao.sh
:
#!/usr/bin/env bash
set -
Eeuo
 
pipefail
PHASE=2; OUT="artifacts/
fase
-$PHASE"; 
mkdir
 -p "$OUT"
test -f artisan || { echo '
BLOQUEAR
: Laravel 
não
 
detectado
' | tee "$OUT/gate.txt"; exit 2; }
php
 artisan migrate --env=testing 2>&1 | tee "$OUT/migrate.txt"
php
 artisan test --
testsuite
=Feature --filter='
Legislation|Legal|Import|Jurisdiction
' 2>&1 | tee "$OUT/tests.txt"
php
 artisan list --raw | grep -q '^
legislation:import
'
 || { echo '
BLOQUEAR
: 
importador
 
legislativo
 
ausente
' | tee "$OUT/gate.txt"; exit 2; }
php
 artisan 
legislation:import
 --dry-run --source="${1:-fixtures/legal}" 2>&
1 | tee "$OUT/import-dry-run.txt
"
php
 artisan list --raw | grep -q '^
legislation:reconcile
'
 || { echo '
BLOQUEAR
: 
comando
 de 
reconciliação
 
ausente
' | tee "$OUT/gate.txt"; exit 2; }
php
 artisan 
legislation:reconcile
 2>&1 | tee "$OUT/reconciliation.txt
"
grep -
RInE
 'status.{0,20}(
published|approved
)' database/seeders 2>/dev/null | tee "$OUT/published-seed-review.txt" || true
if test -s "$OUT/published-seed-review.txt" && test -z "${
LEGAL_SEED_APPROVAL_ID
:-}"; then echo '
BLOQUEAR
: seeds 
publicados
 
sem
 
autorização
 
identificada
' | tee "$OUT/gate.txt"; exit 3; fi
git diff --check | tee "$OUT/diff-check.txt"
echo "
AVANÇAR
 approval=${
LEGAL_SEED_APPROVAL_ID
:-not-required}" | tee "$OUT/gate.txt"
Gate:
 proveniência, 
hash
, vigência, rejeições, 
idempotência
 e 
rollback
 demonstrados.
Fase 3 — Governação de parâmetros, regras e publicação
Prompt para 
Codex
:
 “Implementa tipos de imposto, regimes, parâmetros, rule sets, fontes, elegibilidade, obrigações, decisões de revisão e evidências de testes. Usa 
workflow
 de quatro olhos, promoção atómica e imutabilidade após publicação. Implementa um avaliador de expressões com lista permitida; proíbe 
eval
 e execução arbitrária. A publicação deve falhar sem fonte, revisão técnica, revisão jurídica e testes críticos aprovados.”
Script — 
scripts/
codex
/fase-3-regras.sh
:
#!/usr/bin/env 
bash
set -
Eeuo
 
pipefail
PHASE
=3; OUT="
artifacts
/fase-$
PHASE
"; 
mkdir
 -p "$OUT"
test
 -f 
artisan
 || 
{ 
echo
 'BLOQUEAR: Laravel não detectado' | tee "$OUT/gate.txt"; exit 2; }
php
 
artisan
 
migrate
 --
env
=
testing
 2>&1 | tee "$OUT/migrate.txt"
php
 
artisan
 
test
 --
filter
='
Rule|Parameter|Eligibility|Publication|Review
' 2>&1 | tee "$OUT/domain-tests.txt"
php
 
artisan
 
test
 --
filter
='RULE_01|RULE_02|RULE_03|SEC_02|PUB_01|IMM_01|TMP_02' 2>&1 | tee "$OUT/gate-tests.txt"
grep
 -
RInE
 '\
beval
\s*\(|
shell_exec|proc_open|passthru
' app 2>
/
dev
/
null
 | tee "$OUT/forbidden-code.txt" || 
true
test
 
! 
-s "$OUT/forbidden-code.txt
" || {
 
echo
 'BLOQUEAR: execução potencialmente arbitrária detectada' | tee "$OUT/gate.txt"; exit 3; 
}
if
 
test
 -x 
vendor
/bin/
phpstan
; 
then
 
vendor
/bin/
phpstan
 
analyse
 app --error-
format
=
table
 2>&1 | tee "$OUT/phpstan.txt"; 
elif
 
test
 -x 
vendor
/bin/
psalm
; 
then
 
vendor
/bin/
psalm
 2>&1 | tee "$OUT/psalm.txt"; 
else
 
echo
 'BLOQUEAR: análise estática não configurada' | tee "$OUT/gate.txt"; exit 2; 
fi
git
 
diff
 --
check
 | tee "$OUT/diff-check.txt"
test
 -n "${
RULE_APPROVAL_ID
:-}" || { 
echo
 'CORRIGIR: aprovação do 
workflow
 ausente' | tee "$OUT/gate.txt"; exit 3; }
echo
 "AVANÇAR 
approval
=${
RULE_APPROVAL_ID
}"
 | tee "$OUT/gate.txt"
Rollback
:
 corrigir por nova versão de regra; nunca alterar ou eliminar uma versão publicada.
Fase 4 — API, segurança, privacidade e formulário React
Prompt para 
Codex
:
 “Implementa a API conforme o 
OpenAPI
 aprovado e o /Simulador em React/Next.js com JSON 
Schema
 
versionado
. Usa dropdown pesquisável para todo campo com mais de duas opções; suporta 
multivalor
 por teclado; limpa filhos inválidos 
em dependências; ‘Outro’ abre campo condicional; não define 
defaults
 fiscais. Implementa 
JWT
/scopes, 
RBAC
, 
RLS
, 
token
 anónimo apenas como SHA-256, 
ETag
, 
idempotência
, 
autosave
, 
loading
/erro, validação cliente/servidor, retenção e 
logs
 sem 
PII
.”
Script — 
scripts/
codex
/fase-4-api-ui.sh
:
#!/usr/bin/env 
bash
set -
Eeuo
 
pipefail
PHASE
=4; OUT="
artifacts
/fase-$
PHASE
"; 
mkdir
 -p "$OUT"
test
 -f 
composer.
lock
 || { 
echo
 'BLOQUEAR:
 
composer
.lock
 ausente' | tee "$OUT/gate.txt"; exit 2; }
test
 -f package-
lock.json
 || { 
echo
 'BLOQUEAR: package-
lock.json
 ausente' | tee "$OUT/gate.txt"; exit 2; }
composer
 
install
 --no-
interaction
 --
prefer-dist
npm
 ci
php
 
artisan
 
test
 --
filter
='
Auth|Anonymous|Rls|Simulation|Idempotency|Etag
' 2>&1 | tee "$OUT/api-tests.txt
"
npm
 
run
 
lint
 
2>&1 | tee "$OUT/lint.txt
"
npm
 
run
 
typecheck
 
2>&1 | tee "$OUT/typecheck.txt
"
npm
 
test
 --
 --
runInBand
 2>&
1 | tee "$OUT/ui-tests.txt
"
npm
 
run
 test:e2e
 2>&1 | tee "$OUT/
e2e.txt"
npm
 
run
 test:a11y 2>&1 | tee "$OUT/a11y.txt"
npm
 
run
 
build
 2>&1 | tee "$OUT/
build.txt
"
grep
 -
RInE
 '(tax|rate|iva|irpc|irps|ispc).{0,30}(defaultValue|initialValue)' app 
resources
 
src
 
pages
 2>/
dev
/
null
 | tee "$OUT/default-fiscal-scan.txt" || 
true
test
 
! 
-s "$OUT/default-fiscal-scan.txt
" || {
 
echo
 
'BLOQUEAR:
 possíveis 
defaults
 fiscais' | tee "$OUT/gate.txt"; exit 3; 
}
git
 
diff
 --
check
 | tee "$OUT/diff-check.txt"
echo
 'AVANÇAR
:
 API
, UI, E2E
 e 
acessibilidade aprovados'
 | tee "$OUT/gate.txt"
Testes mínimos:
 
Playwright
/
Cypress
 para jornada, axe para acessibilidade, testes de contrato, falha de rede, sessão expirada, dependências de dropdown e reenvio 
idempotente
.
Fase 5 — Motor fiscal principal e explicabilidade
Prompt para 
Codex
:
 “Implementa o motor determinístico para IRPC, IVA, ISPC, IRPS sobre remunerações, INSS e retenções, limitado ao âmbito fiscal aprovado. Carrega apenas regras publicadas e vigentes, resolve dependências sem ciclos, usa Decimal e arredondamento configurado e persiste instantâneos de fórmula, parâmetros, pressupostos e fontes na mesma transacção. Não implementes imposto do selo, impostos autárquicos, mais-valias, preços de transferência, convenções completas, benefícios complexos ZEE/ZFI ou regimes sectoriais.”
Script — 
scripts/
codex
/fase-5-motor-fiscal.sh
:
#!/usr/bin/env 
bash
set -
Eeuo
 
pipefail
PHASE
=5; OUT="
artifacts
/fase-$
PHASE
"; 
mkdir
 -p "$OUT"
test
 -f 
artisan
 || 
{ 
echo
 'BLOQUEAR: Laravel não detectado' | tee "$OUT/gate.txt"; exit 
2
; }
php
 
artisan
 
test
 --
filter
='
IRPC|IVA|ISPC|IRPS|INSS|Withholding
' 2>&1 | tee "$OUT/formula-tests.txt"
php
 
artisan
 
test
 --
filter
='TX_01|TMP_01|RND_01|ZERO_01|PREC_01|RULE_02|RULE_03' 
2>&1 | tee "$OUT/critical-tests.txt"
php
 
artisan
 
list
 --
raw
 | 
grep
 -q '^
simulator:golden-cases
'
 || { 
echo
 'BLOQUEAR: executor de casos dourados ausente' | tee "$OUT/gate.txt"; exit 2; }
php
 
artisan
 
simulator:golden-cases
 --
fail-on-diff
 2>&
1 | tee "$OUT/golden-cases.txt
"
grep
 -
RInE
 '(IRPC|IVA|ISPC|IRPS|INSS).{0,30}[=:][[:space:]]*[0-9]+([.,][0-9]+)?' app 
config
 2>/
dev
/
null
 | tee "$OUT/hardcoded-rate-scan.txt" || 
true
test
 
! 
-s "$OUT/hardcoded-rate-scan.txt
" || {
 
echo
 
'BLOQUEAR
: possíveis taxas codificadas' | tee "$OUT/gate.txt"; exit 3; 
}
test
 -n "${
FISCAL_APPROVAL_ID
:-}" && 
test
 -n "${
LEGAL_APPROVAL_ID
:-}" || { 
echo
 'BLOQUEAR: aprovações fiscal e jurídica ausentes' | tee "$OUT/gate.txt"; exit 3; }
git
 
diff
 --
check
 | tee "$OUT/diff-check.txt"
echo
 
"AVANÇAR fiscal=${
FISCAL_APPROVAL_ID
} legal=${
LEGAL_APPROVAL_ID
}"
 | tee "$OUT/gate.txt"
Gate:
 exactidão, vigência, precisão, atomicidade, explicabilidade e fontes reconciliadas.
Fase 6 — Aduanas, câmbios, cenários e calendário
Prompt para 
Codex
:
 “Implementa valor aduaneiro, direitos, ICE, IVA de importação, moedas, origem e preferências; exige código pautal e prova válida para taxa preferencial. Adiciona cenários optimista, base e conservador, obrigações fiscais/cambiais, vencimentos, feriados e jobs persistidos com 
retries
 
idempotentes
 e 
dead-letter
. Preserva valor original, moeda, taxa, data e fonte e separa obrigações cambiais de impostos.”
Script — 
scripts/
codex
/fase-6-aduanas-obrigacoes.sh
:
#!/usr/bin/env 
bash
set -
Eeuo
 
pipefail
PHASE
=6; OUT="
artifacts
/fase-$
PHASE
"; 
mkdir
 -p "$OUT"
test
 -f 
artisan
 || 
{ 
echo
 'BLOQUEAR: Laravel não detectado' | tee "$OUT/gate.txt"; exit 2; }
php
 
artisan
 
test
 --filter='Customs|Tariff|Excise|ImportVat|Currency|Scenario|Obligation|Calendar|Job' 2>&1 | tee "$OUT/domain-tests.txt"
php
 
artisan
 
test
 --filter='ADU_01|ADU_02|ADU_03|ADU_04|ADU_05|ICE|IMP_IVA|CUR_01|CON_01|JOB_01' 2>&1 | tee "$OUT/gate-tests.txt"
php
 
artisan
 
list
 --
raw
 | 
grep
 -q '^
simulator:reconcile-calendar
'
 || { 
echo
 'BLOQUEAR: reconciliador de calendário ausente' | tee "$OUT/gate.txt"; exit 2; }
php
 
artisan
 
simulator:reconcile-calendar
 --
formats
=
screen,json,pdf
 2>&1 | tee "$OUT/calendar-reconciliation.txt
"
git
 
diff
 --
check
 | tee "$OUT/diff-check.txt"
echo
 'AVANÇAR
: aduanas, cenários, jobs
 e 
calendário 
reconciliados'
 | tee "$OUT/gate.txt"
Rollback
:
 desactivar a versão não aprovada por configuração e reverter apenas o 
commit
/migração da fase.
Fase 7 — Relatórios, qualidade integral e homologação
Prompt para 
Codex
:
 “Integra a jornada /Simulador, explicações, fontes, obrigações e relatórios PDF/JSON. Garante 
URLs
 assinadas apenas ao proprietário e reconciliação 
com o 
snapshot
 persistido. Executa testes unitários, integração, contrato, segurança, 
RLS
, concorrência, transacções, desempenho, acessibilidade, resiliência, retenção, backup/restauro e E2E-01. 
Não
 marques testes 
ignorados
 
ou
 
instáveis
 
como
 
aprovados
.”
Script — 
scripts/codex/fase-7-qualidade.sh
:
#!/usr/bin/env bash
set -
Eeuo
 
pipefail
PHASE=7; OUT="artifacts/
fase
-$PHASE"; 
mkdir
 -p "$OUT"
test -f artisan || { echo '
BLOQUEAR
: Laravel 
não
 
detectado
' | tee "$OUT/gate.txt"; exit 2; }
test -f 
package.json
 || { echo '
BLOQUEAR
: 
aplicação
 front-end 
não
 
detectada
' | tee "$OUT/gate.txt"; exit 2; }
test -x scripts/reconcile-reports.sh || { echo '
BLOQUEAR
: 
reconciliação
 de 
relatórios
 
ausente
' | tee "$OUT/gate.txt"; exit 2; }
test -x scripts/backup-restore-test.sh || { echo '
BLOQUEAR
: 
ensaio
 DR 
ausente
' | tee "$OUT/gate.txt"; exit 2; }
npm
 run | grep -q 'test:e2e' || { echo '
BLOQUEAR
: teste E2E 
ausente
' | tee "$OUT/gate.txt"; exit 2; }
npm
 run | grep -q 'test:a11y' || { echo '
BLOQUEAR
: teste de 
acessibilidade
 
ausente
' | tee "$OUT/gate.txt"; exit 2; }
php
 artisan test 2>&1 | tee "$OUT/php-tests.txt"
npm
 ci
npm
 test -- --
runInBand
 2>&1 | tee "$OUT/js-tests.txt"
npm
 run test:e2e 2>&1 | tee "$OUT/e2e.txt"
npm
 run test:a11y 2>&1 | tee "$OUT/a11y.txt"
scripts/reconcile-reports.sh 2>&1 | tee "$OUT/report-reconciliation.txt"
scripts/backup-restore-test.sh 2>&1 | tee "$OUT/dr-test.txt"
test -n "${
HOMOLOGATION_APPROVAL_ID
:-}" || { echo '
BLOQUEAR
: 
homologação
 
assinada
 
ausente
' | tee "$OUT/gate.txt"; exit 3; }
git diff --check | tee "$OUT/diff-check.txt"
echo "
AVANÇAR
 approval=${
HOMOLOGATION_APPROVAL_ID
}" | tee "$OUT/gate.txt"
Evidências:
 cobertura, resultados por ID, reconciliação PDF/JSON/API/base, vulnerabilidades, acessibilidade, 
RTO
/
RPO
 e acta de homologação.
Fase 8 — 
Go
-Live, estabilização e actualização contínua
Prompt para 
Codex
:
 “Calcula o gate a partir de evidências reais. Não faça 
deploy
 se existir teste crítico falhado, cobertura inferior a 95%, vulnerabilidade crítica/alta sem excepção válida, divergência de relatório, regra sem fonte, sobreposição temporal ou 
rollback
/DR não demonstrado. Com aprovação humana, prepara 
release
 imutável, backup, migração, 
smoke
 
tests
, observabilidade, implantação gradual e reversão automática. Não publiques parâmetros não aprovados.”
Script — 
scripts/
codex
/fase-8-release.sh
:
#!/usr/bin/env 
bash
set -
Eeuo
 
pipefail
PHASE
=8; OUT="
artifacts
/fase-$
PHASE
"; 
mkdir
 -p "$OUT"
test
 "${
GO_APPROVED
:-false}" = 
true
 || { 
echo
 'BLOQUEAR: 
GO_APPROVED
=
true
 ausente' | tee "$OUT/gate.txt"; exit 2; }
test
 -n "${
GO_DECISION_ID
:-}" && 
test
 -n "${GO_EVIDENCE_SHA256:-}" || { 
echo
 'BLOQUEAR: decisão ou checksum das evidências ausente' | tee "$OUT/gate.txt"; exit 2; }
git
 
diff
 --
quiet
 || { 
echo
 'BLOQUEAR: árvore de trabalho alterada' | tee "$OUT/gate.txt"; exit 2; }
TAG="${
RELEASE_TAG
:-}"; 
test
 -n "$TAG" || { 
echo
 'BLOQUEAR: 
RELEASE_TAG
 ausente' | tee "$OUT/gate.txt"; exit 2; }
git
 
rev
-parse 
-q --
verify
 "
refs
/
tags
/$TAG" >/
dev
/
null
 || { 
echo
 'BLOQUEAR: 
tag
 inexistente' | tee "$OUT/gate.txt"; exit 2; }
test
 "$(
git
 
rev-list
 -n1 "$TAG")" = "$(
git
 
rev
-parse 
HEAD
)" || { 
echo
 'BLOQUEAR: 
tag
 não aponta para o 
commit
 aprovado' | tee "$OUT/gate.txt"; exit 2; }
for s in backup.sh deploy.sh smoke-test.sh rollback.sh; do 
test
 -x "scripts/$s" || { 
echo
 "BLOQUEAR: scripts/$s ausente" | tee "$OUT/gate.txt"; exit 2; }; 
done
printf
 
'
decision
=%s\
nevidence
=%s\
ncommit
=%s\
ntag
=%
s\n' "$
GO_DECISION_ID
" "$GO_EVIDENCE_SHA256" "$(
git
 
rev
-parse 
HEAD
)" "$
TAG" | tee "$OUT/release-
manifest.txt"
scripts
/backup.sh 2>&1 | tee "$OUT/backup.txt"
scripts/deploy.sh --
release
 "$TAG" 2>&1 | tee "$OUT/deploy.txt"
test
 -x scripts/check-migrations.sh && scripts/check-migrations.sh 2>&1 | tee "$OUT/migrations.txt" || { 
echo
 'BLOQUEAR: verificação de migrações ausente ou falhou' | tee "$OUT/gate.txt"; scripts/rollback.sh --
release
 "$TAG"; exit 4; }
if
 !
 scripts/smoke-test.sh 2>&1 | tee "$OUT/smoke.txt"; 
then
 scripts/rollback.sh --
release
 "$TAG" 2>&1 | tee "$OUT/rollback.txt"; 
echo
 'BLOQUEAR: 
smoke
 
test
 falhou; 
rollback
 executado' | tee "$OUT/gate.txt"; exit 5; fi
echo
 'AVANÇAR para 
hypercare
 e monitorização reforçada' | tee "$OUT/gate.txt"
Nota:
 os nomes 
backup.sh
, 
deploy.sh
, 
smoke-test.sh
 e 
rollback.sh
 são interfaces esperadas; o 
Codex
 deve ligá-las ao mecanismo real de entrega do projecto, sem criar 
deploy
 fictício.
17.2 Manifesto e comando mestre
Ficheiro sugerido — 
scripts/
codex
/run-phase.sh
:
#!/usr/bin/env 
bash
set -
Eeuo
 
pipefail
PHASE
="${1:-}"
case "$
PHASE
" in 0|1|2|3|4|5|6|7|8) ;; *) 
echo
 'Uso: scripts/codex/run-phase.sh {0..8}'; exit 64;; 
esac
SCRIPT=$(
find
 scripts/
codex
 -
maxdepth
 1 -
type
 f -
name
 "fase-$
PHASE
-*.
sh
" | 
head
 -n1)
test
 -n "$SCRIPT" || { 
echo
 "Script da Fase $
PHASE
 não encontrado"; exit 66; }
PREV
=$((PHASE-1))
if
 
test
 "$
PHASE
" -
gt
 0; 
then
 
GATE="
artifacts
/fase-$
PREV
/gate.txt"; 
test
 -f "$GATE" || { 
echo
 "BLOQUEAR: gate da Fase $
PREV
 ausente"; exit 65; }; 
grep
 -q '^AVANÇAR' "$GATE" || { 
echo
 "BLOQUEAR: Fase $
PREV
 sem AVANÇAR"; exit 65; }; 
grep
 -q '
approval
=' "$GATE" || { 
echo
 "BLOQUEAR: aprovação identificada da Fase $
PREV
 ausente"; exit 65; }; fi
bash
 "$SCRIPT"
Prompt mestre para 
Codex
:
 “Executa uma única fase por vez. Antes de alterar, apresenta plano e ficheiros exactos. Lê o gate anterior, inspecciona o repositório e adapta o script às ferramentas reais. Não simules comandos nem resultados. Mantém alterações pequenas, reversíveis e cobertas por testes. Se um requisito, fonte, aprovação, segredo, serviço ou ferramenta necessária estiver indisponível, pára e regista BLOQUEAR. No final, entrega resumo, 
diff
 lógico, comandos efectivamente executados, evidências, riscos, 
rollback
 e recomendação de gate. Nunca avances automaticamente para a fase seguinte.”
17.3 Matriz consolidada de pré-condições, gates e 
rollback
Fase
Pré-condições obrigatórias
Gate verificável
Rollback
0
Git
, documentação e intervenientes disponíveis.
Artefactos completos, sem marcadores pendentes, com 
GOVERNANCE_APPROVAL_ID
.
Reverter apenas documentos e 
commit
 da fase.
1
Gate 0; árvore limpa; 
APP_ENV
=
testing
; base descartável; 
OpenAPI
 integral.
SQL-01/02 e OAS-01/02 aprovados; 
TECHNICAL_APPROVAL_ID
 registado.
Reverter novas migrações e 
commits
; nunca editar migrações de produção.
2
DDL
 válido; fontes oficiais; importador e reconciliador disponíveis.
Proveniência, vigência, 
hashes
 e reconciliação aprovados; 
seeds
 publicados autorizados.
Reverter migrações e cargas de teste; preservar fontes e versões publicadas.
3
Repositório legislativo; 
workflow
; avaliador restrito; análise estática.
RULE-01–03, SEC-02, PUB-01, IMM-01 e TMP-02 
aprovados
; 
RULE_APPROVAL_ID
.
Corrigir por nova versão; nunca alterar conteúdo publicado.
4
OpenAPI
, IAM, catálogos, JSON 
Schema
, 
lockfiles
 e política de privacidade.
API, 
lint
, 
typecheck
, UI, E2E, acessibilidade, 
build
 e ausência de 
defaults
 fiscais.
Feature
 
flag
, reversão do 
commit
/migrações novas e preservação dos rascunhos.
5
Rule set publicado; parâmetros e fórmulas validados; casos dourados disponíveis.
Testes críticos e casos dourados aprovados; 
FISCAL_APPROVAL_ID
 e 
LEGAL_APPROVAL_ID
.
Desactivar rule set não aprovado, reverter código e 
criar nova
 versão para correcções.
6
Pauta, origem, câmbio, normas cambiais, jobs e calendário disponíveis.
Testes aduaneiros/cambiais e reconciliação obrigatória entre ecrã, JSON e PDF.
Desactivar versão, cancelar jobs 
auditavelmente
 e preservar históricos.
7
API, UI, motores, conteúdos, E2E, acessibilidade, 
reconciliação e DR implementados.
100% críticos, ≥95% total, relatórios reconciliados, DR aprovado e 
HOMOLOGATION_APPROVAL_ID
.
Não promover; restaurar homologação e repetir testes 
afectados e regressão.
8
Gate 7; 
GO_DECISION_ID
; checksum das evidências; 
tag
 imutável; scripts operacionais.
Backup, migrações, 
deploy
 e 
smoke
 
test
 aprovados; observabilidade e suporte activos.
Rollback
 automático, restauração quando necessária e reactivação da versão estável.
18. Formulário integrado de simulação e manifestação de investimento ou negócio
18.0 
Componente da Fase 4
 — Formulário React com 
dropdowns
Objectivo:
 entregar o 
/Simulador
 acessível, responsivo e fiel aos catálogos.
Pré-condições:
 endpoints de catálogo e API estáveis; contrato e desenho de campos aprovados.
Prompt para 
Codex
:
 
“Antes de actuar, inspecciona o repositório real e identifica Laravel, React/Next.js, PostgreSQL/
PostGIS
, 
OpenAPI
, CI, testes, versões, estrutura, convenções e restrições. Não assumes nomes nem caminhos: adapta-os ao projecto. Reutiliza padrões existentes e apresenta primeiro um plano curto e a lista exacta de ficheiros a criar ou alterar. Não apagues, renomeies ou reescrevas artefactos sem necessidade demonstrada; não edites migrations já executadas em produção; não inventes taxas ou regras fiscais. 
Executa o componente da Fase 4
 — Formulário React com 
dropdowns
. Implementa /Simulador em React/Next.js segundo os padrões existentes. Todo campo com 
mais de duas opções
 usa dropdown pesquisável e acessível; campos 
multivalor
 permitem selecção e remoção por teclado. Não definas 
defaults
 fiscais. 
Dropdowns
 dependentes limpam filhos inválidos; ‘Outro’ abre campo condicional. Implementa 
autosave
, validações cliente/servidor, estados de erro/
loading
, experiência móvel e 
WCAG
. Implementa apenas este escopo. Mantém alterações não destrutivas e reversíveis, validação cliente/servidor quando aplicável, transacções, 
idempotência
, 
optimistic
 
locking
, 
RLS
, 
snapshots
 e 
logs
 sem 
PII
 co
nforme as decisões já aprovadas. Executa os testes adequados e corrige os erros encontrados apenas dentro deste escopo. Se uma pré-condição ou 
gate falhar
, pára e regista o bloqueio. Não prossigas para a etapa seguinte. No fim, entrega: resumo; 
diff
 lógico por ficheiro; comandos executados; resultados e evidências dos testes; riscos e pendências; instruções de 
rollback
; estado proposto do gate para revisão humana. Não afirmes ter executado comandos que não executaste.”
Critérios de conclusão:
 testes de interface, teclado e leitor de ecrã definidos e 
verificados; dependências, 
autosave
 e validação aprovados; ausência de 
defaults
 fiscais.
18.0.1 Finalidade e modalidades de utilização
Modalidades do formulário integrado
Modalidade
Descrição
Resultado
Simulação anónima
Recolhe apenas dados económicos essenciais, sem identificação pessoal obrigatória.
Resultado fiscal indicativo; gravação temporária por 
token
 ou autenticação para continuar.
Simulação autenticada
Associa a simulação ao perfil do investidor ou entidade existente.
Simulação persistente, cenários, relatório e histórico.
Manifestação formal
O utilizador escolhe “Transformar em manifestação”, confirma os dados reutilizados e completa identificação, contactos, documentos e declaração.
Processo de investimento ou negócio com referência, estado, responsável e acompanhamento no 
InvestMoz
.
O formulário serve simultaneamente à simulação fiscal e, mediante 
consentimento explícito, separado, 
versionado
 e revogável quando aplicável
, à criação de uma Manifestação de Interesse de Investimento ou de uma Manifestação de Oportunidade de Negócio. A simulação mantém natureza informativa; a manifestação é formal, exige autenticação, validação documental e acompanhamento.
Estrutura integrada por etapa
Etapa
Campos principais
Regras e ligações
1. Finalidade
Objectivo; tipo de manifestação; origem; idioma preferido.
Controla o percurso e o módulo de destino. 
Chaves: purpose, 
manifestation_type
, 
entry_source
, 
source_id
, 
preferred_language
.
2. Perfil do promotor
Tipo de pessoa; origem; residência fiscal; fase da entidade; forma jurídica; perfil; NUIT; confirmação do perfil.
Pré-preencher dados autorizados sem actualizar o cadastro mestre sem confirmação separada.
3. Identificação e contactos
Nome/denominação; registo; representante; e-mail verificado; telefone; endereço; canal preferido.
Obrigatório apenas na manifestação; dados pessoais separados dos económicos.
4. Projecto ou negócio
Título; resumo; tipo; sector; actividade; produtos/serviços; maturidade; início; duração; projecto existente.
Cria ou liga projecto/oportunidade; título e resumo formam a ficha inicial; pesquisar duplicados.
5. Localização
Província, distrito, localidade; local conhecido; coordenadas; área; situação do terreno; ZEE/ZFI; infra-estruturas.
Usa catálogo mestre/
PostGIS
; 
dropdowns
 dependentes; benefício exige certificado.
6. Estrutura financeira
Moeda; investimento total; capital; dívida nacional/externa; subvenções; montante mobilizado e procurado; países de origem; receitas, custos, lucro; prazo.
Valores não negativos; fontes reconciliam com o total; lucro reconciliado.
7. Emprego e impacto
Empregos directos/indirectos; nacionais/estrangeiros; competências; conteúdo local; exportações; substituição de importações; ambiente; comunidade.
Alimenta impacto e priorização sem alterar cálculos fiscais não relacionados.
8. Operação fiscal
Vendas tributadas, isentas, taxa zero e exportações; custos; prejuízos; 
payroll
; pagamentos externos; importações; benefícios; data de referência.
Enviado ao motor fiscal; benefícios permanecem “a validar” sem elegibilidade e prova.
9. Necessidade de negócio
Oferta/procura; tipo de parceiro; descrição; valor/moeda; condições; prazo; confidencialidade; pedido de publicação.
Cria oportunidade ligada; publicação nunca automática; campos sensíveis não são públicos.
10. Documentos
Identificação; registo/NUIT; perfil; plano/estudo; prova de fundos; certificado; licenças; mapa.
Tipo, 
hash
, versão, validade, antivírus, confidencialidade e verificação obrigatórios.
11. Consentimentos
Termos; veracidade; reutilização; contacto; publicação.
Consentimentos separados, versionados e revogáveis; publicação não presumida.
12. Revisão e submissão
Resumo; lacunas; resultado fiscal; riscos; pré-visualização pública/privada; declaração final.
Guardar, validar, submeter ou regressar; submissão gera referência e versão imutável.
18.0.2 Regras de campos, 
dropdowns
 e validação
Todo campo com 
mais de duas opções
 usa dropdown pesquisável e acessível; campos 
multivalor
 suportam selecção e remoção por teclado.
Usar catálogos oficiais para países, moedas ISO 4217, formas jurídicas, sectores, actividades, geografia, ZEE/ZFI, maturidade, documentos, confidencialidade e estados; o utilizador não precisa conhecer códigos.
Dropdowns
 dependentes limpam automaticamente valores filhos inválidos; a opção “Outro” abre campo condicional; não existem 
defaults
 fiscais.
Chaves estáveis devem ser usadas no 
front-end
, API, base, testes e relatórios, incluindo 
purpose
, 
promoter
.*
, 
identity
.*
, 
contact
.*
, 
project
.*
, 
location
.*
, 
financial.*
, 
impact
.*
, 
tax
.*
, 
opportunity
.*
, 
consents.*
 e 
review
.*.
Campos obrigatórios condicionais são activados apenas pelas respostas aplicáveis; validação no campo e no servidor indica como corrigir o erro.
Valores monetários guardam valor, moeda, taxa, data e fonte; fontes financeiras, empregos e lucro devem reconciliar ou gerar aviso.
Autosave
 usa 
optimistic
 
locking
/
ETag
 e 
idempotência
; a versão submetida é imutável; 
logs
 não contêm 
PII
.
Pré-preenchimento exige confirmação por grupo e não altera dados mestre sem confirmação separada.
18.0.3 Ligações com o 
InvestMoz
 e fluxo de conversão
Ligações e propriedade dos dados
Fonte
Destino
Regra
Conta/IAM
Manifestação
owner_user_id
 identifica o proprietário; autenticação obrigatória para submissão formal.
Perfil do investidor
Manifestação
investor_profile_id
 referencia o mestre; a manifestação guarda 
snapshot
 do apresentado.
Simulação
Manifestação
simulation_id
 liga o cenário; resultado preservado por 
rule_set
, data e 
hash
.
Manifestação
Projecto
investment_project_id
 é criado após triagem favorável ou ligado sem duplicação.
Manifestação
Oportunidade
business_opportunity_id
 é criado para procura/oferta; publicação exige aprovação e consentimento.
Manifestação
CRM
crm_case_id
 acompanha responsável, notas, tarefas e follow-up sem duplicar detalhe fiscal.
Localização
Mapa/
PostGIS
jurisdiction_id
 e geometria opcional suportam pesquisa e regras territoriais.
Documentos
Gestão documental
document_id
 aponta para armazenamento seguro e respeita confidencialidade.
Manifestação
Notificações
Submissão, pedidos, decisões e prazos geram eventos no portal e canais autorizados.
O utilizador inicia em /Simulador ou a partir de projecto/oportunidade e confirma os dados pré-preenchidos.
O motor valida e calcula; o resultado recebe 
simulation_id
, versão das regras, data e 
hash
.
Após o resultado, a interface oferece Guardar, Criar cenários e Manifestar interesse.
Ao manifestar interesse, o utilizador autentica-se, selecciona o cenário e autoriza a reutilização.
O sistema cria rascunho com 
simulation_id
 e 
snapshot
 e solicita apenas dados e documentos ausentes.
A validação identifica obrigatoriedade, documentos, divergências, duplicados possíveis e campos públicos.
A submissão gera referência, 
timestamp
, checksum e versão imutável e abre caso CRM via 
outbox
.
O analista verifica identidade, completude, enquadramento, duplicação e viabilidade preliminar.
Após aprovação, a manifestação liga ou cria projecto e, quando aplicável, oportunidade publicável.
Alterações posteriores 
criam nova
 versão; a simulação original nunca é sobrescrita.
Estados
 
autorizados
:
 draft → 
validation_pending
 → submitted → 
under_screening
 → 
information_requested
 → 
under_assessment
 → 
approved_for_facilitation
 | 
converted_to_project
 | 
converted_to_opportunity
 | rejected | withdrawn | archived. 
Cada transição valida o estado esperado e regista actor, data, motivo, anexos e mensagem pública; notas internas não são expostas ao promotor.
18.0.4 Extensão do modelo de dados
Entidades adicionais
Entidade
Campos e restrições principais
investment_manifestations
id, 
reference_no
, 
owner_user_id
, 
investor_profile_id
, 
simulation_id
, 
manifestation_type
, purpose, title, summary, status, confidentiality, 
lock_version
, 
current_version
, 
submitted_at
, 
assigned_team_id
, 
deleted_at
.
manifestation_versions
manifestation_id
, 
version_no
, 
data_snapshot
, 
public_snapshot
, checksum, 
created_by
, submitted; 
UNIQUE(
manifestation_id
, 
version_no
); 
imutável
 
quando
 
submetida
.
manifestation_contacts
Tipo, nome, e-mail, telefone, endereço, principal, verificação; cifragem quando aplicável.
manifestation_locations
jurisdiction_id
, geometry, 
site_known
, 
land_status
, 
área
/
unidade
, 
special_zone_id
, 
infrastructure_needs
.
manifestation_financials
Moeda, total, capital, dívidas, subvenções, mobilizado, procurado, receitas, custos e lucro; valores ≥ 0 e reconciliação configurável.
manifestation_impacts
Empregos, nacionais/estrangeiros, exportações, substituição de importações, conteúdo local, competências e ambiente.
business_opportunities
manifestation_id
, 
created_from_version_id
, tipo, oferta/procura, título, descrição, valor, moeda, prazo, publicação, confidencialidade e 
public_snapshot
.
manifestation_documents
manifestation_id
, 
version_id
, tipo, 
object_key
, 
hash
, MIME, tamanho, validade, confidencialidade, verificação e antivírus.
manifestation_consents
Tipo, versão dos termos, 
granted
, 
granted_at
, 
revoked_at
, 
evidence_hash
 e 
ip_hash
; unicidade por tipo e versão.
assignments
, requests e 
tasks
Atribuição principal activa única; pedidos com itens/prazo/resposta; tarefas com prioridade, estado e 
external_id
 CRM opcional.
manifestation_status_history
from_status
, 
to_status
, 
actor_id
, 
reason_code
, notes, 
occurred_at
; 
trilho
 
imutável
.
manifestation_links
 e 
integration_outbox
Referências a projecto, oportunidade e CRM; eventos com payload, estado, tentativas e 
idempotency_key
 única.
Uma simulação pode originar manifestações distintas apenas quando tipo/finalidade diferirem; 
idempotência
 impede duplicação do mesmo pedido.
Cada manifestação possui múltiplas versões, documentos, tarefas, pedidos, consentimentos e eventos.
Respostas a pedidos de informação 
criam nova
 versão, preservando todas as anteriores.
Projecto, oportunidade, perfil e CRM continuam dados mestre externos; apenas 
snapshots
 de prova são preservados.
RLS
 limita acesso ao proprietário, equipa atribuída e supervisores; campos confidenciais exigem permissão adicional.
18.0.5 Endpoints adicionais
Gate técnico da extensão de manifestações:
 as entidades, restrições, políticas 
RLS
, máquina de estados, 
snapshots
, consentimentos, documentos, 
outbox
 e endpoints descritos nesta secção são requisitos de desenho até serem incorporados no 
DDL
 executável, nas migrações Laravel e no 
OpenAPI
 3.1 integral. A extensão permanece 
No-Go
 enquanto as migrações não executarem 
up
 e 
down
 numa base vazia, os contratos não passarem no 
parser
 e nos testes positivos e negativos, e a reconciliação campo a campo entre formulário, 
schema
, API, modelos e tabelas não estiver concluída.
API de manifestações
Método e rota
Uso e controlo
POST /api/v1/
simulations/{id}/
manifestations
Cria rascunho a partir de cenário concluído; 
JWT
, 
Idempotency-Key
, consentimento, propriedade e 
snapshot
.
POST /api/v1/
manifestations
Criação directa autenticada, sem submissão; pode invocar o simulador depois.
GET /api/v1/
manifestations/{id}/
schema
Devolve etapas, campos, 
enums
, condições, documentos e versão do 
schema
.
GET /api/v1/
manifestations/{
id}
Dados, completude, validação, versão, estado, atribuição, 
tarefas, pedidos, ligações e 
timeline
; filtrado por 
RLS
.
PATCH
 /api/v1/
manifestations
/{id}
Merge-patch
 com 
If
-Match; apenas draft ou 
information_requested
; devolve novo 
ETag
.
POST /api/v1/
manifestations/{id}/
validate
Valida campos, documentos, reconciliações, 
malware
, consentimentos e pré-visualização pública sem submeter.
POST /api/v1/
manifestations/{id}/
documents/uploads e /complete
URL temporária, lista branca, limites, 
hash
, antivírus e confidencialidade; submissão bloqueada até aprovação.
POST /api/v1/
manifestations/{id}/
submit
Idempotente
; gera referência, versão, checksum, histórico e 
outbox
 CRM/notificação numa transacção.
GET
 /api/v1/me/
manifestations
 e /{id}/
timeline
Lista paginada, próxima acção e eventos públicos; nunca devolve notas internas.
POST /api/v1/
manifestations/{id}/requests/{
request_
id
}/
respond
Fecha pedido e 
cria nova
 versão numa transacção.
POST /api/v1/admin/
manifestations/{id}/
assign, /transition e /information-requests
RBAC
, 
If
-Match, máquina de estados, razão, auditoria, tarefa e notificação.
POST /api/v1/admin/
manifestations/{id}/
convert/project e /convert/opportunity
Conversão 
idempotente
; verifica duplicados; publicação separada e sujeita a consentimento e aprovação.
18.0.6 Experiência, acompanhamento, segurança e aceitação
Apresentar barra de progresso, percentagem de completude, 
autosave
, resumo por etapa, obrigatoriedade e próxima acção única e accionável.
O painel do investidor mostra referência, título, tipo, estado, submissão, responsável institucional, última actualização, 
timeline
 pública, pedidos, documentos e ligação à simulação exacta.
Documentos exibem recebido, em verificação, válido, rejeitado ou expirado, com motivo e opção de substituição.
Mensagens usam canal seguro do processo; correio electrónico apenas notifica e remete ao portal.
Submissão gera recibo; atribuição cria tarefa; prazos em risco escalam; pedidos de informação têm lembretes; alterações de estado indicam fundamento público e próxima acção.
Nunca publicar nomes, contactos, documentos, valores confidenciais ou resultados fiscais sem consentimento explícito e aprovação.
Manter um dono por dado: identidade no Perfil, geografia no catálogo, simulação no módulo fiscal, processo na Manifestação e relacionamento no CRM.
Detectar possíveis duplicados por promotor, título, sector, localização e montante, sem bloquear automaticamente submissões legítimas.
Conversões e submissões são 
idempotentes
; repetição não cria manifestações, projectos ou 
oportunidades duplicados
.
O relatório da manifestação inclui referência, resumo, resultado fiscal associado, documentos, estado, próximos passos e contactos institucionais.
Critério 
Go
-Live
 do formulário fiscal
:
 testes de 
dropdowns
 e 
dependências, pré-preenchimento, 
acessibilidade, teclado, leitor de ecrã, 
experiência 
móvel, 
autosave
, 
validação cliente/servidor, ausência de 
defaults
 fiscais, 
rollback
, 
RLS
 e protecção de dados aprovados. Quando a extensão de manifestações integrar a 
release
 aprovada, acrescentam-se obrigatoriamente os testes de consentimento, reconciliação financeira, documentos, confidencialidade, máquina de estados, conversão, duplicação, 
outbox
, notificações
 e integração CRM
. Nenhum teste relativo a funcionalidade fora do escopo da 
release
 pode ser usado para declarar essa funcionalidade implementada.
Alinhamento dos percursos:
 as Fases 0–8 da Secção 17 representam a sequência macro de implementação; as Sprints 0–6 da Secção 16 representam a cadência temporal do MVP; as Etapas 1–12 da Secção 18 representam a jornada funcional do utilizador; e as Etapas 18.1–18.10 detalham apenas os dados necessários ao cálculo fiscal. As etapas funcionais não substituem as fases técnicas nem devem ser usadas como numeração de execução do projecto.
Finalidade do subformulário fiscal:
 as Etapas 18.1–18.10 detalham os campos económicos, fiscais, aduaneiros, laborais e cambiais usados pelo motor de simulação. Na jornada integrada de 12 etapas, estes campos são apresentados nos grupos correspondentes de Finalidade, Perfil do promotor, Projecto ou negócio, Localização, Estrutura financeira, Emprego e impacto, Operação fiscal, Consentimentos e Revisão e submissão. Campos de identificação, oportunidade de negócio, documentos e acompanhamento formal pertencem exclusivamente ao percurso de manifestação. Os campos 
obrigatórios devem ser validados antes do cálculo
; perguntas
 condicionais 
aparecem 
apenas 
quando 
aplicáveis
; e o utilizador pode
 guardar
, retomar, rever 
e 
corrigir 
o rascunho
 antes da 
validação ou 
submissão.
18.1 Etapa 1 — Configuração da simulação
Campo
Tipo de entrada
Obrigatório
Regra/validação
Data de referência
Data
Sim
Determina a legislação, parâmetros e taxas vigentes.
Período da simulação
Selecção: mensal, anual ou projecto
Sim
Compatível com as datas de início e fim.
Moeda principal
Lista ISO de moedas
Sim
Predefinição 
MZN
; moeda diferente exige taxa, data e fonte de câmbio.
Cenários
Selecção: único ou optimista/base/conservador
Sim
Três cenários devem indicar as variáveis alteradas.
Modo de utilização
Selecção: anónimo ou autenticado
Sim
No modo anónimo, emitir 
token
 seguro e informar prazo de retenção.
18.2 Etapa 2 — Perfil do contribuinte e do investidor
Campo
Tipo de entrada
Obrigatório
Regra/condição
Tipo de contribuinte
Selecção: pessoa singular, pessoa colectiva ou trabalhador por conta própria
Sim
Activa IRPS, IRPC, ISPC e obrigações correspondentes.
Origem do investidor
Selecção: nacional, estrangeiro ou misto
Sim
Capital estrangeiro activa perguntas cambiais.
Residência fiscal
País e estado de residência
Sim
País obrigatório; não presumir convenção de dupla tributação.
Estado do projecto
Selecção: empresa existente ou projecto a constituir
Sim
Projecto novo exige data prevista de constituição e início.
Forma jurídica
Lista configurável
Condicional
Obrigatória para pessoa colectiva ou projecto a constituir.
NUIT
Texto
Não
Validar formato quando preenchido; não expor em relatórios públicos.
Dimensão estimada
Selecção: pequeno contribuinte, PME ou grande empresa
Sim
Deve ser confirmada por critérios configuráveis, não apenas autodeclarada.
18.3 Etapa 3 — Actividade e localização
Campo
Tipo
Obrigatório
Regra/condição
Sector e actividade económica
Lista hierárquica com código
Sim
Seleccionar a classificação oficial e activar regras sectoriais.
Província
Lista
Sim
Filtra distritos.
Distrito
Lista dependente
Sim
Filtra localidades e autarquias.
Localidade/autarquia
Lista dependente
Condicional
Usada para impostos e obrigações locais quando aplicáveis.
Regime territorial especial
Selecção: nenhum, ZEE ou ZFI
Sim
Benefício não é aplicado apenas pela localização.
Certificado ZEE/ZFI
Número, entidade, emissão, validade e comprovativo
Condicional
Obrigatório para simular benefício confirmado; sem prova, apresentar apenas oportunidade a validar.
18.4 Etapa 4 — Estrutura do investimento e financiamento
Campo
Tipo
Obrigatório
Regra/validação
Montante total do investimento
Valor monetário
Sim
Maior que zero.
Capital próprio nacional
Valor monetário
Sim
Valor não negativo.
Capital próprio estrangeiro
Valor monetário
Sim
Se superior a zero, activar registo cambial.
Financiamento nacional
Valor, prazo e taxa
Não
Não negativo; indicar instituição quando aplicável.
Financiamento externo
Valor, moeda, país, prazo e taxa
Não
Activa obrigações cambiais e análise de pagamentos ao exterior.
Reconciliação de fontes
Campo calculado
Sim
A soma das fontes deve corresponder ao investimento; diferenças devem ser corrigidas ou justificadas.
Data prevista de início
Data
Sim
Não anterior à data de referência sem justificação.
Duração do projecto
Número de meses/anos
Sim
Maior que zero.
Activos por classe
Grelha repetível: classe, descrição, valor, origem e vida útil
Não
A soma pode ser reconciliada com o investimento total.
18.5 Etapa 5 — Operação, vendas e custos
Campo
Tipo
Obrigatório
Regra/uso
Volume de negócios previsto
Valor monetário por período
Sim
Usado na elegibilidade e comparação de regimes.
Vendas tributadas
Valor por categoria
Sim
Separar por taxa aplicável sem preencher a taxa no formulário.
Vendas isentas
Valor e natureza
Não
Exigir fundamento configurado ou marcar para validação.
Exportações/taxa zero
Valor e destino
Não
Manter separadas das vendas isentas.
Outros rendimentos
Grelha: natureza e valor
Não
Classificação fiscal obrigatória para cálculo definitivo.
Custos fiscalmente dedutíveis
Grelha por categoria
Sim
Valores não negativos; apresentar pressupostos.
Gastos não dedutíveis
Grelha por categoria
Não
Integram correcções positivas.
Prejuízos reportáveis
Valor, período de origem e saldo
Não
Aplicar limites e vigência parametrizados.
IVA suportado dedutível
Valor
Não
Validar dedutibilidade e pró-rata quando existirem operações mistas.
Crédito de IVA anterior
Valor
Não
Não negativo e associado ao período de origem.
18.6 Etapa 6 — Trabalho, remunerações e segurança social
Campo
Tipo
Obrigatório
Regra/uso
Número total de trabalhadores
Número inteiro
Sim
Não negativo.
Trabalhadores nacionais
Número inteiro
Sim
A soma com expatriados deve reconciliar com o total.
Trabalhadores expatriados
Número inteiro
Sim
Se superior a zero, activar alertas laborais e migratórios.
Remunerações
Grelha repetível: categoria, quantidade, salário bruto, adicionais tributáveis e não contributivos
Sim
Permitir agregação por faixas sem misturar bases individuais de IRPS.
Situação familiar/deduções
Campos por trabalhador ou perfil
Condicional
Solicitar apenas quando necessário ao regime aplicável.
Inscrição no INSS
Sim/Não/Não aplicável
Sim
Apresentar contribuição patronal e desconto do trabalhador separadamente.
Trabalhador por conta própria
Sim/Não
Condicional
Activa regime contributivo próprio quando aplicável.
18.7 Etapa 7 — Pagamentos, retenções e dupla tributação
Campo
Tipo
Obrigatório
Regra/condição
Existem pagamentos sujeitos a retenção?
Sim/Não
Sim
Se “Sim”, abrir grelha de pagamentos.
Pagamentos previstos
Grelha: dividendos, juros, royalties, rendas, serviços ou outros; valor; moeda; periodicidade
Condicional
Uma linha por natureza e beneficiário.
Residência do beneficiário
País e condição de 
residente/não
 residente
Condicional
Determina regra doméstica e eventual convenção.
Relação entre as partes
Independentes ou relacionadas
Condicional
Partes relacionadas activam alerta de preços de transferência.
Convenção de dupla tributação
Selecção e comprovativo
Não
Taxa convencional só pode ser aplicada com convenção vigente e documentação válida.
Certificado de residência fiscal
Referência, validade e comprovativo
Condicional
Sem certificado, aplicar regra doméstica e emitir aviso.
18.8 Etapa 8 — Importações e custos aduaneiros
Campo
Tipo
Obrigatório
Regra/validação
Existem importações?
Sim/Não
Sim
Se “Não”, ocultar esta etapa.
Artigos a importar
Grelha repetível
Condicional
Uma linha por produto/classificação.
Descrição e código pautal
Texto e pesquisa de código
Sim por artigo
Sem código pautal, bloquear cálculo definitivo dos direitos.
País de origem e proveniência
Listas de países
Sim por artigo
Preferência depende da origem comprovada.
Quantidade e unidade
Número e lista de unidades
Sim por artigo
Obrigatórias para ICE específico.
Valor da factura
Valor e moeda
Sim por artigo
Maior ou igual a zero.
Frete, seguro e ajustamentos
Valores e moedas
Sim por artigo
Ajustamento negativo exige fundamento.
Taxa de câmbio aduaneira
Taxa, data e fonte
Condicional
Obrigatória quando a moeda não for 
MZN
.
Preferência, isenção ou regime suspensivo
Selecção e comprovativo
Não
Não aplicar sem evidência válida.
18.9 Etapa 9 — Operações cambiais
Campo
Tipo
Obrigatório
Regra/uso
Capital estrangeiro
Sim/Não; valor, moeda, país e data
Sim
Activa checklist de registo do investimento.
Empréstimo externo
Sim/Não; credor, valor, moeda, prazo e juros
Sim
Indicar registo/aprovação e pagamentos previstos.
Pagamentos ao exterior
Grelha por natureza, beneficiário, valor e periodicidade
Condicional
Associar documentação e banco autorizado.
Receitas de exportação
Valor, moeda e periodicidade
Condicional
Gerar obrigações de recepção/repatriamento quando aplicáveis.
Dividendos e lucros a repatriar
Valor e data prevista
Condicional
Apresentar condições e documentos, sem transformar obrigação cambial em imposto.
Conta em moeda estrangeira
Sim/Não 
e
 finalidade
Não
Gerar orientação conforme o perfil da operação.
Desinvestimento previsto
Sim/Não; data e valor
Não
Activar análise cambial e fiscal de saída.
18.10 Etapa 10 — Revisão, declarações e submissão
Item
Controlo
Condição de submissão
Resumo das respostas
Apresentar por etapa, com opção “Editar”.
Todos os campos obrigatórios completos.
Reconciliações
Investimento versus financiamento; trabalhadores; vendas; custos; importações.
Diferenças corrigidas ou justificadas.
Documentos de suporte
Certificados, residência fiscal, origem, isenções e autorizações.
Benefícios e preferências sem prova ficam apenas como oportunidades a validar.
Declaração de exactidão
Caixa de confirmação.
Obrigatória: o utilizador confirma que os dados inseridos são correctos segundo o seu conhecimento.
Aviso de natureza indicativa
Caixa de confirmação.
Obrigatória: o resultado não substitui parecer oficial ou aconselhamento especializado.
Aviso de privacidade e retenção
Leitura e confirmação.
Obrigatória quando aplicável; indicar finalidades, retenção, direitos e contactos.
Acções
Guardar rascunho; Validar; Calcular; Cancelar.
“Calcular” só é activado após validação sem erros bloqueadores.
18.11 Regras transversais do formulário
Validação:
 impedir valores negativos, datas incoerentes, percentagens fora de 0–100, duplicados e somas não reconciliadas.
Condicionalidade:
 ocultar perguntas irrelevantes e explicar por que um campo adicional foi activado.
Moedas:
 guardar valor original, moeda, taxa, data e fonte; nunca converter silenciosamente.
Explicabilidade:
 cada resultado deve indicar pergunta de origem, regra, fórmula, parâmetros, versão e fundamento legal.
Acessibilidade:
 rótulos persistentes, instruções antes dos campos, mensagens de erro associadas, ordem lógica de foco, teclado, leitor de ecrã, contraste, zoom e interface móvel.
Privacidade:
 recolher apenas dados necessários, evitar dados pessoais em campos livres e não expor NUIT, 
tokens
 ou documentos no relatório.
Resiliência:
 guardar rascunho automaticamente, prevenir submissão duplicada e permitir retoma após falha de rede ou sessão expirada.
Resultado:
 apresentar resumo fiscal, bases, taxas, montantes, benefícios confirmados ou a validar, custos aduaneiros, obrigações cambiais, calendário, cenários, riscos, fontes e data de actualização.
19. Pacote final optimizado para 
Codex
19.1 Prompt final para Codex
Actua como agente principal de implementação do Simulador Fiscal 
InvestMoz
. 
Usa esta especificação para determinar o estado pretendido e usa o repositório real para determinar o estado actualmente implementado. Quando existir conflito entre ambos, não escolhas silenciosamente: regista a divergência como BLOQUEADO e solicita decisão humana.
OBJECTIVO
Implementar apenas as lacunas comprovadas do MVP fiscal, preservando tudo o que já esteja conforme, funcional, testado e compatível. Executa uma única fase por vez e não avances sem aprovação humana explícita do gate anterior.
REGRA DE ACTUALIZAÇÃO INCREMENTAL
Antes de criar ou alterar qualquer artefacto, inspecciona o repositório, o ambiente e os serviços disponíveis. Para 
cada 
requisito, 
classifica o estado como 
CONFORME, PARCIAL, AUSENTE ou BLOQUEADO. 
Mantém sem reescrever o que estiver CONFORME. Corrige somente 
o que estiver 
PARCIAL ou AUSENTE. Para itens BLOQUEADOS, não improvises nem contornes controlos: documenta a causa, impacto, dependência e decisão necessária.
 Não substituas soluções funcionais por preferência técnica.
INSPECÇÃO INICIAL
 OBRIGATÓRIA
Identifica 
stack
, versões, estrutura, convenções, comandos, CI/CD, testes, 
manifestos, 
lockfiles
, contentores, variáveis, serviços e restrições.
 Confirma Laravel, React/Next.js, PostgreSQL/
PostGIS
, Redis, armazenamento de objectos, IAM/
SSO
, 
OpenAPI
 e ferramentas de teste apenas quando existirem.
 Não assumes nomes, caminhos ou comandos. Antes de alterar, apresenta
: plano curto; matriz requisito/evidência/estado/alteração/ficheiros
/testes/gate; e
 lista exacta de ficheiros a criar ou alterar
.
DEPENDÊNCIAS
Não actualizes versões fora do escopo. Não reinstales dependências desnecessariamente. Instala ou restaura dependências somente quando faltarem para executar a fase, usando o gestor e o 
lockfile
 existentes, sem alterar versões bloqueadas; regista o comando e qualquer alteração resultante. Se não existir 
lockfile
 ou o ambiente não puder ser reproduzido com segurança, BLOQUEIA.
SEGURANÇA E PRESERVAÇÃO
Trabalha numa 
branch
 dedicada. 
Não uses 
produção nem 
credenciais de produção. 
Não apagues dados. 
Não edites migrations já executadas; cria migrations novas e reversíveis. Não uses 
migrate:fresh
, 
reset
, 
drop
 ou 
truncate
 excepto numa 
base descartável de testes
, isolada e explicitamente
 confirmada. 
Não alteres interfaces públicas sem versionamento. 
Não publiques taxas, fórmulas, benefícios
 ou interpretações sem fonte oficial e aprovação fiscal e jurídica. Não uses 
eval
 ou execução arbitrária. 
Não guardes 
tokens
 em claro, 
PII
 em 
logs
 ou 
URLs
 assinadas na base. Preserva 
RLS
, 
RBAC
, 
ETag
/
If
-Match, 
idempotência
, 
snapshots
, auditoria, 
soft delete, retenção 
e compatibilidade
.
ESCOPO
 DO MVP FISCAL
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
 e 
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 
de 
ZEE/ZFI
;
 regimes sectoriais
.
FORA DESTA 
RELEASE
:
 manifestações
 formais;
 oportunidades
 de negócio;
 conversões 
para projecto ou oportunidade; integração CRM completa; conta avançada do investidor; assistente inteligente. Não declares nem testes estas funcionalidades como implementadas no MVP. Apenas preserva pontos de extensão existentes.
MODO ANÓNIMO
Recolhe apenas dados económicos, fiscais, territoriais e operacionais necessários ao cálculo. Não solicita nome, NUIT, contactos, identificação, documentos de manifestação ou consentimentos de publicação. Emite o 
token
 uma única vez, persiste apenas SHA-256, aplica retenção e expurgo, protege por 
RLS
 e não expõe 
token
 ou 
hash
 em 
logs
 ou respostas. Para guardar numa conta ou iniciar futura manifestação, exige autenticação e consentimento separado.
FORMULÁRIO
Implementa /Simulador conforme o 
schema
 aprovado. Todo campo com duas ou mais opções usa controlo de selecção acessível apropriado; listas extensas devem ser pesquisáveis. Campos 
multivalor
 permitem selecção e remoção por teclado. Dependências limpam filhos inválidos e “Outro” abre campo condicional. Não definas taxas, regimes, elegibilidade ou pressupostos fiscais por defeito. 
MZN
 pode ser apenas sugestão operacional confirmável pelo utilizador; se o modelo de dados exigir moeda, a escolha explícita prevalece e qualquer 
default
 técnico deve ser neutro ou documentado. Implementa 
autosave
, retoma, 
loading
, erro, conflito, sessão expirada, validação cliente/servidor, móvel, teclado, leitor de ecrã, contraste, zoom e prevenção de submissão duplicada.
FASES E GATES
Executa pela ordem 0–8: 0 Governação; 1 Fundação e contratos executáveis; 2 Repositório legislativo; 3 Regras e publicação; 4 API e formulário; 5 Motor fiscal; 6 Aduanas, câmbios, cenários e calendário; 7 Relatórios e homologação; 8 
Release
 e estabilização. Em cada fase, executa apenas os testes 
aplicáveis que existam ou que a própria fase deva criar. Um teste inexistente que seja requisito da fase é AUSENTE, não “falhado”; cria-o dentro do escopo antes de avaliar o gate. Um serviço externo indisponível deve ser simulado apenas por 
mock
 oficial do projecto e nunca contado como validação de integração real.
MÉTRICA ÚNICA DE APROVAÇÃO
Go
 exige 100% dos testes críticos aplicáveis aprovados e pelo menos 95% dos testes aplicáveis aprovados. “Cobertura de código” é uma métrica separada e não substitui a percentagem de testes aprovados. Testes não aplicáveis exigem justificação e aprovação formal e não entram no numerador nem no denominador. Testes ignorados, instáveis, não executados ou sem evidência não contam como aprovados.
PRIORIDADE DOS ARTEFACTOS
1. decisões e escopo formalmente aprovados; 2. requisitos desta especificação; 3. contrato 
OpenAPI
 integral validado; 4. migrations e 
schema
 executáveis; 5. código e testes; 6. exemplos e extractos. O repositório demonstra o estado actual, mas não pode contrariar silenciosamente o escopo aprovado. Extractos SQL/
OpenAPI
 deste documento são referências, não substituem artefactos integrais validados.
EXECUÇÃO POR FASE
Inspecciona; compara; preserva; propõe alterações mínimas; verifica pré-condições; implementa; executa comandos reais; testa; corrige somente erros do escopo; actualiza documentação; gera evidências; propõe AVANÇAR, CORRIGIR ou BLOQUEAR; e pára. Não avances automaticamente. 
Não afirmes ter executado comandos, testes
, revisões ou aprovações
 que não executaste
 ou não recebeste.
GO/
NO-GO
BLOQUEIA perante fórmula crítica incorrecta, regra sem fonte, benefício sem elegibilidade, sobreposição temporal, fuga de dados, divergência entre API/base/PDF/JSON, 
auto-aprovação
, 
migration
 irreversível, 
OpenAPI
 integral inválido, 
RLS
 não demonstrado, vulnerabilidade crítica, vulnerabilidade alta sem excepção válida, 
rollback
 ou recuperação não demonstrados. Uma falha crítica nunca admite excepção. Uma falha alta requer impacto, controlo compensatório, responsável, prazo e aprovação formal; ao expirar, torna-se bloqueio
.
SAÍDA OBRIGATÓRIA
Entrega: 
fase; objectivo; estado proposto
; matriz de conformidade actualizada; 
itens conformes preservados; itens parciais corrigidos; itens ausentes implementados; bloqueios; ficheiros criados e alterados; 
diff
 lógico por ficheiro; comandos efectivamente executados; 
testes, 
resultados e evidências
; aprovações verificadas
; riscos
;
 pendências; 
rollback
; 
gate avaliado; próxima acção recomendada; 
e 
próxima fase potencialmente autorizável.
REGRA FINAL
Inspecciona → compara → preserva o conforme → implementa apenas lacunas → testa → apresenta evidências → propõe
 AVANÇAR, CORRIGIR ou BLOQUEAR 
→ aguarda aprovação
 humana.
19.2 Versão 
Markdown
 optimizada para Codex
# Simulador Fiscal 
InvestMoz
 — Especificação Executável para 
Codex
## 1. Regra principal
- O repositório real é a fonte de verdade sobre o estado implementado.
- Inspeccionar antes de alterar.
- Classificar cada requisito: `CONFORME`, `PARCIAL`, `AUSENTE` ou `BLOQUEADO`.
- Preservar tudo o que já estiver conforme.
- Implementar apenas lacunas comprovadas.
- Executar uma fase por vez e aguardar revisão humana.
## 2. Escopo do MVP fiscal
### 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 e cambiais.
- Cenários e relatórios PDF/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 da 
release
 inicial
- Manifestações formais.
- Oportunidades de negócio.
- Conversões para projecto ou oportunidade.
- Integração CRM completa.
- Conta avançada do investidor.
- Assistente inteligente.
## 3. 
Stack
 alvo
- Backend: Laravel, adaptado à versão encontrada.
- Frontend: React/Next.js, adaptado à estrutura encontrada.
- Dados: PostgreSQL/
PostGIS
.
- Contrato: 
OpenAPI
 3.1 integral.
- Serviços: Redis, armazenamento de objectos compatível com S3, IAM/
SSO
 e serviço PDF, apenas quando disponíveis.
## 4. Restrições não negociáveis
- Não editar migrations executadas; criar novas migrations reversíveis.
- Não apagar dados nem usar produção.
- Não instalar novamente dependências existentes.
- Não actualizar versões fora do escopo.
- Não codificar taxas fiscais no código.
- Não publicar regras sem fonte e aprovação fiscal/jurídica.
- Não usar `
eval
` ou execução arbitrária.
- Não guardar 
tokens
 em claro, 
PII
 em 
logs
 ou 
URLs
 assinadas na base.
- Manter 
RLS
, 
RBAC
, 
ETag
/
If
-Match, 
idempotência
, 
snapshots
, soft delete e auditoria.
## 5. Fluxo obrigatório por fase
1. Inspeccionar.
2. Produzir matriz de conformidade.
3. Propor plano e ficheiros exactos.
4. Validar pré-condições.
5. Aplicar alterações mínimas.
6. Executar testes reais.
7. Corrigir apenas erros do escopo.
8. Produzir evidências e 
rollback
.
9. Propor `AVANÇAR`, `CORRIGIR` ou `BLOQUEAR`.
10. Aguardar aprovação humana.
## 6. Fases
### Fase 0 — Governação
Escopo, exclusões, 
RACI
, riscos, 
ADRs
, 
backlog
, rastreabilidade e gates.
### Fase 1 — Fundação executável
Reconciliar 
DDL
, migrations, modelos e 
OpenAPI
. Gates: `SQL-01`, `SQL-02`, `OAS-01`, `OAS-02`.
### Fase 2 — Repositório legislativo
Instrumentos, versões, disposições, relações, jurisdições, actividades, documentos, 
hashes
, pesquisa e importação 
idempotente
.
### Fase 3 — Regras e publicação
Parâmetros, rule sets, fontes, elegibilidade, obrigações, revisão de quatro olhos, testes e imutabilidade.
### Fase 4 — API e formulário React
JWT
/scopes, 
RBAC
, 
RLS
, 
token
 anónimo com 
hash
, 
ETag
, 
idempotência
, 
autosave
, validação cliente/servidor, 
dropdowns
 pesquisáveis e acessíveis, dependências, móvel e 
WCAG
. Sem 
defaults
 fiscais.
### Fase 5 — Motor fiscal
IRPC, IVA, ISPC, IRPS, INSS e retenções; regras vigentes; Decimal; arredondamento; transacção atómica; explicabilidade e casos dourados.
### Fase 6 — Aduanas, câmbios e calendário
Valor aduaneiro, direitos, ICE, IVA na importação, moedas, origem, cenários, obrigações, jobs, 
retries
 e 
dead-letter
.
### Fase 7 — Relatórios e homologação
PDF/JSON, checksum, reconciliação, segurança, desempenho, acessibilidade, resiliência, retenção, backup/restauro e E2E.
### Fase 8 — 
Release
Go
/
No-Go
, 
release
 imutável, backup, implantação controlada, 
smoke
 
tests
, 
rollback
, 
hypercare
 e actualização normativa contínua.
## 7. Formulário fiscal
- Configuração da simulação.
- Perfil do contribuinte.
- Actividade e localização.
- Investimento e financiamento.
- Vendas, custos e IVA.
- Trabalho, IRPS e INSS.
- Pagamentos e retenções.
- Importações.
- Obrigações cambiais.
- Revisão e cálculo.
- Modo anónimo não solicita identificação pessoal, NUIT, contactos ou documentos.
## 8. Gates mínimos
- 100% dos testes críticos aprovados.
- Pelo menos 95% dos testes aplicáveis aprovados.
- Zero vulnerabilidades críticas ou altas sem excepção válida.
- SQL e 
OpenAPI
 integrais executáveis.
- PDF, JSON, API e base reconciliados.
- 
Rollback
 e DR demonstrados.
- Aprovações fiscal, jurídica, segurança, operação e homologação registadas.
## 9. Saída de cada execução
```
text
Fase:
Estado proposto: AVANÇAR | CORRIGIR | BLOQUEAR
Itens conformes preservados:
Itens parciais corrigidos:
Itens ausentes implementados:
Bloqueios:
Ficheiros alterados:
Comandos executados:
Testes e resultados:
Evidências:
Riscos:
Rollback
:
Próxima acção autorizável:
```