# Documentação Funcional (FSD) — MAIORE Simulador Tributário

| Campo | Valor |
|-------|--------|
| Nome do projeto | MAIORE — Simulador Tributário |
| Tipo de documento | Especificação Funcional (Functional Specification Document — FSD) |
| Referência de template | Functional Specification Document Template (Rizwan Khawaja) / quadro Miro |
| Versão | 2.1 |
| Data | 2026-09-29 |
| Ambiente | http://simulador-tributario.local |
| Classificação de evidência | CONFIRMADO / INFERIDO / NÃO CONFIRMADO / LEGADO |

> **O que este documento é:** descrição formal do **que** o sistema deve fazer (funcionalidades, escopo, requisitos, histórias de usuário e critérios de aceite).  
> **O que não é:** como implementar em PHP/Laravel — ver `ESPECIFICACAO_TECNICA.md`.  
> **Como operar a interface passo a passo:** ver `MANUAL_DO_SISTEMA.md`.

---

## 1. Visão geral do projeto

| Campo | Valor |
|-------|--------|
| Nome do projeto | MAIORE — Simulador Tributário (Análise fiscal inteligente) |
| Product owner / stakeholder | MAIORE / Solução Cliente (**INFERIDO** — marca na UI) |
| Usuários principais | Analistas fiscais, contadores, consultores e administradores do tenant |
| Stack (apenas contexto) | PHP 8.3 · Laravel 13 · MySQL · Blade/Livewire |
| Status do documento | Levantamento do sistema existente (as-is) |
| Última revisão | 2026-09-29 |

---

## 2. Propósito

### Qual problema de negócio estamos resolvendo?

Escritórios e consultorias precisam estimar o impacto da **Reforma Tributária (CBS + IBS)** com base em dados reais do cliente (**SPED**), sem substituir o ERP de apuração oficial.

### Dores atendidas

| Dor | Como o sistema atende |
|-----|------------------------|
| Dados SPED inconsistentes geram simulação “no escuro” | Confronto + pendências + score de **prontidão** |
| Comparar regime atual × reforma é trabalhoso | Wizard de 5 etapas + cálculos consolidados |
| Falta rastreabilidade das premissas | Auditoria + versionamento + justificativas |
| Cliente multi-filial / multi-mês | Importação em lote e consolidado anual |

### Por que agora

O cronograma da reforma (EC 132 / LC 214) exige planejamento tributário antecipado (**CONFIRMADO** pelo posicionamento do produto e docs de escopo).

### O que acontece se não fizermos isso

Consultorias continuam com planilhas manuais, sem padronização de qualidade de dados nem entregáveis reutilizáveis.

### Alinhamento estratégico

Produto SaaS multi-tenant focado em análise consultiva CBS/IBS a partir de SPED — não apuração oficial.

---

## 3. Escopo

### 3.1 Dentro do escopo (CONFIRMADO)

| Categoria | Itens |
|-----------|--------|
| Funcionalidades | Autenticação e sessão única; Simulações (wizard 5 etapas); Importação SPED; Confronto; Pendências/Prontidão; Cenários CBS/IBS; De-para; Auditoria; Feedback de testes; Usuários; Exports PDF/Excel |
| Tipos de usuário | Analista autenticado do tenant; Admin (role Spatie ADMIN); Admin do tenant (`is_admin_tenant`) |
| Plataformas | Web (desktop; UI responsiva parcial — **INFERIDO**) |
| Integrações | Brasil API (CNPJ/CEP/Simples); Sync ClassTrib (SVRS); Brevo (e-mail de reset) |
| Dados | multi-tenant (`idtenant`); clientes (`pessoa`); SPEDs; simulações; reforma |

### 3.2 Fora do escopo

| Categoria | Itens |
|-----------|--------|
| Explicitamente excluído | Apuração oficial / geração de guia; substituto de ERP (Domínio, SCI, Fortes); revisão completa de NCM como produto principal |
| Removido / legado | Demos Material Dashboard; módulo Eventos/Time Tracking/Agenda (código removido) |
| Adiado / não enforceado | ACL fino por permission Spatie em cada tela do simulador; OpenAPI; worker de fila assíncrona (ambiente usa `sync`) |

> **Nota:** o que está fora do escopo é tão importante quanto o que está dentro — gerencia expectativas e evita expansão indevida.

