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