---
id: recorrencias
title: Recorrências
description: Moldes que geram receitas e despesas ao longo do tempo.
type: feature
status: observed
visibility: public
tags: finanças, recorrências, scheduler
related: financas, transacoes, automacoes, relatorios
source_refs: https://github.com/james-suite/james/blob/master/app/Models/FinancialRecurrence.php, https://github.com/james-suite/james/blob/master/app/Console/Commands/ProcessFinancialRecurrences.php
---

## Visão Geral

As **Recorrências** (`FinancialRecurrence`) permitem a automação do fluxo de caixa agendando despesas ou receitas recorrentes (ex: assinaturas, mensalidades, salários). Diferente de compras parceladas, onde as parcelas nascem limitadas e já instanciadas no banco de dados, as recorrências são um "molde" dinâmico que gera transações à medida que o tempo passa, permitindo projeções de longo prazo sem inchar o banco de dados.

## Tabelas

### `financial_recurrences`

| Coluna | Tipo | Descrição |
| --- | --- | --- |
| `id` | bigint | Chave primária. |
| `financial_account_id` | foreignId | (Opcional) Conta bancária vinculada. |
| `financial_credit_card_id` | foreignId | (Opcional) Cartão de Crédito vinculado. |
| `title` | string | Descrição/Título da recorrência. |
| `type` | enum | `income` (receita) ou `expense` (despesa). |
| `amount` | decimal | Valor base da transação a ser gerada. |
| `frequency` | string | `weekly`, `monthly`, ou `yearly`. |
| `start_date` | date | Data de início da recorrência. O dia desta data serve como base (Ex: dia 15). |
| `end_date` | date | (Opcional) Data em que a recorrência deixa de vigorar. |
| `next_processing_date` | date | Próxima data em que uma transação deverá ser materializada. |
| `is_active` | boolean | Liga/desliga o motor de geração para esta recorrência. |

## Diagrama Relacional (ER)

> **Diagrama: Modelo relacional de recorrências**
> Recorrências se vinculam a uma conta ou cartão e materializam transações históricas.
> Leitura semântica: Uma recorrência tem vínculo exclusivo com uma conta financeira ou cartão de crédito e pode materializar várias transações ao longo do tempo.
> Fonte semântica: `diagrams/recurrences-model.json`
> Fonte declarativa: `diagrams/sources/recurrences-model.mmd`

## Regras de Negócio e Comportamento

### Vínculo Exclusivo (Validação XOR)
Uma recorrência sempre movimenta fundos. Portanto, ela exige um vínculo de origem/destino.
A regra de negócio determina que deve haver um **Ou Exclusivo (XOR)** na validação e na estrutura de dados:
- Ou a recorrência está vinculada a uma Conta Bancária (`financial_account_id`).
- Ou a recorrência está vinculada a um Cartão de Crédito (`financial_credit_card_id`).
As duas colunas não podem estar nulas simultaneamente, nem preenchidas ao mesmo tempo.

### Frequência e Dia Base
O dia em que a transação acontece é definido pelo dia extraído da coluna `start_date` via o método `dayOfMonth()`.
O processamento irá somar +1 semana, +1 mês ou +1 ano a depender da `frequency`, gerando o `next_processing_date`.

### Transações Virtuais vs. Materialização
Para evitar criação massiva de registros no banco de dados para os próximos 10 anos, as recorrências operam sob o conceito de **Transações Virtuais**.
- Ao consultar projeções financeiras, o sistema "extrapola" as datas calculando instâncias virtuais em tempo real na memória.
- Uma recorrência só vira uma `FinancialTransaction` real (materialização) quando:
  1. A data da `next_processing_date` se aproxima de hoje e o motor de automação (Cron) roda para criar a despesa real.
  2. O usuário interage com o sistema para efetivar/pagar manualmente.
  3. Quando vinculada a cartão de crédito, ao chegar próximo ao fechamento da fatura.

Essa abordagem híbrida garante relatórios performáticos enquanto mantém os dados estritamente fiéis à realidade consolidada.