feat: otimização de performance e ajustes finais

2026-05-18 10:49:32 +00:00
commit 52a7c4f9cf
579 changed files with 156489 additions and 0 deletions
@@ -0,0 +1,59 @@
+# Documentação: Motor Tributário e Coerência Orçamental (Folha de Pagamento)
+
+Esta documentação descreve a implementação da lógica de cálculo de folha de pagamento, motor tributário dinâmico e integração orçamental para o SIGEFP, em conformidade com as normas da Guiné-Bissau.
+
+## 1. Princípios de Cálculo Tributário
+
+O sistema implementa uma lógica de retenção na fonte progressiva e regras globais, com foco na justiça fiscal e precisão.
+
+### 1.1 Base Tributável do IRPS (Imposto sobre o Rendimento de Pessoas Singulares)
+Conforme as normas de segurança social e fiscalidade, a base para aplicação da taxa de IRPS não é o salário bruto total, mas sim o **rendimento líquido de contribuições obrigatórias**.
+- **Fórmula**: `Base_Tributável = Rendimento_Bruto - Contribuição_INPS`
+- **Motivação**: Evitar a tributação em cascata (imposto sobre contribuição).
+
+### 1.2 Motor de Progressividade
+O IRPS é calculado através de escalões progressivos definidos na base de dados.
+- **Cálculo**: `Imposto = (Base_Tributável * Taxa_do_Escalão) - Parcela_a_Abater`
+- **Auditabilidade**: Cada item de folha regista a taxa aplicada e a base utilizada.
+
+---
+
+## 2. Coerência Orçamental (O "Cabimento")
+
+Uma das funcionalidades críticas é a integração automática com o módulo de Orçamento (Budget).
+
+### 2.1 Mapeamento por Classificador Económico
+Cada provento (vencimento, abonos) e cada desconto (impostos, taxas) possui um **Código de Classe Económica** associado.
+- Exemplo: Vencimento Base -> `311100` (Remunerações Certas e Permanentes).
+- Exemplo: INPS -> `311200` (Contribuições para a Segurança Social).
+
+### 2.2 Resolução Automática de Linha Orçamental
+Durante a geração da folha, o `PayrollService` tenta localizar a dotação orçamental correcta:
+1. Identifica o **Ano Fiscal** activo.
+2. Identifica a **Unidade Orgânica** (Unid. Gestora) do agente.
+3. Filtra a **Linha Orçamental** que corresponde ao código económico do item de folha.
+
+### 2.3 Travas de Segurança
+- **Validação Antecipada**: O sistema impede o processamento (finalização) da folha se algum item não tiver uma linha orçamental associada.
+- **Consumo de Dotação**: No momento da conclusão, o sistema comunica com o `BudgetIntegrationService` para registar o compromisso (Commitment).
+
+---
+
+## 3. Gestão Administrativa (Interfaces)
+
+O sistema oferece autonomia total para mudanças legislativas através de duas novas interfaces no módulo de RH:
+
+1. **Gestão de Regras Globais**: Para impostos fixos ou taxas sobre o bruto (ex: INPS 7%, Imposto de Selo).
+2. **Gestão de Escalões IRPS**: Tabela dinâmica de limites de rendimento, percentagens e parcelas a abater.
+
+---
+
+## 4. Componentes Técnicos Principais
+
+- **`PayrollService.java`**: Orquestrador central da lógica de cálculo e integração orçamental.
+- **`TaxController.java`**: API REST para parametrização dinâmica.
+- **`PayrollItem.java`**: Entidade que armazena cada linha de cálculo com a sua respectiva `budgetLine`.
+- **`BudgetIntegrationService.java`**: Ponto de contacto para execução orçamental.
+
+---
+**Status de Conformidade**: Auditado e Coerente com o Decreto 12-A/94 e práticas orçamentais da Guiné-Bissau.