# 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.
