feat: otimização de performance e ajustes finais

2026-05-18 10:49:32 +00:00
commit 430deed1cd
530 changed files with 150759 additions and 0 deletions
@@ -0,0 +1,62 @@
+# Definição de Padrão para Configuração de Novos Impostos
+
+Este documento estabelece o protocolo técnico e funcional para a introdução de novos tributos, contribuições ou retenções no Sistema Integrado de Gestão (SIGEFP), garantindo a automatização sem necessidade de refatoração de código.
+
+## 1. Princípio da Extensibilidade
+O sistema foi desenhado para suportar a adição de novas figuras tributárias desde que estas obedeçam a modelos matemáticos pré-definidos (Fixo ou Progressivo). Qualquer imposto que dependa de variáveis exógenas não previstas na entidade `Agente` ou `Tabela Salarial` requer desenvolvimento específico.
+
+## 2. Contrato de Dados (Data Contract)
+Para que um novo imposto seja reconhecido e processado automaticamente pelo Motor de Cálculo (`PayrollService`), este deve ser registado na base de dados obedecendo rigorosamente à seguinte estrutura:
+
+### 2.1. Entidade: Tipo de Desconto (`deduction_type`)
+Representa a "Categoria" do tributo.
+*   **Identificador (Code)**: Deve ser único, curto e em caixa alta (Ex: `TSAN`).
+*   **Nome (Name)**: O nome amigável que aparecerá nas abas de configuração e nos recibos de vencimento.
+*   **Mandatório (Mandatory)**: `TRUE` se for aplicado a todos automaticamente.
+
+### 2.2. Entidade: Regra de Escalão (`tax_bracket`)
+Define a lógica matemática. O sistema interpreta cada registo como uma regra condicional: *"Se o salário base estiver entre X e Y, aplique Z"*.
+
+| Campo | Obrigatoriedade | Descrição Técnica |
+| :--- | :--- | :--- |
+| `deduction_type_id` | Obrigatório | Chave estrangeira para o Tipo de Desconto. |
+| `lower_limit` | Obrigatório | Limite inferior da faixa de incidência (Inclusive). |
+| `upper_limit` | Opcional | Limite superior. Se nulo, considera-se infinito. |
+| `fixed_amount` | Condicional | Valor monetário fixo a descontar. Preivalece sobre percentagens. |
+| `rate_percentage` | Condicional | Coeficiente decimal (Ex: 0.15 para 15%) aplicado sobre a base tributável. |
+| `excess_deduction` | Opcional | "Parcela a Abater". Valor subtraído do resultado da multiplicação da taxa. |
+
+---
+
+## 3. Modelos Matemáticos Suportados
+O motor de cálculo executa a seguinte lógica de decisão para cada escalão encontrado. Ao configurar um novo imposto, deve-se escolher **apenas um** dos modelos abaixo.
+
+### 3.1. Modelo A: Tributação Fixa (Flat Fee)
+Aplicável a taxas de valor nominal (ex: Taxa de Saneamento, Contribuição Sindical Fixa).
+*   **Configuração**: Preencher apenas `fixed_amount`.
+*   **Fórmula**: `Desconto = Valor Fixo`
+
+### 3.2. Modelo B: Tributação Proporcional Simples (Flat Rate)
+Aplicável a impostos de percentagem única ou variável por faixa, sem dedução (ex: Dízimo, Contribuições Especiais).
+*   **Configuração**: Preencher `rate_percentage`. Deixar `excess_deduction` e `fixed_amount` nulos.
+*   **Fórmula**: `Desconto = Base Tributável × Taxa`
+
+### 3.3. Modelo C: Tributação Progressiva Completa (padrão IRPS)
+Aplicável a impostos sobre rendimento com suavização de curvas.
+*   **Configuração**: Preencher `rate_percentage` e `excess_deduction`.
+*   **Fórmula**: `Desconto = (Base Tributável × Taxa) - Parcela a Abater`
+
+---
+
+## 4. Protocolo de Inserção (Procedimento)
+Para operacionalizar um novo imposto:
+
+1.  **Definição**: Insira o registo mestre na tabela `deduction_type`.
+2.  **Parametrização**: Insira os N escalões necessários na tabela `tax_bracket`, cobrindo todas as faixas salariais possíveis (de 0 ao infinito).
+3.  **Verificação**:
+    *   Acesse o módulo de Recursos Humanos -> Configurações -> Escalões.
+    *   Verifique se uma nova aba com o nome do imposto foi gerada automaticamente.
+    *   Confirme se os valores aparecem conforme inserido.
+4.  **Execução**: Na próxima execução da folha, o sistema iterará sobre o novo tipo e aplicará as regras aos agentes elegíveis.
+
+**Nota Importante**: O sistema assume que a base de cálculo para novos impostos progressivos é (Salário Bruto - Segurança Social), salvo configuração específica em contrário nas Regras Globais.