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