---

## 4. Requisitos funcionais

Linguagem: **deve** = obrigatório (CONFIRMADO no sistema atual); **deveria** = preferencial / parcialmente presente.

| ID | Descrição | Prioridade | Dependências | Teste de aceite |
|----|-----------|------------|--------------|-----------------|
| FR-01 | O sistema **deve** autenticar usuários e garantir uma única sessão ativa por conta | Alta | Tabela de usuários, SingleSession | Login OK; segundo login invalida a sessão anterior |
| FR-02 | O sistema **deve** permitir redefinição de senha por e-mail | Alta | Brevo | Link de reset recebido e senha alterada |
| FR-03 | O sistema **deve** isolar dados por tenant | Alta | TenantScope | Usuário A não vê simulações do tenant B |
| FR-04 | O sistema **deve** criar simulações a partir de lote SPED, arquivo único ou entrada manual | Alta | Parsers SPED | Lote cria análise mensal/grupo |
| FR-05 | O sistema **deve** executar confronto de dados e gerar pendências | Alta | ConfrontoService | Pendências aparecem após o processamento |
| FR-06 | O sistema **deve** calcular score/classificação de prontidão | Alta | ProntidaoService | Classificação = simulavel / ressalva / nao_simulavel |
| FR-07 | O sistema **deve** bloquear o recálculo da reforma quando a prontidão for `nao_simulavel` (salvo força) | Alta | ReformaCalculoService | Mensagem/exceção de bloqueio sem force |
| FR-08 | O sistema **deve** calcular CBS/IBS versus regime atual | Alta | ReformaCalculoService | Resultados gravados e exibidos na UI |
| FR-09 | O sistema **deve** manter tabela de cenários CBS/IBS por ano | Média | ReformaCenario | Edição/sincronização de cenário funciona |
| FR-10 | O sistema **deve** suportar regras de mapeamento De-para | Média | MapaDepara | Criar/copiar regras na simulação |
| FR-11 | O sistema **deve** exportar PDF/Excel (pendências, reforma, consolidado, executivo) | Alta | Serviços de export | Arquivo baixa com sucesso |
| FR-12 | O sistema **deve** registrar eventos de auditoria para mudanças relevantes | Média | AuditoriaService | Eventos visíveis em Auditoria |
| FR-13 | O sistema **deveria** enriquecer CNPJ do cliente com dados Simples/MEI | Média | BrasilAPI / Job | Campo de regime atualizado |
| FR-14 | O sistema **deveria** sincronizar referência cClassTrib diariamente | Média | SyncClassTribJob | Tabela atualizada após o job |
| FR-15 | O sistema **deve** permitir que admins gerenciem usuários/papéis | Média | UserController, Spatie | CRUD de usuário funciona |

---

## 5. Requisitos não funcionais

| Categoria | O que especificar (as-is / alvo) | Classificação |
|-----------|----------------------------------|---------------|
| Desempenho | Importações e cálculos podem rodar de forma síncrona (`QUEUE_CONNECTION=sync`); lotes grandes de SPED podem alongar a requisição | CONFIRMADO (as-is); melhoria = fila assíncrona (**alvo**) |
| Segurança | Autenticação por sessão + sessão única; isolamento por tenant; **proxies `/api/brasil/*` e `/api/gov/*` atualmente públicos** (risco) | CONFIRMADO |
| Usabilidade | UI em português; tours guiados; card-help; wizard de 5 etapas | CONFIRMADO |
| Confiabilidade | Sem soft-delete nos modelos centrais; log de auditoria presente; tabela `failed_jobs` existe | CONFIRMADO / parcial |
| Escalabilidade | SaaS multi-tenant; sync ClassTrib sem sobreposição | CONFIRMADO parcial |
| Manutenibilidade | Camada de serviços no domínio fiscal; Form Requests ausentes; permissions Spatie não enforceadas nas telas do simulador | CONFIRMADO |

---

## 6. Histórias de usuário

Formato: **Como** … **quero** … **para** …

### US-01 — Login
**Como** consultor  
**quero** entrar com minhas credenciais  
**para** acessar com segurança as simulações do meu tenant.  
**Aceite:** redirecionamento para `/admin/simulacoes`; apenas uma sessão ativa.

