{
  "id": "cartoes",
  "title": "Cartões de crédito",
  "description": "Cartões, limites, faturas, dias úteis e pagamentos no módulo financeiro.",
  "type": "feature",
  "status": "observed",
  "visibility": "public",
  "tags": [
    "finanças",
    "cartões",
    "faturas"
  ],
  "related": [
    "financas",
    "contas-financeiras",
    "transacoes",
    "automacoes"
  ],
  "sourceRefs": [
    "https://github.com/james-suite/james/blob/master/app/Models/FinancialCreditCard.php",
    "https://github.com/james-suite/james/blob/master/app/Models/FinancialCreditCardInvoice.php",
    "https://github.com/james-suite/james/blob/master/routes/financial.php"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Visão Geral\n\nO módulo de **Cartões de Crédito** gerencia limites, datas de vencimento/fechamento e o ciclo de vida das faturas (invoices). Um cartão está sempre vinculado a uma [Conta Financeira](doc:contas-financeiras) de onde o dinheiro sairá quando a fatura for paga. O módulo possui inteligência de dias úteis para mover automaticamente datas que caiam em finais de semana ou feriados nacionais.\n\n## Tabelas\n\n### `financial_credit_cards`\n\n| Coluna | Tipo | Descrição |\n| --- | --- | --- |\n| `id` | bigint | Chave primária. |\n| `financial_account_id` | foreignId | Conta corrente vinculada para débito do pagamento. |\n| `name` | string | Nome do cartão (Ex: Nubank Platinum). |\n| `credit_limit` | decimal | Limite de crédito disponível. |\n| `closing_day` | integer | Dia padrão de fechamento da fatura (Ex: 7). |\n| `due_day` | integer | Dia padrão de vencimento da fatura (Ex: 2). |\n| `deleted_at` | timestamp | Soft deletes (Lixeira). |\n\n### `financial_credit_card_invoices`\n\n| Coluna | Tipo | Descrição |\n| --- | --- | --- |\n| `id` | bigint | Chave primária. |\n| `financial_credit_card_id` | foreignId | Vínculo com o cartão originador. |\n| `reference_month` | date | Mês/Ano base da fatura (dia é sempre 01). |\n| `closing_date` | date | Data *ajustada* real de fechamento (respeita personalizações e feriados). |\n| `due_date` | date | Data *ajustada* real de vencimento (respeita dias úteis). |\n| `amount_paid` | decimal | Valor já pago nesta fatura. |\n| `paid_at` | date | Data em que a fatura foi totalmente quitada. |\n| `interest_transaction_id`| foreignId | Vínculo com a despesa de juros, caso haja pagamento em atraso. |\n\n## Diagrama Relacional (ER)\n\n{{diagram:cards-model}}\n\n## Regras de Negócio e Comportamento\n\n### Ciclo de Vida e Status da Fatura (`InvoiceStatus`)\n\nO estado da fatura é computado dinamicamente através do Enum `App\\Enums\\InvoiceStatus`:\n\n| Status | Case | Cor | Descrição |\n| --- | --- | --- | --- |\n| **Paga** | `InvoiceStatus::Paid` | Verde | Fatura totalmente quitada (`amount_paid >= total`). |\n| **Parcialmente Paga** | `InvoiceStatus::PartiallyPaid` | Amarelo | Houve pagamento parcial antes do fechamento/vencimento. |\n| **Aberta** | `InvoiceStatus::Open` | Azul | Fatura corrente ainda recebendo novas compras (antes do fechamento). |\n| **Fechada** | `InvoiceStatus::Closed` | Neutro / Cinza | Fatura fechada aguardando pagamento (após o fechamento e antes do vencimento). |\n| **Atrasada** | `InvoiceStatus::Overdue` | Vermelho | Fatura fechada com vencimento ultrapassado e saldo em aberto. |\n\n### Centralização da Fatura Corrente (`setCurrentInvoice`)\n\nO modelo `FinancialCreditCard` centraliza a lógica de resolução da fatura ativa no método `setCurrentInvoice()`. Essa abstração calcula dinamicamente o total da fatura aberta, a quantidade de lançamentos e o status de liquidez sem onerar o banco de dados com queries redundantes em loops de listagem.\n\n### Lógica de Feriados e Dias Úteis\n\nO sistema integra com a `BrasilAPI` (via `BusinessDayHelper`) para buscar os feriados nacionais anuais, mantendo-os em cache:\n- O **Fechamento** é antecipado para o *dia útil anterior* caso caia em feriado/final de semana.\n- O **Vencimento** é postergado para o *próximo dia útil* caso caia em feriado/final de semana.\n- **Fechamento Personalizado:** O sistema respeita fechamentos com data customizada (`closing_date`) definida pelo usuário ou ajustada no banco ao vincular novas transações.\n\n### Rolagem e Vinculação de Compras\n\nAo lançar uma nova compra, o método `FinancialCreditCardInvoice::resolveForDate` compara a data da transação com a data real (ajustada) de fechamento daquele mês. Se a transação for feita no dia ou antes do fechamento, entra na fatura atual. Se for posterior, rola automaticamente para a fatura do mês subsequente.\n\n### Automação (Cron)\n\nO comando `php artisan finance:rollover-invoices` executa diariamente à meia-noite via Laravel Scheduler. Ele percorre todos os cartões ativos e garante que a fatura do mês de referência exista no banco de dados.\n\n### Pagamento da Fatura\n\nQuando o pagamento total é confirmado:\n1. Uma despesa é gerada na Conta Bancária vinculada ao cartão.\n2. Caso informado valor de **Juros**, uma transação extra de juros é gerada aplicando a tag protegida `Juros`.\n3. Todas as transações atreladas à fatura têm seu status alterado para `TransactionStatus::Posted` (`posted`), consolidando o fluxo financeiro.\n\n### Exclusão (Soft Deletes)\n\nCartões não podem ser excluídos permanentemente (`forceDelete`) se possuírem faturas ou transações ativas, garantindo a rastreabilidade contábil.",
  "sections": [
    {
      "id": "visao-geral",
      "level": 2,
      "title": "Visão Geral",
      "text": "O módulo de **Cartões de Crédito** gerencia limites, datas de vencimento/fechamento e o ciclo de vida das faturas (invoices). Um cartão está sempre vinculado a uma [Conta Financeira](doc:contas-financeiras) de onde o dinheiro sairá quando a fatura for paga. O módulo possui inteligência de dias úteis para mover automaticamente datas que caiam em finais de semana ou feriados nacionais.",
      "line": 1
    },
    {
      "id": "tabelas",
      "level": 2,
      "title": "Tabelas",
      "text": "",
      "line": 5
    },
    {
      "id": "financial-credit-cards",
      "level": 3,
      "title": "financial_credit_cards",
      "text": "| Coluna | Tipo | Descrição | | --- | --- | --- | | `id` | bigint | Chave primária. | | `financial_account_id` | foreignId | Conta corrente vinculada para débito do pagamento. | | `name` | string | Nome do cartão (Ex: Nubank Platinum). | | `credit_limit` | decimal | Limite de crédito disponível. | | `closing_day` | integer | Dia padrão de fechamento da fatura (Ex: 7). | | `due_day` | integer | Dia padrão de vencimento da fatura (Ex: 2). | | `deleted_at` | timestamp | Soft deletes (Lixeira). |",
      "line": 7
    },
    {
      "id": "financial-credit-card-invoices",
      "level": 3,
      "title": "financial_credit_card_invoices",
      "text": "| Coluna | Tipo | Descrição | | --- | --- | --- | | `id` | bigint | Chave primária. | | `financial_credit_card_id` | foreignId | Vínculo com o cartão originador. | | `reference_month` | date | Mês/Ano base da fatura (dia é sempre 01). | | `closing_date` | date | Data *ajustada* real de fechamento (respeita personalizações e feriados). | | `due_date` | date | Data *ajustada* real de vencimento (respeita dias úteis). | | `amount_paid` | decimal | Valor já pago nesta fatura. | | `paid_at` | date | Data em que a fatura foi totalmente quitada. | | `interest_transaction_id`| foreignId | Vínculo com a despesa de juros, caso haja pagamento em atraso. |",
      "line": 19
    },
    {
      "id": "diagrama-relacional-er",
      "level": 2,
      "title": "Diagrama Relacional (ER)",
      "text": "",
      "line": 32
    },
    {
      "id": "regras-de-negocio-e-comportamento",
      "level": 2,
      "title": "Regras de Negócio e Comportamento",
      "text": "",
      "line": 36
    },
    {
      "id": "ciclo-de-vida-e-status-da-fatura-invoicestatus",
      "level": 3,
      "title": "Ciclo de Vida e Status da Fatura (InvoiceStatus)",
      "text": "O estado da fatura é computado dinamicamente através do Enum `App\\Enums\\InvoiceStatus`:  | Status | Case | Cor | Descrição | | --- | --- | --- | --- | | **Paga** | `InvoiceStatus::Paid` | Verde | Fatura totalmente quitada (`amount_paid >= total`). | | **Parcialmente Paga** | `InvoiceStatus::PartiallyPaid` | Amarelo | Houve pagamento parcial antes do fechamento/vencimento. | | **Aberta** | `InvoiceStatus::Open` | Azul | Fatura corrente ainda recebendo novas compras (antes do fechamento). | | **Fechada** | `InvoiceStatus::Closed` | Neutro / Cinza | Fatura fechada aguardando pagamento (após o fechamento e antes do vencimento). | | **Atrasada** | `InvoiceStatus::Overdue` | Vermelho | Fatura fechada com vencimento ultrapassado e saldo em aberto. |",
      "line": 38
    },
    {
      "id": "centralizacao-da-fatura-corrente-setcurrentinvoice",
      "level": 3,
      "title": "Centralização da Fatura Corrente (setCurrentInvoice)",
      "text": "O modelo `FinancialCreditCard` centraliza a lógica de resolução da fatura ativa no método `setCurrentInvoice()`. Essa abstração calcula dinamicamente o total da fatura aberta, a quantidade de lançamentos e o status de liquidez sem onerar o banco de dados com queries redundantes em loops de listagem.",
      "line": 50
    },
    {
      "id": "logica-de-feriados-e-dias-uteis",
      "level": 3,
      "title": "Lógica de Feriados e Dias Úteis",
      "text": "O sistema integra com a `BrasilAPI` (via `BusinessDayHelper`) para buscar os feriados nacionais anuais, mantendo-os em cache: - O **Fechamento** é antecipado para o *dia útil anterior* caso caia em feriado/final de semana. - O **Vencimento** é postergado para o *próximo dia útil* caso caia em feriado/final de semana. - **Fechamento Personalizado:** O sistema respeita fechamentos com data customizada (`closing_date`) definida pelo usuário ou ajustada no banco ao vincular novas transações.",
      "line": 54
    },
    {
      "id": "rolagem-e-vinculacao-de-compras",
      "level": 3,
      "title": "Rolagem e Vinculação de Compras",
      "text": "Ao lançar uma nova compra, o método `FinancialCreditCardInvoice::resolveForDate` compara a data da transação com a data real (ajustada) de fechamento daquele mês. Se a transação for feita no dia ou antes do fechamento, entra na fatura atual. Se for posterior, rola automaticamente para a fatura do mês subsequente.",
      "line": 61
    },
    {
      "id": "automacao-cron",
      "level": 3,
      "title": "Automação (Cron)",
      "text": "O comando `php artisan finance:rollover-invoices` executa diariamente à meia-noite via Laravel Scheduler. Ele percorre todos os cartões ativos e garante que a fatura do mês de referência exista no banco de dados.",
      "line": 65
    },
    {
      "id": "pagamento-da-fatura",
      "level": 3,
      "title": "Pagamento da Fatura",
      "text": "Quando o pagamento total é confirmado: 1. Uma despesa é gerada na Conta Bancária vinculada ao cartão. 2. Caso informado valor de **Juros**, uma transação extra de juros é gerada aplicando a tag protegida `Juros`. 3. Todas as transações atreladas à fatura têm seu status alterado para `TransactionStatus::Posted` (`posted`), consolidando o fluxo financeiro.",
      "line": 69
    },
    {
      "id": "exclusao-soft-deletes",
      "level": 3,
      "title": "Exclusão (Soft Deletes)",
      "text": "Cartões não podem ser excluídos permanentemente (`forceDelete`) se possuírem faturas ou transações ativas, garantindo a rastreabilidade contábil.",
      "line": 76
    }
  ],
  "sourcePath": "content/cartoes.md",
  "visuals": [
    {
      "id": "cards-model",
      "kind": "er",
      "title": "Modelo relacional de cartões",
      "description": "Relações entre contas, cartões, faturas e transações de cartão.",
      "summary": "Uma conta financeira pode possuir cartões; cada cartão gera faturas, e as faturas agregam transações com os respectivos estados financeiros.",
      "renderMode": "mermaid",
      "api": "api/diagrams/cards-model.json",
      "human": "diagrams/cards-model.html"
    }
  ],
  "apiVersion": 1
}