{
  "id": "contas-financeiras",
  "title": "Contas financeiras",
  "description": "Contas que originam e recebem movimentações financeiras do James.",
  "type": "feature",
  "status": "observed",
  "visibility": "public",
  "tags": [
    "finanças",
    "contas",
    "saldos"
  ],
  "related": [
    "financas",
    "transacoes",
    "cartoes",
    "relatorios"
  ],
  "sourceRefs": [
    "https://github.com/james-suite/james/blob/master/app/Models/FinancialAccount.php",
    "https://github.com/james-suite/james/blob/master/app/Http/Controllers/FinancialAccountController.php"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Visão Geral\n\nAs **Contas Financeiras** são a origem e o destino de todas as movimentações do sistema. A arquitetura centraliza tudo em uma única entidade: seja dinheiro em espécie, conta em banco tradicional ou saldo em corretora de investimentos.\n\n## Tabela: `financial_accounts`\n\n| Coluna | Tipo | Descrição |\n| --- | --- | --- |\n| `id` | bigint | Chave primária. |\n| `name` | string | Nome identificador (Ex: Nubank, Carteira, XP Investimentos). |\n| `type` | string | Enum `FinancialAccountType` (`checking`, `investment`, `wallet`). |\n| `pix_keys` | jsonb | Array contendo as chaves Pix cadastradas (para contas correntes). |\n| `deleted_at` | timestamp | Soft deletes (Lixeira). |\n\n## Diagrama Relacional (ER)\n\nO diagrama abaixo ilustra como a tabela de contas age como o pilar central do módulo financeiro. Todas as relações de dependência utilizam `restrictOnDelete` para proteger a integridade dos dados, impedindo a exclusão permanente de uma conta que possua histórico financeiro.\n\n{{diagram:accounts-model}}\n\n## Regras de Negócio e Comportamento\n\n- **Tipos de Conta (`FinancialAccountType`):**\n  - `Checking` (`Conta Corrente`): Contas bancárias de movimentação diária, com suporte a chaves Pix e pagamento de faturas de cartão.\n  - `Investment` (`Investimentos`): Contas em corretoras ou carteiras de ativos (podem ser isoladas nos relatórios e saldo líquido do dashboard através do toggle de investimentos).\n  - `Wallet` (`Carteira / Dinheiro Físico`): Controle de dinheiro em espécie e valores não bancarizados.\n- **Exclusão Segura (Soft Deletes & Constraints):** Contas podem ser deletadas e enviadas à lixeira sem problemas. Contudo, a **exclusão permanente** (`forceDelete`) é estritamente bloqueada (tanto via aplicação quanto por `restrictOnDelete` no banco) se a conta possuir cartões de crédito, transações ou recorrências vinculadas.\n- **Ícones Dinâmicos (SSOT):** O Enum `FinancialAccountType` centraliza a inteligência de UI através do método `icon()`, garantindo a exibição do ícone correto de acordo com a natureza da conta.\n- **Chaves Pix:** O banco armazena via JSONB, e a interface reage ativando a adição de chaves exclusivamente quando o tipo selecionado for Conta Corrente.\n\n## Métricas (Dashboard da Conta)\n\nA tela de visualização (`show`) atua como uma pequena central analítica para aquela conta específica, calculando dinamicamente:\n- **Receitas:** Somatório total de transações de entrada consolidadas.\n- **Despesas:** Somatório total de transações de saída consolidadas.\n- **Saldo Atual:** Resultado líquido. Possui design responsivo (verde para positivo, vermelho para negativo, neutro para zero).",
  "sections": [
    {
      "id": "visao-geral",
      "level": 2,
      "title": "Visão Geral",
      "text": "As **Contas Financeiras** são a origem e o destino de todas as movimentações do sistema. A arquitetura centraliza tudo em uma única entidade: seja dinheiro em espécie, conta em banco tradicional ou saldo em corretora de investimentos.",
      "line": 1
    },
    {
      "id": "tabela-financial-accounts",
      "level": 2,
      "title": "Tabela: financial_accounts",
      "text": "| Coluna | Tipo | Descrição | | --- | --- | --- | | `id` | bigint | Chave primária. | | `name` | string | Nome identificador (Ex: Nubank, Carteira, XP Investimentos). | | `type` | string | Enum `FinancialAccountType` (`checking`, `investment`, `wallet`). | | `pix_keys` | jsonb | Array contendo as chaves Pix cadastradas (para contas correntes). | | `deleted_at` | timestamp | Soft deletes (Lixeira). |",
      "line": 5
    },
    {
      "id": "diagrama-relacional-er",
      "level": 2,
      "title": "Diagrama Relacional (ER)",
      "text": "O diagrama abaixo ilustra como a tabela de contas age como o pilar central do módulo financeiro. Todas as relações de dependência utilizam `restrictOnDelete` para proteger a integridade dos dados, impedindo a exclusão permanente de uma conta que possua histórico financeiro.",
      "line": 15
    },
    {
      "id": "regras-de-negocio-e-comportamento",
      "level": 2,
      "title": "Regras de Negócio e Comportamento",
      "text": "- **Tipos de Conta (`FinancialAccountType`):** - `Checking` (`Conta Corrente`): Contas bancárias de movimentação diária, com suporte a chaves Pix e pagamento de faturas de cartão. - `Investment` (`Investimentos`): Contas em corretoras ou carteiras de ativos (podem ser isoladas nos relatórios e saldo líquido do dashboard através do toggle de investimentos). - `Wallet` (`Carteira / Dinheiro Físico`): Controle de dinheiro em espécie e valores não bancarizados. - **Exclusão Segura (Soft Deletes & Constraints):** Contas podem ser deletadas e enviadas à lixeira sem problemas. Contudo, a **exclusão permanente** (`forceDelete`) é estritamente bloqueada (tanto via aplicação quanto por `restrictOnDelete` no banco) se a conta possuir cartões de crédito, transações ou recorrências vinculadas. - **Ícones Dinâmicos (SSOT):** O Enum `FinancialAccountType` centraliza a inteligência de UI através do método `icon()`, garantindo a exibição do ícone correto de acordo com a natureza da conta. - **Chaves Pix:** O banco armazena via JSONB, e a interface reage ativando a adição de chaves exclusivamente quando o tipo selecionado for Conta Corrente.",
      "line": 21
    },
    {
      "id": "metricas-dashboard-da-conta",
      "level": 2,
      "title": "Métricas (Dashboard da Conta)",
      "text": "A tela de visualização (`show`) atua como uma pequena central analítica para aquela conta específica, calculando dinamicamente: - **Receitas:** Somatório total de transações de entrada consolidadas. - **Despesas:** Somatório total de transações de saída consolidadas. - **Saldo Atual:** Resultado líquido. Possui design responsivo (verde para positivo, vermelho para negativo, neutro para zero).",
      "line": 31
    }
  ],
  "sourcePath": "content/contas-financeiras.md",
  "visuals": [
    {
      "id": "accounts-model",
      "kind": "er",
      "title": "Modelo relacional de contas",
      "description": "Entidades financeiras dependentes de uma conta financeira.",
      "summary": "Contas financeiras recebem cartões, transações e recorrências. Essas relações restringem a exclusão de uma conta enquanto existirem registros dependentes.",
      "renderMode": "mermaid",
      "api": "api/diagrams/accounts-model.json",
      "human": "diagrams/accounts-model.html"
    }
  ],
  "apiVersion": 1
}