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

MAIORE Simulador Tributário · Levantamento 2026-09-29

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.
O uso passo a passo está no Manual do Sistema.

1. Visão da arquitetura

Diagrama (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

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

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/`

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

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

1. Visão da arquitetura

Características arquiteturais (CONFIRMADO)

2. Stack e dependências

Backend (composer.json)

Frontend (package.json)

Infra identificável

3. Estrutura de diretórios relevantes

4. Camada HTTP — rotas e middleware

Grupos principais

Middleware custom (CONFIRMADO)

5. Controllers (mapa técnico)

Controllers do núcleo

6. Services (camada de domínio)

7. Modelo de dados

Entidades centrais

Status relevantes

8. APIs HTTP

9. Processos automáticos

10. Integrações externas

11. Frontend técnico

12. Segurança e riscos técnicos

13. Testes e implantação

14. Matriz de rastreabilidade (amostra)

15. Glossário técnico

16. Documentos relacionados

Backend (`composer.json`)

Frontend (`package.json`)