# Especificação Técnica — MAIORE Simulador Tributário

| Campo | Valor |
|-------|--------|
| Sistema | MAIORE Simulador Tributário |
| Stack | Laravel 13.18.1 / PHP 8.3 / MySQL / Livewire 3 / Spatie Permission |
| Versão do documento | 1.1 (levantamento) |
| Data | 2026-09-29 |
| Ambiente de referência | http://simulador-tributario.local + repositório local |

> **Objetivo:** descrever **onde e como** o sistema está implementado — arquitetura, camadas, dados, APIs, jobs, segurança e pontos críticos.  
> Complementa a [Documentação Funcional](DOCUMENTACAO_FUNCIONAL_SISTEMA.md).  
> O uso passo a passo está no [Manual do Sistema](MANUAL_DO_SISTEMA.md).

---

## 1. Visão da arquitetura

```mermaid
flowchart TB
  subgraph presentation [Apresentação]
    Blade[Blade Views]
    LW[Livewire SpedRelatorio]
    Assets[JS/CSS Mix + Material Dashboard]
  end
  subgraph application [Aplicação Laravel]
    Routes[routes/web.php + api.php]
    MW[Middleware Stack]
    Ctrl[Http Controllers Admin/Api]
    Svc[Services ~53]
    Jobs[Jobs + Schedule]
  end
  subgraph domain [Domínio / Persistência]
    Models[Eloquent Models]
    Scope[TenantScope]
    DB[(MySQL simulador_tributa)]
  end
  subgraph external [Externos]
    Brasil[BrasilAPI CNPJ/CEP]
    SVRS[Portal SVRS ClassTrib]
    Brevo[Brevo SMTP API]
  end
  Blade --> Routes
  LW --> Routes
  Routes --> MW --> Ctrl --> Svc --> Models --> Scope --> DB
  Svc --> Brasil
  Svc --> SVRS
  Ctrl --> Brevo
  Jobs --> Svc
```

### Características arquiteturais (CONFIRMADO)

| Padrão | Uso no projeto |
|--------|-----------------|
| MVC Laravel | Controllers + Blade |
| Service Layer | Núcleo fiscal em `app/Services/*` |
| Multi-tenant por coluna | `idtenant` + `TenantScope` |
| ACL | Spatie Permission (parcial) + `role:ADMIN` + `admin.tenant` |
| Sem Repository | Pasta `Repositories` inexistente |
| Sem Form Requests | Validação inline nos controllers |
| Queue | `QUEUE_CONNECTION=sync` no ambiente analisado |

---

## 2. Stack e dependências

### Backend (`composer.json`)

| Pacote | Uso |
|--------|-----|
| `laravel/framework ^13` | Framework |
| `php ^8.3` | Runtime |
| `livewire/livewire ^3` | Componentes (itens SPED) |
| `spatie/laravel-permission ^6` | Roles/permissions |
| `laravel/sanctum ^4` | API token (`/api/user`) |
| `laravel/ui ^4` | Auth scaffolding |
| `phpoffice/phpspreadsheet ^5` | Exports Excel |
| `guzzlehttp/guzzle ^7` | HTTP externo |
| `anhskohbo/no-captcha` | Captcha |
| `mobiledetect/mobiledetectlib` | Detecção mobile |

### Frontend (`package.json`)

`laravel-mix`, `axios`, `bootstrap-select`, `cep-promise`, `flatpickr`, `jquery-mask-plugin`.

### Infra identificável

| Item | Evidência |
|------|-----------|
| URL local | `http://simulador-tributario.local` |
| Deploy FTP | `.ftp-deploy-sync-state.json`, pasta `deploy/` |
| CI | `.github/` |
| Banco | MySQL `simulador_tributa` |

---

## 3. Estrutura de diretórios relevantes

```text
app/
  Console/Commands/SyncClassTribCommand.php
  Dto/PendenciaDto.php
  Exceptions/SimulacaoBloqueadaException.php
  Http/Controllers/Admin/     # núcleo + cadastros
  Http/Controllers/Api/       # BrasilApi, GovBr
  Http/Livewire/SpedRelatorioItensComponent.php
  Http/Middleware/            # SingleSession, AdminTenant, …
  Jobs/                       # ConsultaSimplesJob, SyncClassTribJob
  Models/
  Services/                   # ~53 services
  Scopes/TenantScope.php
  Support/ Traits/ Mail/
routes/web.php | api.php | console.php
resources/views/admin/
database/migrations/
```