### US-02 — Importar lote SPED
**Como** analista fiscal  
**quero** enviar vários arquivos SPED de um ano  
**para** montar análise anual consolidada sem digitar tudo.  
**Aceite:** simulações de grupo/mês criadas; cliente detectado pelo CNPJ quando possível.

### US-03 — Avaliar prontidão
**Como** analista fiscal  
**quero** ver resultado do confronto e pendências  
**para** saber se a base é confiável antes de apresentar o impacto CBS/IBS.  
**Aceite:** classificação de prontidão visível; pendências bloqueantes listadas.

### US-04 — Tratar problemas de dados
**Como** analista fiscal  
**quero** resolver ou ignorar pendências com justificativa  
**para** melhorar a prontidão e liberar o cálculo da reforma.  
**Aceite:** status atualizado; auditoria registrada ao resolver/ignorar.

### US-05 — Configurar cenários
**Como** analista fiscal  
**quero** definir parâmetros CBS/IBS e cenários anuais  
**para** simular anos de transição (ex.: 2026–2033).  
**Aceite:** parâmetros salvos; recálculo usa o cenário selecionado.

### US-06 — Simular reforma
**Como** analista fiscal  
**quero** calcular CBS/IBS versus regime atual  
**para** quantificar o impacto da reforma para o cliente.  
**Aceite:** resultados exibidos; bloqueio se não estiver pronto, salvo força.

### US-07 — Exportar entregáveis
**Como** consultor  
**quero** exportar resumos em PDF/Excel  
**para** apresentar achados ao cliente/diretoria.  
**Aceite:** arquivos de export abrem/baixam corretamente.

### US-08 — Trilha de auditoria
**Como** administrador  
**quero** revisar quem alterou o quê  
**para** garantir governança de premissas e correções.  
**Aceite:** Auditoria lista eventos recentes com usuário/data-hora.

### US-09 — Gerenciar usuários
**Como** administrador  
**quero** criar e editar usuários e papéis  
**para** que só pessoas autorizadas acessem o simulador.  
**Aceite:** CRUD de usuário funciona dentro do tenant.

---

## 7. Premissas

| # | Premissa |
|---|----------|
| A1 | Usuários têm alfabetização digital básica e acesso a navegador moderno |
| A2 | Arquivos SPED fornecidos pelo cliente são exportações autênticas (EFD / Contribuições) |
| A3 | Endpoints da Brasil API e do ClassTrib (SVRS) permanecem disponíveis para enriquecimento/sync |
| A4 | Brevo (ou provedor de e-mail configurado) está disponível para reset de senha |
| A5 | Stakeholders de negócio estão disponíveis para validar limiares de prontidão e premissas de cenário |
| A6 | Isolamento multi-tenant por `idtenant` é suficiente para o modelo SaaS atual |
| A7 | O sistema permanece consultivo — a apuração oficial fica fora deste produto |

---

## 8. Restrições

| Tipo | Restrição |
|------|-----------|
| Tecnologia | Stack Laravel/PHP/MySQL já implantada; herança visual do Material Dashboard |
| Segurança | Proxies públicos da API devem ser tratados como risco conhecido até autenticação |
| Processo | Fila atualmente `sync` — jobs longos de SPED/cálculo bloqueiam a requisição |
| Regulatório | O produto **não** se apresenta como substituto da apuração oficial |
| Escopo | Recursos legados de ERP (eventos/demos de NF) removidos do código da aplicação |
| Recursos | A documentação reflete engenharia reversa **as-is** do sistema em execução |

> Seja honesto sobre restrições — elas definem expectativas realistas.

---

## 9. Critérios de aceite (nível de projeto)

Critérios **SMART** e binários (passa/falha).

| ID | Critério | Passa se |
|----|----------|----------|
| AC-01 | Analista completa o caminho feliz SPED → confronto → reforma → export | Ponta a ponta sem bloqueios quando a prontidão permite |
| AC-02 | Pendências bloqueantes impedem resultados não confiáveis da reforma | Recálculo bloqueado quando `nao_simulavel` sem force |
| AC-03 | Isolamento por tenant se mantém | Dados cross-tenant não ficam visíveis |
| AC-04 | Sessão única enforceada | Sessão anterior invalidada após novo login |
| AC-05 | Exports centrais disponíveis | Pelo menos reforma + consolidado + pendências exportam |
| AC-06 | Auditoria captura mudanças materiais | Pendências/parâmetros/versões aparecem em Auditoria |
| AC-07 | Pacote documental entregue | Funcional + Técnica + Manual disponíveis em MD/PDF no layout padrão |

