# 01 — Visão geral do sistema

## Identificação

| Item | Valor | Classificação |
|------|-------|---------------|
| Nome comercial (UI) | **MAIORE — Simulador Tributário** | CONFIRMADO — `sidebar.blade.php`, logo `assets/img/maoire-logo.png` |
| Subtítulo UI | Análise fiscal inteligente | CONFIRMADO |
| Stack | PHP 8.3 · Laravel Framework **13.18.1** · MySQL | CONFIRMADO — `.php-version`, `php artisan --version`, `db:show` |
| URL ambiente analisado | `http://simulador-tributario.local` | CONFIRMADO — `.env` `APP_URL` + HTTP 200 em `/sign-in` |
| Banco (dev) | `simulador_tributa` · 53 tabelas no schema da aplicação | CONFIRMADO |

## Objetivo (CONFIRMADO pelo código + docs de escopo)

Ferramenta multi-tenant para **escritórios / consultorias fiscais** simularem o impacto da **Reforma Tributária (CBS + IBS)** a partir de:

1. importação de arquivos **SPED** (EFD ICMS/IPI e EFD Contribuições);
2. classificação de produtos/operações (origem, NCM, cClassTrib);
3. comparação **regime atual × reforma**, com cenários de transição;
4. diagnóstico de **pendências / prontidão** antes de confiar no resultado;
5. consolidação multi-período (grupo anual) e exports executivos.

Evidências: `docs/ESCOPO-CALCULADORA-REFORMA-TRIBUTARIA.md`, menu em `resources/views/components/navbars/sidebar.blade.php`, núcleo em `app/Http/Controllers/Admin/SimulacaoTributariaController.php` + services `Reforma*` / `Confronto*` / `Sped*`.

## Problemas que resolve (CONFIRMADO / INFERIDO)

| Problema | Como o sistema atua | Classificação |
|----------|---------------------|---------------|
| Estimar carga CBS/IBS na transição | Cenários por ano + cálculo em `ReformaCalculoService` | CONFIRMADO |
| Usar dados reais de operação | Parser SPED → `sped_import` / `sped_doc_item` | CONFIRMADO |
| Qualidade cadastral antes da simulação | Confronto → `simulacao_pendencia` + score `simulacao_prontidao` | CONFIRMADO |
| Bloquear simulação “não confiável” | `SimulacaoBloqueadaException` quando prontidão `nao_simulavel` | CONFIRMADO |
| Governança de mudanças | `simulacao_evento_log` via `AuditoriaService` + versões | CONFIRMADO |
| Identificar Simples/MEI | Brasil API (RFB) via `BrasilApiService` / job | CONFIRMADO |

## O que NÃO é (CONFIRMADO em escopo documental)

Conforme `docs/ESCOPO-CALCULADORA-REFORMA-TRIBUTARIA.md`:

- não é substituto de apuração oficial / ERP fiscal (Domínio, SCI, Fortes);
- não é revisor completo de cadastro fiscal como produto principal;
- não é simulador genérico de IRPJ/folha estilo IOB.

**Atenção:** o código atual **evoluiu** além do escopo inicial (confronto, ClassTrib, de-para, prontidão). O escopo histórico descreve a intenção; a implementação vigente é a fonte operacional.

## Público-alvo

| Público | Evidência | Classificação |
|---------|-----------|---------------|
| Usuários internos do tenant (consultores fiscais) | Autenticados acessam `/admin/simulacoes` | CONFIRMADO |
| Administradores de tenant / plataforma | Role `ADMIN`; middleware `admin.tenant` para tenants | CONFIRMADO |
| Role `RH` no banco | Existe em `roles`, **0 usuários** atribuídos no momento do levantamento | CONFIRMADO existência; uso operacional NÃO CONFIRMADO |

## Volumes observados no banco de desenvolvimento (2026-09-29)

| Entidade | Qtde |
|----------|------|
| `simulacao_tributaria` | 73 |
| `reforma_simulacao` | 72 |
| `sped_import` | 48 |
| `pessoa` | 23 |
| `simulacao_pendencia` | 11.846 |
| `simulacao_evento_log` | 234 |
| `classtrib_referencia` | 164 |
| `reforma_cenario` | 8 |
| Users com role ADMIN | 17 |

## Origem do sistema (CONFIRMADO — legado)

O repositório **não nasceu** como simulador isolado. Há rastros de ERP/agenda (eventos, time tracking, NF, veículos, obras, Material Dashboard). O produto atual **reaproveita** multi-tenant, pessoas, uploads e UI, concentrando o menu no simulador.

Ver [15-achados.md](15-achados.md).