---

## 4. Camada HTTP — rotas e middleware

### Grupos principais

| Grupo | Middleware | Prefixo |
|-------|------------|---------|
| Guest | `guest` | login, register, password |
| Auth app | `auth`, `single.session` | dashboard, admin/*, profile |
| Tenants | `admin.tenant` + `role:ADMIN` | `admin/tenants` |
| API proxies | nenhum | `/api/brasil/*`, `/api/gov/*` |
| API user | `auth:sanctum` | `/api/user` |

### Middleware custom (CONFIRMADO)

| Alias | Classe | Comportamento |
|-------|--------|---------------|
| `single.session` | `SingleSession` | Logout se `user.idsession !== Session::getId()` |
| `admin.tenant` | `AdminTenantMiddleware` | Exige `tenant.is_admin_tenant = 1` |
| `role` / `permission` | Spatie | RBAC (uso pontual de `role:ADMIN`) |

**Total de rotas:** 201 (`php artisan route:list`, pós-limpeza de legado).

---

## 5. Controllers (mapa técnico)

### Controllers do núcleo

| Controller | Responsabilidade |
|------------|------------------|
| `SessionsController` | Login/logout + idsession |
| `ForgotPasswordController` | Reset senha (Brevo) |
| `DashboardController` | Redirect para simulações |
| `Admin\SimulacaoTributariaController` | CRUD simulação + reforma + exports |
| `Admin\SimulacaoConfrontoController` | Confronto NCM/ClassTrib/cadastro |
| `Admin\SimulacaoDeparaController` | De-para por simulação |
| `Admin\SimulacaoVersaoController` | Versionamento |
| `Admin\SpedImportController` | Upload/process/itens SPED |
| `Admin\PendenciaController` | Pendências + exports |
| `Admin\MapaDeparaController` | Biblioteca De-para |
| `Admin\ReformaCenarioController` | Cenários CBS/IBS |
| `Admin\ClienteController` | Clientes + job Simples |
| `Admin\AuditoriaController` | Log de eventos |
| `Admin\CardHelpController` | Card-help / feedback |
| `Admin\UserController` | Usuários + roles |
| `Api\BrasilApiController` | Proxy CNPJ/CEP |
| `Api\GovBrController` | Proxy Simples |

---

## 6. Services (camada de domínio)

| Área | Classes principais |
|------|-------------------|
| SPED | `SpedImportProcessor`, parsers, `SpedToSimulacaoService`, `SimulacaoFromSpedService`, `SpedRelatorioService` |
| Regime atual | `SimulacaoCalculoService`, `SimulacaoGrupoService`, `SimulacaoConsolidacaoService` |
| Reforma | `ReformaCalculoService`, `ReformaAnaliseService`, `ReformaTransicaoService`, `ProdutoOrigemClassifier`, `ClassTribResolverService`, `ClassTribSyncService` |
| Qualidade | `ConfrontoService`, `ConfrontoRegrasCatalog`, `ProntidaoService`, `ConfiabilidadeService`, `DiagnosticoMvpService` |
| De-para | `MapaDeparaResolver`, `MapaDeparaPreviewService` |
| Governança | `AuditoriaService`, `VersionamentoService`, `SimulacaoVersaoService` |
| Exports | `RelatorioExecutivoService`, `RelatorioPendenciasService`, `SimulacaoConsolidadoExportService` |
| Integrações | `BrasilApiService`, `GovBrService` |

**Exceção de negócio:** `SimulacaoBloqueadaException` em `ReformaCalculoService::verificarBloqueio`.

---

## 7. Modelo de dados

### Entidades centrais

```text
tenant ──< users
tenant ──< empresa ──< pessoa
pessoa ──< simulacao_tributaria ──< itens/resultados/logs/versões
simulacao_tributaria ──|| reforma_simulacao ──< produtos/resultados
pessoa ──< sped_import ──< sped_doc_item / sped_reg_0200
pessoa ──< simulacao_pendencia / simulacao_prontidao
```

### Status relevantes

| Entidade | Campo | Valores |
|----------|-------|---------|
| Simulação | status | rascunho, concluida, validada_sped |
| Simulação | regime | lucro_real, lucro_presumido, simples |
| Pendência | status | aberta, em_revisao, resolvida, ignorada |
| Pendência | impacto | bloqueia, ressalva, informativo |
| Prontidão | classificacao | simulavel, simulavel_ressalva, nao_simulavel |

Detalhamento: `documentacao-sistema/08-modelo-dados.md`.

---

## 8. APIs HTTP

| Método | URI | Auth | Controller |
|--------|-----|------|------------|
| GET | `/api/brasil/cnpj/{cnpj}` | **Pública** | `BrasilApiController@cnpj` |
| GET | `/api/brasil/cep/{cep}` | **Pública** | `BrasilApiController@cep` |
| GET | `/api/gov/simples/{cnpj}` | **Pública** | `GovBrController@simples` |
| GET | `/api/user` | Sanctum | Closure |

Listagens `admin/*/fetch` são rotas **web** autenticadas (JSON AJAX).

---

## 9. Processos automáticos

| Processo | Trigger | Resultado |
|----------|---------|-----------|
| `SyncClassTribJob` | Schedule diário 06:00 | Upsert `classtrib_referencia` |
| `classtrib:sync` | Command manual | Idem (`--fonte=portal\|api\|local`) |
| `ConsultaSimplesJob` | Create/update cliente | Atualiza `pessoa` + diagnóstico |
| `DiagnosticoMvpService` | Pós-parse SPED OK | Pendências + prontidão + log |

---

## 10. Integrações externas

| Sistema | Auth | Código |
|---------|------|--------|
| BrasilAPI | Nenhuma | `BrasilApiService` |
| Gov/Simples (proxy) | Nenhuma | `GovBrService` |
| SVRS ClassTrib | Portal / cert opcional | `ClassTribSyncService` |
| Brevo | API Key | `ForgotPasswordController` |

---

## 11. Frontend técnico

| Item | Detalhe |
|------|---------|
| Layout | `components/layout.blade.php` + sidebar |
| Views | `resources/views/admin/**` |
| Livewire | `SpedRelatorioItensComponent` |
| Stepper | `?etapa=1..5` · `SimulacaoMvpProgressService` |
| Confronto | `confronto=resumo\|ncm\|classtrib\|cadastro` |

---

## 12. Segurança e riscos técnicos

| ID | Item | Severidade |
|----|------|------------|
| S1 | APIs `/api/brasil/*` e `/api/gov/*` públicas | Alta |
| S2 | Permissions Spatie sem enforcement no simulador | Média |
| S3 | `forcar_simulacao` bypassa bloqueio de prontidão | Média |
| S4 | Queue `sync` — requests longos | Média |
| S5 | Validação espalhada (sem FormRequest) | Baixa/Média |

---

## 13. Testes e implantação

| Item | Situação |
|------|----------|
| PHPUnit ^12 | Presente; cobertura parcial |
| Exemplo | `tests/Unit/ConfrontoRegrasTest.php` |
| Deploy | FTP + pasta `deploy/` |
| Local | `simulador-tributario.local` |

---

## 14. Matriz de rastreabilidade (amostra)

| Função | Rota | Controller | Service | Tabela |
|--------|------|------------|---------|--------|
| Listar simulações | `admin.simulacoes.index` | SimulacaoTributariaController | — | simulacao_tributaria |
| Import SPED | `from-sped*` / `sped.process` | Simulacao* / SpedImport | SpedImportProcessor | sped_* |
| Confronto | `…confronto.recalcular` | SimulacaoConfrontoController | ConfrontoService | simulacao_pendencia |
| Calcular reforma | `…reforma.recalcular` | SimulacaoTributariaController | ReformaCalculoService | reforma_* |
| Sync ClassTrib | schedule | SyncClassTribJob | ClassTribSyncService | classtrib_referencia |

---

## 15. Glossário técnico

| Termo | Significado |
|-------|-------------|
| TenantScope | Global scope filtrando por `idtenant` |
| Prontidão | Score/classificação em `simulacao_prontidao` |
| Confronto | `ConfrontoRegrasCatalog` + `ConfrontoService` |
| Grupo | `escopo=grupo` com filhas mensais |
| cClassTrib | Código em `classtrib_referencia` |

---

## 16. Documentos relacionados

| Documento | Arquivo |
|-----------|---------|
| Documentação Funcional | `DOCUMENTACAO_FUNCIONAL_SISTEMA.md` / `.pdf` |
| Manual do Sistema | `MANUAL_DO_SISTEMA.md` / `.pdf` |
| Acervo detalhado | `documentacao-sistema/` |