---

## 10. Anexos

> Capturas grandes e inventários técnicos profundos ficam referenciados aqui (não duplicados na narrativa principal).

### Anexo A — Catálogo de telas e imagens

Imagens em `docs/pdf-assets/` (mesmo padrão do Monithora).

| Código | Tela | Imagem |
|--------|------|--------|
| TEL-AUTH-01 | Login | `pdf-assets/login.jpg` |
| TEL-AUTH-02 | Recuperar senha | `pdf-assets/recuperar-senha.jpg` |
| TEL-SIM-01 | Listagem de simulações | `pdf-assets/simulacoes-listagem.jpg` |
| TEL-SIM-02 | Nova simulação | `pdf-assets/nova-simulacao.jpg` |
| TEL-SIM-03 | Edição / wizard | `pdf-assets/simulacao-edicao.jpg` |
| TEL-SIM-04 | Confronto | `pdf-assets/etapa-confronto.jpg` |
| TEL-SIM-05 | Parâmetros / De-para | `pdf-assets/etapa-depara.jpg` |
| TEL-SIM-06 | Reforma | `pdf-assets/etapa-reforma.jpg` |
| TEL-SIM-07 | Regime atual | `pdf-assets/etapa-regime-atual.jpg` |
| TEL-SIM-08 | Dashboard consolidado | `pdf-assets/etapa-consolidado.jpg` |
| TEL-CLI-01 | Clientes | `pdf-assets/clientes-listagem.jpg` |
| TEL-PEN-01 | Pendências | `pdf-assets/pendencias-listagem.jpg` |
| TEL-CEN-01 | Cenários | `pdf-assets/cenarios.jpg` |
| TEL-DEP-01 | Biblioteca De-para | `pdf-assets/depara-listagem.jpg` |
| TEL-AUD-01 | Auditoria | `pdf-assets/auditoria-listagem.jpg` |
| TEL-USR-01 | Usuários | `pdf-assets/usuarios-listagem.jpg` |

![Login](pdf-assets/login.jpg)

![Simulações](pdf-assets/simulacoes-listagem.jpg)

![Nova simulação](pdf-assets/nova-simulacao.jpg)

![Confronto](pdf-assets/etapa-confronto.jpg)

![Pendências](pdf-assets/pendencias-listagem.jpg)

![Reforma](pdf-assets/etapa-reforma.jpg)

![Consolidado](pdf-assets/etapa-consolidado.jpg)

### Anexo B — Documentos relacionados

| Documento | Caminho |
|-----------|---------|
| Especificação Técnica | `ESPECIFICACAO_TECNICA.md` / `.pdf` |
| Manual do Sistema | `MANUAL_DO_SISTEMA.md` / `.pdf` |
| Inventário detalhado | `documentacao-sistema/` |
| Catálogo de regras de negócio | `documentacao-sistema/05-regras-negocio.md` |
| Fonte do template Miro / FSD | Functional Specification Document Template (Rizwan Khawaja) |

### Anexo C — Fluxo operacional principal

```mermaid
flowchart TD
  A[Login] --> B[Criar simulação / Importar SPED]
  B --> C[Confronto + Pendências]
  C --> D[Parâmetros + De-para + Cenários]
  D --> E[Calcular CBS/IBS]
  E --> F{Pronto?}
  F -->|Não| C
  F -->|Sim| G[Dashboard + Exports]
```

### Anexo D — Glossário

| Termo | Significado |
|-------|-------------|
| SPED | Arquivo fiscal digital usado como entrada |
| CBS / IBS | Tributos da reforma simulados pelo produto |
| Prontidão | Score/classificação de prontidão da base |
| Pendência | Problema de dados (bloqueia / alerta / info) |
| Confronto | Motor de verificação de qualidade dos dados |
| De-para | Regras de mapeamento de códigos fiscais |
| cClassTrib | Código de classificação tributária |
| Tenant | Organização isolada no SaaS |