{ "id": "financas", "title": "Finanças", "description": "Estrutura relacional para contas, transações, cartões, recorrências, tags e relatórios.", "type": "feature", "status": "observed", "visibility": "public", "tags": [ "finanças", "domínio", "relatórios" ], "related": [ "funcionalidades", "contas-financeiras", "transacoes", "cartoes", "recorrencias", "relatorios" ], "sourceRefs": [ "https://github.com/james-suite/james/blob/master/routes/financial.php", "https://github.com/james-suite/james/tree/master/app/Models" ], "authors": [], "updated": null, "diagram": null, "body": "### Visão Geral\nO módulo Financeiro é o núcleo de controle patrimonial do James.\nA regra de ouro é estruturação relacional — dados financeiros precisam\nser somados, agrupados e cruzados em relatórios. O uso de JSONB foi\ndescartado para garantir integridade e performance nas consultas.\n\n### Contas (`financial_accounts`)\nTabela única para todas as carteiras — dinheiro físico (`wallet`), conta corrente (`checking`)\ne investimentos (`investment`). Sem tabelas separadas de bancos.\nÍcones dinâmicos via `FinancialAccountType` e suporte a chaves Pix.\n\n### Transações — Estrutura Pai e Filho\n- `financial_transactions` (Pai) — o registro do pagamento na totalidade:\n conta, valor, data, cartão, status (`TransactionStatus`: Draft, Pending, Posted) e anexos.\n- `financial_transaction_items` (Filhos) — detalhamento dos itens,\n especialmente útil para itens de nota fiscal. Garante relatórios\n precisos por item.\n\n### Cartão de Crédito\nControle de faturas (`financial_credit_card_invoices`) com data de fechamento e vencimento (ajustadas por feriados via BrasilAPI).\nStatus gerenciado via `InvoiceStatus` (Paid, PartiallyPaid, Open, Overdue, Closed).\nGastos no cartão não afetam o saldo imediatamente — a saída ocorre quando a fatura é paga.\n\n### Parcelamentos e Recorrências\nCompras parceladas geram parcelas futuras automaticamente vinculadas à\ntransação original. Transações recorrentes (salário, aluguel, assinaturas)\nsão processadas via Laravel Scheduler diariamente.\n\n### Transferências entre Contas\nGera duas transações vinculadas (`transfer_pair_id`) — saída na conta A e entrada na conta B.\nO saldo total não é afetado.\n\n### Sistema de Tags\nSubstitui o sistema rígido de categorias. Tabela `financial_tags` com `name`, `icon` (Heroicons, Tabler e Phosphor) e `color_hex`.\nTabela pivot polimórfica `financial_taggables` com `is_primary` — permite vincular tags tanto\nna transação pai quanto em itens filhos específicos.\n\n### Relatórios e Dashboards (Apache ECharts)\nVisualizações analíticas em Regime de Caixa (Evolução de Saldo, Diagrama de Sankey do fluxo de dinheiro, drill-down dinâmico por tags e isolamento de investimentos).\n\n### Importação de NFC-e\nImportação assíncrona de notas fiscais de consumidor a partir de URLs públicas ou da leitura do QR Code pela câmera, inicialmente pelo portal SVRS. A nota é criada como rascunho, com emitente, documento, itens, descontos e metadados fiscais, sem afetar os cálculos financeiros até a revisão. Falhas podem ser reenviadas pela notificação recebida pelo usuário.\n\nConsulte a [documentação da Importação de NFC-e](doc:nfce).\n\n### Integrações\n- **Módulo Acertos** — pagamentos e liquidações refletem como transações financeiras.\n- **Módulo Notificações** — avisos de faturas fechadas, lembretes de vencimento e alertas via Telegram / E-mail.\n- **Módulo de Auditoria** — rastreabilidade de todas as alterações em transações, contas e cartões.\n\n### Referências\n- [Roadmap — Módulo Finanças](doc:roadmap)\n- [Decisão 007 — Padronização de data e moeda](doc:decisoes)\n- [Decisão 014 — Biblioteca gráfica (Apache ECharts)](doc:decisoes)", "sections": [ { "id": "visao-geral", "level": 3, "title": "Visão Geral", "text": "O módulo Financeiro é o núcleo de controle patrimonial do James. A regra de ouro é estruturação relacional — dados financeiros precisam ser somados, agrupados e cruzados em relatórios. O uso de JSONB foi descartado para garantir integridade e performance nas consultas.", "line": 1 }, { "id": "contas-financial-accounts", "level": 3, "title": "Contas (financial_accounts)", "text": "Tabela única para todas as carteiras — dinheiro físico (`wallet`), conta corrente (`checking`) e investimentos (`investment`). Sem tabelas separadas de bancos. Ícones dinâmicos via `FinancialAccountType` e suporte a chaves Pix.", "line": 7 }, { "id": "transacoes-estrutura-pai-e-filho", "level": 3, "title": "Transações — Estrutura Pai e Filho", "text": "- `financial_transactions` (Pai) — o registro do pagamento na totalidade: conta, valor, data, cartão, status (`TransactionStatus`: Draft, Pending, Posted) e anexos. - `financial_transaction_items` (Filhos) — detalhamento dos itens, especialmente útil para itens de nota fiscal. Garante relatórios precisos por item.", "line": 12 }, { "id": "cartao-de-credito", "level": 3, "title": "Cartão de Crédito", "text": "Controle de faturas (`financial_credit_card_invoices`) com data de fechamento e vencimento (ajustadas por feriados via BrasilAPI). Status gerenciado via `InvoiceStatus` (Paid, PartiallyPaid, Open, Overdue, Closed). Gastos no cartão não afetam o saldo imediatamente — a saída ocorre quando a fatura é paga.", "line": 19 }, { "id": "parcelamentos-e-recorrencias", "level": 3, "title": "Parcelamentos e Recorrências", "text": "Compras parceladas geram parcelas futuras automaticamente vinculadas à transação original. Transações recorrentes (salário, aluguel, assinaturas) são processadas via Laravel Scheduler diariamente.", "line": 24 }, { "id": "transferencias-entre-contas", "level": 3, "title": "Transferências entre Contas", "text": "Gera duas transações vinculadas (`transfer_pair_id`) — saída na conta A e entrada na conta B. O saldo total não é afetado.", "line": 29 }, { "id": "sistema-de-tags", "level": 3, "title": "Sistema de Tags", "text": "Substitui o sistema rígido de categorias. Tabela `financial_tags` com `name`, `icon` (Heroicons, Tabler e Phosphor) e `color_hex`. Tabela pivot polimórfica `financial_taggables` com `is_primary` — permite vincular tags tanto na transação pai quanto em itens filhos específicos.", "line": 33 }, { "id": "relatorios-e-dashboards-apache-echarts", "level": 3, "title": "Relatórios e Dashboards (Apache ECharts)", "text": "Visualizações analíticas em Regime de Caixa (Evolução de Saldo, Diagrama de Sankey do fluxo de dinheiro, drill-down dinâmico por tags e isolamento de investimentos).", "line": 38 }, { "id": "importacao-de-nfc-e", "level": 3, "title": "Importação de NFC-e", "text": "Importação assíncrona de notas fiscais de consumidor a partir de URLs públicas ou da leitura do QR Code pela câmera, inicialmente pelo portal SVRS. A nota é criada como rascunho, com emitente, documento, itens, descontos e metadados fiscais, sem afetar os cálculos financeiros até a revisão. Falhas podem ser reenviadas pela notificação recebida pelo usuário. Consulte a [documentação da Importação de NFC-e](doc:nfce).", "line": 41 }, { "id": "integracoes", "level": 3, "title": "Integrações", "text": "- **Módulo Acertos** — pagamentos e liquidações refletem como transações financeiras. - **Módulo Notificações** — avisos de faturas fechadas, lembretes de vencimento e alertas via Telegram / E-mail. - **Módulo de Auditoria** — rastreabilidade de todas as alterações em transações, contas e cartões.", "line": 46 }, { "id": "referencias", "level": 3, "title": "Referências", "text": "- [Roadmap — Módulo Finanças](doc:roadmap) - [Decisão 007 — Padronização de data e moeda](doc:decisoes) - [Decisão 014 — Biblioteca gráfica (Apache ECharts)](doc:decisoes)", "line": 51 } ], "sourcePath": "content/financas.md", "visuals": [], "apiVersion": 1 }