npm - @hed-hog/finance - Versions diffs - 0.0.270 → 0.0.274 - Mend

@hed-hog/finance 0.0.270 → 0.0.274

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +636 -437
package/package.json +4 -4

package/README.md CHANGED Viewed

@@ -1,467 +1,666 @@
-# Finance Library - Estrutura de Banco de Dados
+# Módulo Finance - Biblioteca HedHog
-Este documento explica, de forma didática e técnica, como funciona a estrutura de dados do módulo financeiro em `libraries/finance`.
+Este documento técnico detalha o módulo financeiro `@hed-hog/finance` do monorepo HedHog, cobrindo sua visão geral, escopo, endpoints, regras de autenticação, estruturas de dados, erros comuns, banco de dados, regras de negócio e guia rápido de uso.
-## 1) Objetivo do módulo
+---
-O módulo financeiro foi modelado para cobrir o ciclo completo de gestão financeira:
+## 1. Visão geral do módulo
-- cadastro base (filiais, categorias, centros de custo, contas bancárias, meios de pagamento);
-- planejamento (título e parcelas);
-- execução financeira (liquidação/baixa real);
-- conciliação bancária (extrato x liquidação);
-- governança (auditoria e fechamento de período);
-- projeções futuras (cenários, fluxo projetado e agenda de recebíveis).
+O módulo financeiro gerencia o ciclo completo da gestão financeira corporativa, incluindo cadastro, planejamento, execução, conciliação bancária, governança e projeções futuras. Ele suporta contas a pagar e receber, liquidações, conciliações, auditoria e fechamento de períodos, além de cenários de fluxo de caixa e agenda de recebíveis.
-## 2) Convenções gerais
+---
-### 2.1 Escopo atual (sem tenant)
+## 2. Escopo e responsabilidades
-Nesta versão, o módulo **não usa separação por tenant** nas tabelas novas.
-Ou seja, não existem colunas `company_person_id` ou `person_company_id` nas tabelas do módulo financeiro.
+- Cadastro de entidades financeiras: filiais, categorias, centros de custo, contas bancárias, meios de pagamento.
+- Planejamento financeiro: títulos financeiros e suas parcelas.
+- Execução financeira: liquidação e baixa real de parcelas.
+- Conciliação bancária: importação e associação de extratos bancários.
+- Governança: auditoria de ações e fechamento operacional de períodos.
+- Projeções financeiras: cenários, fluxo projetado e agenda de recebíveis.
+- Gestão de transferências entre contas.
+- Gestão de cobranças e acordos.
-### 2.2 Tabelas já existentes usadas pelo módulo
+---
-O módulo reutiliza tabelas de outras libraries:
+## 3. Endpoints
-- `person`: contraparte de títulos e liquidações (cliente/fornecedor).
-- `user`: autoria e rastreabilidade (`created_by`, `matched_by`, `closed_by`, etc.).
-- `tag`: classificação analítica de parcelas.
-- `file`: anexos de títulos.
+### FinanceAuditLogsController
-### 2.3 Padrões recomendados de domínio
+| Método | Path                  | Auth  | Descrição                         | Parâmetros/Query                                                                                  | Resposta                         | Erros Comuns           |
+|--------|-----------------------|-------|----------------------------------|-------------------------------------------------------------------------------------------------|---------------------------------|-----------------------|
+| GET    | /finance/audit-logs   | Sim   | Lista logs de auditoria financeira | Query: `search`, `action`, `entity_table`, `actor_user_id`, `from`, `to`, paginação              | Lista paginada de logs           | 401 Unauthorized      |
-- Valores monetários em centavos (`*_cents`) para evitar erro de precisão.
-- Datas de competência e vencimento separadas para análises corretas.
-- Histórico imutável de eventos financeiros: não apagar histórico; corrigir por estorno/ajuste.
+---
-## 3) Visão macro das relações
+### FinanceBankAccountsController
-Fluxo principal de operação:
+| Método | Path                      | Auth  | Descrição                         | Parâmetros/Body                                                                                  | Resposta                         | Erros Comuns           |
+|--------|---------------------------|-------|----------------------------------|-------------------------------------------------------------------------------------------------|---------------------------------|-----------------------|
+| GET    | /finance/bank-accounts     | Sim   | Lista contas bancárias            | -                                                                                               | Lista de contas bancárias        | 401 Unauthorized      |
+| POST   | /finance/bank-accounts     | Sim   | Cria nova conta bancária         | Body: `{ bank: string, branch?: string, account?: string, type: string, description?: string, initial_balance?: number }` | Conta criada                    | 400 Validação         |
+| PATCH  | /finance/bank-accounts/:id | Sim   | Atualiza conta bancária           | Body: campos opcionais para atualização (bank, branch, account, type, description, status)       | Conta atualizada                 | 400 Validação, 404     |
+| DELETE | /finance/bank-accounts/:id | Sim   | Remove conta bancária             | -                                                                                               | Confirmação de exclusão          | 404 Not Found          |
-1. Cadastra `financial_title` (documento pai).
-2. Gera `financial_installment` (parcelas).
-3. Registra `settlement` (dinheiro real).
-4. Liga settlement às parcelas em `settlement_allocation`.
-5. Importa extrato (`bank_statement` e `bank_statement_line`).
-6. Concilia extrato x settlement em `bank_reconciliation`.
+---
-Relações de suporte:
+### FinanceCategoriesController
-- `financial_installment_tag`: N:N entre parcela e tag.
-- `installment_allocation`: rateio de parcela por centro de custo.
-- `financial_title_attachment`: documentos anexos.
-- `audit_log`: trilha de auditoria de ações.
-- `period_close`: bloqueio operacional por período.
+| Método | Path                      | Auth  | Descrição                         | Parâmetros/Body                                                                                  | Resposta                         | Erros Comuns           |
+|--------|---------------------------|-------|----------------------------------|-------------------------------------------------------------------------------------------------|---------------------------------|-----------------------|
+| GET    | /finance/categories       | Sim   | Lista categorias financeiras      | -                                                                                               | Lista de categorias              | 401 Unauthorized      |
+| POST   | /finance/categories       | Sim   | Cria categoria financeira         | Body: `{ name: string, kind: string, parent_id?: number }`                                      | Categoria criada                 | 400 Validação         |
+| PATCH  | /finance/categories/:id   | Sim   | Atualiza categoria financeira     | Body: campos opcionais (name, kind, parent_id, status)                                          | Categoria atualizada             | 400 Validação, 404     |
+| PATCH  | /finance/categories/:id/move | Sim | Move categoria na hierarquia      | Body: `{ parent_id?: number, position?: number }`                                               | Categoria movida                 | 400 Validação, 404     |
+| DELETE | /finance/categories/:id   | Sim   | Remove categoria financeira       | -                                                                                               | Confirmação de exclusão          | 404 Not Found          |
-## 4) Dicionário de tabelas (objetivo, colunas e uso)
+---
-## 4.1 company_profile
+### FinanceCollectionsController
-**Objetivo:** guardar configurações globais do contexto financeiro (status, moeda e timezone).
+| Método | Path                                               | Auth  | Descrição                         | Parâmetros/Body                                                                                  | Resposta                         | Erros Comuns           |
+|--------|----------------------------------------------------|-------|----------------------------------|-------------------------------------------------------------------------------------------------|---------------------------------|-----------------------|
+| GET    | /finance/accounts-receivable/collections-default   | Sim   | Obtém configurações padrão de cobrança | -                                                                                               | Configurações padrão             | 401 Unauthorized      |
+| POST   | /finance/accounts-receivable/collections-default/:personId/send | Sim | Envia mensagem de cobrança para pessoa | Body: `{ message: string, subject?: string }`                                                   | Confirmação de envio             | 400 Validação, 404     |
+| POST   | /finance/accounts-receivable/collections-default/:personId/agreements | Sim | Registra acordo de cobrança para pessoa | Body: `{ amount: number, installments: number, first_due_date: string, notes?: string }`         | Acordo registrado                | 400 Validação, 404     |
-**Colunas:**
+---
-- `id`: chave primária.
-- `code`: identificador curto/estável para integração e referência.
-- `status`: `active|inactive`.
-- `default_currency`: moeda padrão (ex.: `BRL`).
-- `timezone`: timezone padrão (ex.: `America/Sao_Paulo`).
-- `created_at`, `updated_at`: auditoria temporal.
+### FinanceCostCentersController
-**Uso comum:** inicialização de regras de data/moeda em UI, API e relatórios.
+| Método | Path                      | Auth  | Descrição                         | Parâmetros/Body                                                                                  | Resposta                         | Erros Comuns           |
+|--------|---------------------------|-------|----------------------------------|-------------------------------------------------------------------------------------------------|---------------------------------|-----------------------|
+| GET    | /finance/cost-centers     | Sim   | Lista centros de custo            | -                                                                                               | Lista de centros de custo        | 401 Unauthorized      |
+| POST   | /finance/cost-centers     | Sim   | Cria centro de custo              | Body: `{ name: string }`                                                                         | Centro criado                   | 400 Validação         |
+| PATCH  | /finance/cost-centers/:id | Sim   | Atualiza centro de custo          | Body: `{ name?: string, status?: 'active' | 'inactive' }`                                       | Centro atualizado               | 400 Validação, 404     |
+| DELETE | /finance/cost-centers/:id | Sim   | Remove centro de custo            | -                                                                                               | Confirmação de exclusão          | 404 Not Found          |
-## 4.3 finance_category
+---
-**Objetivo:** plano de categorias financeiras para classificação analítica.
+### FinanceDataController
-**Colunas:**
+| Método | Path                  | Auth  | Descrição                         | Parâmetros/Query                                                                                  | Resposta                         | Erros Comuns           |
+|--------|-----------------------|-------|----------------------------------|-------------------------------------------------------------------------------------------------|---------------------------------|-----------------------|
+| GET    | /finance/data         | Sim   | Obtém dados financeiros com filtros | Query: `horizonte` (dias), `cenario` (nome do cenário)                                          | Dados financeiros filtrados      | 401 Unauthorized      |
+| PATCH  | /finance/scenarios/:cenario | Sim | Atualiza configurações do cenário | Body: `{ atrasoMedio: number, taxaInadimplencia: number, crescimentoReceita: number, setAsDefault?: boolean }` | Cenário atualizado               | 400 Validação, 404     |
-- `id`: chave primária.
-- `parent_id`: auto-relacionamento para hierarquia (nullable).
-- `code`: código da categoria.
-- `name`: nome da categoria.
-- `kind`: `revenue|expense|transfer|adjustment|other`.
-- `status`: `active|inactive`.
-- `created_at`, `updated_at`.
+---
-**Relações:**
+### FinanceInstallmentsController
-- Auto-relacionamento por `parent_id`.
-- Referenciada por `financial_title.finance_category_id`.
+Endpoints para contas a pagar e receber, títulos, parcelas, liquidações, estornos, tags e extração de dados de arquivos.
-## 4.4 cost_center
-**Objetivo:** centro de custo/projeto para rateio gerencial.
-**Colunas:**
-- `id`: chave primária.
-- `code`: código do centro de custo.
-- `name`: nome exibível.
-- `status`: `active|inactive`.
-- `created_at`, `updated_at`.
-**Relações:**
-- Referenciada por `installment_allocation.cost_center_id`.
-## 4.5 payment_method
-**Objetivo:** catálogo configurável de meios de pagamento/recebimento.
-**Colunas:**
-- `id`: chave primária.
-- `code`: identificador do método.
-- `name`: nome exibível.
-- `type`: `pix|boleto|ted|doc|card|cash|other`.
-- `status`: `active|inactive`.
-- `created_at`, `updated_at`.
-**Relações:**
-- Referenciada por `settlement.payment_method_id`.
-## 4.6 bank_account
-**Objetivo:** contas bancárias/caixa usadas nos movimentos reais.
-**Colunas:**
-- `id`: chave primária.
-- `code`: código da conta.
-- `name`: nome exibível.
-- `bank_name`, `bank_code`: metadados bancários (nullable).
-- `agency`, `account_number`: metadados bancários (nullable).
-- `account_type`: `checking|savings|investment|cash|other`.
-- `status`: `active|inactive`.
-- `created_at`, `updated_at`.
-**Relações:**
-- Referenciada por `bank_statement.bank_account_id`.
-- Referenciada por `bank_statement_line.bank_account_id`.
-- Referenciada por `settlement.bank_account_id`.
-## 4.7 financial_title
-**Objetivo:** documento pai de contas a pagar/receber.
-**Colunas:**
-- `id`: chave primária.
-- `person_id`: FK para contraparte (`person.id`).
-- `title_type`: `payable|receivable`.
-- `status`: `draft|open|partial|settled|canceled|overdue`.
-- `document_number`: número do documento (nullable).
-- `description`: histórico/observações (nullable).
-- `competence_date`: competência macro (nullable).
-- `issue_date`: emissão (nullable).
-- `total_amount_cents`: total previsto no título.
-- `finance_category_id`: FK para categoria (nullable).
-- `created_by_user_id`: FK para `user.id` (nullable).
-- `created_at`, `updated_at`.
-**Relações:**
-- 1:N com `financial_installment`.
-- 1:N com `financial_title_attachment`.
-## 4.8 financial_installment
-**Objetivo:** parcelas planejadas de cada título.
-**Colunas:**
-- `id`: chave primária.
-- `title_id`: FK para `financial_title.id`.
-- `installment_number`: número sequencial da parcela por título.
-- `competence_date`: competência contábil/gerencial.
-- `due_date`: vencimento.
-- `amount_cents`: valor original da parcela.
-- `open_amount_cents`: saldo em aberto.
-- `status`: `open|partial|settled|canceled|overdue`.
-- `notes`: observações (nullable).
-- `created_at`, `updated_at`.
-**Relações:**
-- N:1 com `financial_title`.
-- N:N com `tag` via `financial_installment_tag`.
-- 1:N com `installment_allocation`.
-- 1:N com `settlement_allocation`.
-## 4.9 financial_title_attachment
-**Objetivo:** anexar arquivos ao título sem armazenar binário na tabela.
-**Colunas:**
-- `id`: chave primária.
-- `title_id`: FK para `financial_title.id`.
-- `file_id`: FK para `file.id`.
-- `uploaded_by_user_id`: FK para `user.id` (nullable).
-- `created_at`, `updated_at`.
-## 4.10 financial_installment_tag
-**Objetivo:** classificação por tags em nível de parcela.
-**Colunas:**
-- `id`: chave primária.
-- `installment_id`: FK para `financial_installment.id`.
-- `tag_id`: FK para `tag.id`.
-- `created_at`, `updated_at`.
-**Observação:** possui unicidade (`installment_id`, `tag_id`) para evitar duplicidade.
-## 4.11 installment_allocation
-**Objetivo:** ratear uma parcela entre centros de custo.
-**Colunas:**
-- `id`: chave primária.
-- `installment_id`: FK para `financial_installment.id`.
-- `cost_center_id`: FK para `cost_center.id`.
-- `allocated_amount_cents`: valor alocado.
-- `created_at`, `updated_at`.
-**Observação:** possui unicidade (`installment_id`, `cost_center_id`).
-## 4.12 settlement
-**Objetivo:** representar o evento financeiro real (pagamento/recebimento/transferência/ajuste).
-**Colunas:**
-- `id`: chave primária.
-- `person_id`: FK para `person.id` (nullable).
-- `bank_account_id`: FK para `bank_account.id` (nullable).
-- `payment_method_id`: FK para `payment_method.id` (nullable).
-- `settlement_type`: `payable|receivable|transfer|adjustment`.
-- `status`: `pending|confirmed|reversed`.
-- `settled_at`: data/hora do evento financeiro.
-- `amount_cents`: valor do evento.
-- `description`: histórico (nullable).
-- `external_reference`: referência externa (nullable).
-- `created_by_user_id`: FK para `user.id` (nullable).
-- `created_at`, `updated_at`.
-**Relações:**
-- 1:N com `settlement_allocation`.
-- 1:1 com `bank_reconciliation` (por restrição de unicidade).
-## 4.13 settlement_allocation
-**Objetivo:** distribuir um settlement em uma ou várias parcelas.
-**Colunas:**
-- `id`: chave primária.
-- `settlement_id`: FK para `settlement.id`.
-- `installment_id`: FK para `financial_installment.id`.
-- `allocated_amount_cents`: valor aplicado na parcela.
-- `discount_cents`: desconto aplicado.
-- `interest_cents`: juros aplicado.
-- `penalty_cents`: multa aplicada.
-- `created_at`, `updated_at`.
-**Observação:** possui unicidade (`settlement_id`, `installment_id`).
-## 4.14 bank_statement
-**Objetivo:** lote de importação de extrato bancário.
-**Colunas:**
-- `id`: chave primária.
-- `bank_account_id`: FK para `bank_account.id`.
-- `source_type`: `ofx|csv|manual`.
-- `idempotency_key`: evita reimportação do mesmo lote (nullable).
-- `period_start`, `period_end`: intervalo coberto no extrato (nullable).
-- `imported_at`: data/hora da importação.
-- `imported_by_user_id`: FK para `user.id` (nullable).
-- `created_at`, `updated_at`.
-**Relações:**
-- 1:N com `bank_statement_line`.
-## 4.15 bank_statement_line
-**Objetivo:** transações individuais do extrato (a prova bancária).
-**Colunas:**
-- `id`: chave primária.
-- `bank_statement_id`: FK para `bank_statement.id`.
-- `bank_account_id`: FK para `bank_account.id`.
-- `external_id`: identificador externo do banco (nullable).
-- `posted_date`: data efetiva.
-- `amount_cents`: valor da linha.
-- `description`: histórico do banco.
-- `status`: `imported|pending|reconciled|reversed|adjusted`.
-- `dedupe_key`: chave de deduplicação (única).
-- `created_at`, `updated_at`.
-**Relações:**
-- 1:1 com `bank_reconciliation` (por restrição de unicidade).
-## 4.16 bank_reconciliation
-**Objetivo:** vínculo auditável entre linha de extrato e settlement.
-**Colunas:**
-- `id`: chave primária.
-- `bank_statement_line_id`: FK para `bank_statement_line.id` (único).
-- `settlement_id`: FK para `settlement.id` (único).
-- `status`: `pending|reconciled|reversed|adjusted`.
-- `matched_at`: data/hora da conciliação (nullable).
-- `matched_by_user_id`: FK para `user.id` (nullable).
-- `created_at`, `updated_at`.
-**Observação:** modelado como 1:1 para simplificar conciliação de eventos.
-## 4.17 audit_log
-**Objetivo:** trilha de auditoria funcional do módulo.
-**Colunas:**
-- `id`: chave primária.
-- `actor_user_id`: FK para `user.id` (nullable).
-- `action`: ação executada (ex.: `SETTLEMENT_CREATE`).
-- `entity_table`: tabela afetada.
-- `entity_id`: id da entidade afetada (string).
-- `summary`: resumo legível (nullable).
-- `before_data`: snapshot anterior (nullable).
-- `after_data`: snapshot posterior (nullable).
-- `ip_address`: origem da ação (nullable).
-- `created_at`, `updated_at`.
-## 4.18 period_close
-**Objetivo:** controlar fechamento operacional de período.
-**Colunas:**
-- `id`: chave primária.
-- `period_start`: início do período.
-- `period_end`: fim do período.
-- `status`: `open|closed`.
-- `closed_at`: data/hora do fechamento (nullable).
-- `closed_by_user_id`: FK para `user.id` (nullable).
-- `notes`: observações (nullable).
-- `created_at`, `updated_at`.
-**Uso comum:** bloquear operações diretas em períodos fechados e permitir apenas estornos sob regra.
-## 4.19 forecast_scenario
-**Objetivo:** cenários de planejamento financeiro futuro.
-**Colunas:**
-- `id`: chave primária.
-- `name`: nome do cenário (ex.: Base, Conservador).
-- `status`: `active|inactive`.
-- `is_default`: cenário padrão.
-- `created_at`, `updated_at`.
-**Relações:**
-- 1:N com `cashflow_projection`.
-- 1:N com `receivable_schedule`.
-## 4.20 cashflow_projection
-**Objetivo:** linhas de projeção de fluxo por data e tipo.
-**Colunas:**
-- `id`: chave primária.
-- `scenario_id`: FK para `forecast_scenario.id`.
-- `projection_date`: data projetada.
-- `projection_type`: `inflow|outflow|net`.
-- `amount_cents`: valor projetado.
-- `notes`: observações (nullable).
-- `created_at`, `updated_at`.
-## 4.21 receivable_schedule
-**Objetivo:** agenda de recebíveis previstos quando ainda não há título lançado.
-**Colunas:**
-- `id`: chave primária.
-- `scenario_id`: FK para `forecast_scenario.id`.
-- `person_id`: FK para `person.id` (nullable).
-- `expected_date`: data esperada.
-- `amount_cents`: valor esperado.
-- `description`: descrição (nullable).
-- `created_at`, `updated_at`.
-## 5) Fluxos operacionais essenciais
-## 5.1 Contas a pagar/receber
-1. Criar `financial_title`.
-2. Criar parcelas em `financial_installment`.
-3. Registrar liquidação em `settlement`.
-4. Alocar liquidação em `settlement_allocation`.
-5. Atualizar saldo em aberto e status da parcela/título na regra de negócio.
-## 5.2 Conciliação bancária
-1. Importar lote em `bank_statement`.
-2. Inserir linhas em `bank_statement_line` com `dedupe_key`.
-3. Associar linha e settlement em `bank_reconciliation`.
-4. Atualizar status de conciliação e registrar auditoria.
-## 5.3 Estorno
-1. Não apagar dados históricos.
-2. Marcar `settlement.status = reversed`.
-3. Reprocessar saldo em aberto das parcelas relacionadas.
-4. Registrar no `audit_log`.
-## 5.4 Fechamento de período
-1. Definir janela em `period_close`.
-2. Marcar `status = closed`.
-3. Bloquear lançamentos/alterações do período fechado via regra da aplicação.
-## 6) Invariantes recomendados de regra de negócio
-Para manter consistência financeira, o ideal é garantir (na aplicação e, quando possível, no banco):
-- `financial_installment.open_amount_cents >= 0`.
-- `financial_installment.open_amount_cents <= financial_installment.amount_cents`.
-- soma de `settlement_allocation.allocated_amount_cents` por parcela não excede o valor permitido pela política da parcela.
-- soma de `installment_allocation.allocated_amount_cents` coerente com a política de rateio da parcela.
-- `period_end >= period_start` em `period_close`.
-- unicidade respeitada em tabelas de vínculo N:N para evitar duplicidades.
-## 7) Diretrizes para novos desenvolvedores
-- Trate `financial_title` como agregador de documento e `financial_installment` como unidade operacional de cobrança/baixa.
-- Considere `settlement` como evento imutável de dinheiro real; prefira estorno/ajuste em vez de edição destrutiva.
-- Use `audit_log` sempre que houver alteração relevante de estado.
-- Ao importar extrato, monte `dedupe_key` estável para evitar duplicidade.
-- Ao evoluir schema, preserve compatibilidade de índices e FKs com os fluxos descritos neste documento.
-## 8) Resumo rápido da arquitetura
-- **Cadastro:** `company_profile`, `branch`, `finance_category`, `cost_center`, `payment_method`, `bank_account`.
-- **Operação:** `financial_title`, `financial_installment`, `settlement`, `settlement_allocation`.
-- **Conciliação:** `bank_statement`, `bank_statement_line`, `bank_reconciliation`.
-- **Governança:** `audit_log`, `period_close`.
-- **Planejamento:** `forecast_scenario`, `cashflow_projection`, `receivable_schedule`.
-Com essa estrutura, o módulo cobre planejamento, execução, rastreabilidade e projeção financeira de forma consistente e extensível.
+| Método | Path                                                        | Auth  | Descrição                         | Parâmetros/Body/Query                                                                                  | Resposta                         | Erros Comuns           |
+|--------|-------------------------------------------------------------|-------|----------------------------------|-------------------------------------------------------------------------------------------------------|---------------------------------|-----------------------|
+| GET    | /finance/accounts-payable/installments                      | Sim   | Lista parcelas contas a pagar     | Query: `status`, paginação                                                                             | Lista paginada                  | 401 Unauthorized      |
+| GET    | /finance/accounts-payable/installments/:id                  | Sim   | Detalha parcela contas a pagar    | Path param: `id`                                                                                       | Detalhes da parcela             | 404 Not Found          |
+| POST   | /finance/accounts-payable/installments                      | Sim   | Cria título contas a pagar        | Body: `CreateFinancialTitleDto`                                                                        | Título criado                  | 400 Validação         |
+| PATCH  | /finance/accounts-payable/installments/:id                  | Sim   | Atualiza título contas a pagar    | Body: `CreateFinancialTitleDto`                                                                        | Título atualizado              | 400 Validação, 404     |
+| PATCH  | /finance/accounts-payable/installments/:id/approve          | Sim   | Aprova título contas a pagar      | -                                                                                                     | Título aprovado               | 404 Not Found          |
+| PATCH  | /finance/accounts-payable/installments/:id/reject           | Sim   | Rejeita título contas a pagar     | Body: `{ reason?: string }`                                                                             | Título rejeitado              | 400 Validação, 404     |
+| PATCH  | /finance/accounts-payable/installments/:id/cancel           | Sim   | Cancela título contas a pagar     | Body: `{ reason?: string }`                                                                             | Título cancelado              | 400 Validação, 404     |
+| POST   | /finance/accounts-payable/installments/:id/settlements      | Sim   | Registra liquidação parcela       | Body: dados de liquidação (ver DTO SettleInstallmentDto)                                               | Liquidação registrada          | 400 Validação, 404     |
+| PATCH  | /finance/accounts-payable/installments/:id/settlements/:settlementId/reverse | Sim | Estorna liquidação parcela        | Body: `{ reason?: string, memo?: string }`                                                             | Liquidação estornada           | 400 Validação, 404     |
+| PATCH  | /finance/settlements/:id/reverse                             | Sim   | Estorna liquidação por id         | Body: `{ reason?: string, memo?: string }`                                                             | Liquidação estornada           | 400 Validação, 404     |
+| DELETE | /finance/bank-reconciliations/:id                            | Sim   | Desfaz conciliação bancária       | -                                                                                                     | Conciliação desfeita           | 404 Not Found          |
+| PATCH  | /finance/accounts-payable/installments/:id/tags              | Sim   | Atualiza tags da parcela           | Body: `{ tag_ids?: number[] }`                                                                          | Tags atualizadas               | 400 Validação, 404     |
+| POST   | /finance/accounts-payable/installments/extract-from-file    | Sim   | Extrai dados de título de arquivo | Multipart file + Body: `{ file_id?: number }`                                                          | Dados extraídos               | 400 Validação          |
+| GET    | /finance/accounts-receivable/installments                    | Sim   | Lista parcelas contas a receber   | Query: `status`, paginação                                                                             | Lista paginada                  | 401 Unauthorized      |
+| GET    | /finance/accounts-receivable/installments/:id                | Sim   | Detalha parcela contas a receber  | Path param: `id`                                                                                       | Detalhes da parcela             | 404 Not Found          |
+| POST   | /finance/accounts-receivable/installments                    | Sim   | Cria título contas a receber      | Body: `CreateFinancialTitleDto`                                                                        | Título criado                  | 400 Validação         |
+| PATCH  | /finance/accounts-receivable/installments/:id                | Sim   | Atualiza título contas a receber  | Body: `CreateFinancialTitleDto`                                                                        | Título atualizado              | 400 Validação, 404     |
+| PATCH  | /finance/accounts-receivable/installments/:id/approve        | Sim   | Aprova título contas a receber    | -                                                                                                     | Título aprovado               | 404 Not Found          |
+| PATCH  | /finance/accounts-receivable/installments/:id/cancel         | Sim   | Cancela título contas a receber   | Body: `{ reason?: string }`                                                                             | Título cancelado              | 400 Validação, 404     |
+| POST   | /finance/accounts-receivable/installments/:id/settlements    | Sim   | Registra liquidação parcela       | Body: dados de liquidação (ver DTO SettleInstallmentDto)                                               | Liquidação registrada          | 400 Validação, 404     |
+| PATCH  | /finance/accounts-receivable/installments/:id/settlements/:settlementId/reverse | Sim | Estorna liquidação parcela        | Body: `{ reason?: string, memo?: string }`                                                             | Liquidação estornada           | 400 Validação, 404     |
+| PATCH  | /finance/accounts-receivable/installments/:id/tags            | Sim   | Atualiza tags da parcela           | Body: `{ tag_ids?: number[] }`                                                                          | Tags atualizadas               | 400 Validação, 404     |
+| POST   | /finance/tags                                                | Sim   | Cria tag financeira                | Body: `{ name: string, color?: string }`                                                              | Tag criada                    | 400 Validação          |
+| POST   | /finance/accounts-receivable/installments/extract-from-file  | Sim   | Extrai dados de título de arquivo | Multipart file + Body: `{ file_id?: number }`                                                          | Dados extraídos               | 400 Validação          |
+---
+### FinancePeriodCloseController
+| Método | Path              | Auth  | Descrição                         | Parâmetros/Body                                                                                  | Resposta                         | Erros Comuns           |
+|--------|-------------------|-------|----------------------------------|-------------------------------------------------------------------------------------------------|---------------------------------|-----------------------|
+| GET    | /finance/period-close | Sim | Lista fechamentos de períodos     | Query: `search`, `status`, `user`, `from`, `to`, paginação                                      | Lista paginada                  | 401 Unauthorized      |
+| POST   | /finance/period-close | Sim | Cria fechamento de período        | Body: `{ period_start: string, period_end: string, notes?: string, status?: 'open' | 'closed' }` | Fechamento criado             | 400 Validação         |
+---
+### FinanceStatementsController
+| Método | Path                          | Auth  | Descrição                         | Parâmetros/Query/Body                                                                                  | Resposta                         | Erros Comuns           |
+|--------|-------------------------------|-------|----------------------------------|-------------------------------------------------------------------------------------------------------|---------------------------------|-----------------------|
+| GET    | /finance/statements            | Sim   | Lista extratos bancários          | Query: `bank_account_id`, `search`                                                                     | Lista de extratos               | 400 BadRequest, 401    |
+| GET    | /finance/bank-reconciliation/summary | Sim | Resumo da conciliação bancária    | Query: `bank_account_id` (obrigatório)                                                                 | Resumo da conciliação           | 400 BadRequest, 401    |
+| GET    | /finance/statements/export     | Sim   | Exporta extratos em CSV            | Query: `bank_account_id` (obrigatório), `search`                                                       | CSV para download               | 400 BadRequest, 401    |
+| POST   | /finance/statements/import     | Sim   | Importa extrato bancário           | Multipart file + Body: `bank_account_id` (obrigatório)                                                 | Importação realizada            | 400 BadRequest, 401    |
+| POST   | /finance/statements/adjustments | Sim  | Cria ajuste em extrato bancário    | Body: `{ bank_account_id: number, amount: number, date?: string, type: string, description?: string }` | Ajuste criado                   | 400 Validação, 401     |
+---
+### FinanceTransfersController
+| Método | Path              | Auth  | Descrição                         | Parâmetros/Query/Body                                                                                  | Resposta                         | Erros Comuns           |
+|--------|-------------------|-------|----------------------------------|-------------------------------------------------------------------------------------------------------|---------------------------------|-----------------------|
+| GET    | /finance/transfers | Sim   | Lista transferências              | Query: `search`, `bank_account_id`                                                                     | Lista de transferências         | 401 Unauthorized      |
+| POST   | /finance/transfers | Sim   | Cria transferência entre contas  | Body: `{ source_account_id: number, destination_account_id: number, date: string, amount: number, description?: string }` | Transferência criada            | 400 Validação         |
+---
+## 4. Regras de autenticação e autorização
+- Todos os endpoints requerem autenticação via token válido.
+- O decorator `@Role()` indica que o acesso é restrito a usuários autenticados.
+- Controle de permissões específicas deve ser implementado na camada de serviço conforme regras de negócio.
+- Usuários são identificados via decorator `@User()` para rastreabilidade.
+---
+## 5. Estruturas de request/response
+### Exemplos de DTOs principais
+- **CreateBankAccountDto**
+```ts
+{
+  bank: string; // obrigatório
+  branch?: string;
+  account?: string;
+  type: string; // obrigatório
+  description?: string;
+  initial_balance?: number; // >= 0
+}
+```
+- **CreateFinancialTitleDto**
+```ts
+{
+  document_number: string; // obrigatório
+  person_id: number; // obrigatório
+  competence_date?: string (ISO date);
+  issue_date?: string (ISO date);
+  due_date: string (ISO date); // obrigatório
+  total_amount: number; // obrigatório, >= 0.01
+  finance_category_id?: number;
+  cost_center_id?: number;
+  payment_channel?: string;
+  description?: string;
+  installments?: [
+    {
+      installment_number?: number; // >= 1
+      due_date: string (ISO date);
+      amount: number; // >= 0.01
+    }
+  ];
+  attachment_file_ids?: number[];
+}
+```
+- **SettleInstallmentDto**
+```ts
+{
+  installment_id: number; // obrigatório
+  amount: number; // obrigatório, >= 0.01
+  settled_at?: string (ISO date);
+  bank_account_id?: number;
+  bank_statement_line_id?: number;
+  payment_channel?: string;
+  discount?: number; // >= 0
+  interest?: number; // >= 0
+  penalty?: number; // >= 0
+  description?: string;
+}
+```
+- **CreateBankStatementAdjustmentDto**
+```ts
+{
+  bank_account_id: number; // obrigatório
+  amount: number; // obrigatório, >= 0.01
+  date?: string (ISO date);
+  type: string; // obrigatório
+  description?: string;
+}
+```
+- **CreateTransferDto**
+```ts
+{
+  source_account_id: number; // obrigatório
+  destination_account_id: number; // obrigatório
+  date: string; // obrigatório
+  amount: number; // obrigatório, >= 0.01
+  description?: string;
+}
+```
+---
+## 6. Erros comuns
+- **400 Bad Request**: dados inválidos ou ausentes conforme validações dos DTOs.
+- **401 Unauthorized**: ausência ou invalidez do token de autenticação.
+- **404 Not Found**: recurso não encontrado (ex.: id inválido).
+- **409 Conflict**: tentativas de duplicidade em tabelas com unicidade (ex.: tags, rateios).
+- **422 Unprocessable Entity**: violações de regras de negócio (ex.: saldo insuficiente, período fechado).
+---
+## 7. Banco de dados (tabelas YAML)
+### company_profile
+- **Finalidade:** Configurações globais financeiras (status, moeda, timezone).
+- **Colunas:**
+  - `id` (PK)
+  - `code` (string, único)
+  - `status` (enum: `active`, `inactive`)
+  - `default_currency` (string, ex: `BRL`)
+  - `timezone` (string, ex: `America/Sao_Paulo`)
+  - `created_at`, `updated_at` (timestamps)
+- **Defaults:** `status = active`
+- **Nulabilidade:** `code`, `default_currency`, `timezone` não nulos
+- **Integridade:** PK em `id`
+- **Indices:** índice único em `code`
+- **Enums:** `status`
+---
+### finance_category
+- **Finalidade:** Categorias financeiras hierárquicas.
+- **Colunas:**
+  - `id` (PK)
+  - `parent_id` (FK para self, nullable)
+  - `code` (string)
+  - `name` (string)
+  - `kind` (enum: `revenue`, `expense`, `transfer`, `adjustment`, `other`)
+  - `status` (enum: `active`, `inactive`)
+  - `created_at`, `updated_at`
+- **Defaults:** `status = active`
+- **Nulabilidade:** `parent_id` nullable
+- **Integridade:** FK para `parent_id`
+- **Indices:** índice em `code`
+- **Enums:** `kind`, `status`
+---
+### cost_center
+- **Finalidade:** Centros de custo para rateio.
+- **Colunas:**
+  - `id` (PK)
+  - `code` (string)
+  - `name` (string)
+  - `status` (enum: `active`, `inactive`)
+  - `created_at`, `updated_at`
+- **Defaults:** `status = active`
+- **Nulabilidade:** não nulo
+- **Integridade:** PK em `id`
+- **Indices:** índice em `code`
+- **Enums:** `status`
+---
+### payment_method
+- **Finalidade:** Meios de pagamento configuráveis.
+- **Colunas:**
+  - `id` (PK)
+  - `code` (string)
+  - `name` (string)
+  - `type` (enum: `pix`, `boleto`, `ted`, `doc`, `card`, `cash`, `other`)
+  - `status` (enum: `active`, `inactive`)
+  - `created_at`, `updated_at`
+- **Defaults:** `status = active`
+- **Nulabilidade:** não nulo
+- **Integridade:** PK em `id`
+- **Indices:** índice em `code`
+- **Enums:** `type`, `status`
+---
+### bank_account
+- **Finalidade:** Contas bancárias e caixas.
+- **Colunas:**
+  - `id` (PK)
+  - `code` (string)
+  - `name` (string)
+  - `bank_name` (string, nullable)
+  - `bank_code` (string, nullable)
+  - `agency` (string, nullable)
+  - `account_number` (string, nullable)
+  - `account_type` (enum: `checking`, `savings`, `investment`, `cash`, `other`)
+  - `status` (enum: `active`, `inactive`)
+  - `created_at`, `updated_at`
+- **Defaults:** `status = active`
+- **Nulabilidade:** campos bancários nullable
+- **Integridade:** PK em `id`
+- **Indices:** índice em `code`
+- **Enums:** `account_type`, `status`
+---
+### financial_title
+- **Finalidade:** Documento pai de contas a pagar/receber.
+- **Colunas:**
+  - `id` (PK)
+  - `person_id` (FK para `person.id`)
+  - `title_type` (enum: `payable`, `receivable`)
+  - `status` (enum: `draft`, `open`, `partial`, `settled`, `canceled`, `overdue`)
+  - `document_number` (string, nullable)
+  - `description` (string, nullable)
+  - `competence_date` (date, nullable)
+  - `issue_date` (date, nullable)
+  - `total_amount_cents` (integer)
+  - `finance_category_id` (FK para `finance_category.id`, nullable)
+  - `created_by_user_id` (FK para `user.id`, nullable)
+  - `created_at`, `updated_at`
+- **Defaults:** `status = draft`
+- **Nulabilidade:** campos opcionais nullable
+- **Integridade:** FK para `person`, `finance_category`, `user`
+- **Indices:** índice em `document_number`
+- **Enums:** `title_type`, `status`
+---
+### financial_installment
+- **Finalidade:** Parcelas de títulos financeiros.
+- **Colunas:**
+  - `id` (PK)
+  - `title_id` (FK para `financial_title.id`)
+  - `installment_number` (integer)
+  - `competence_date` (date)
+  - `due_date` (date)
+  - `amount_cents` (integer)
+  - `open_amount_cents` (integer)
+  - `status` (enum: `open`, `partial`, `settled`, `canceled`, `overdue`)
+  - `notes` (string, nullable)
+  - `created_at`, `updated_at`
+- **Defaults:** `status = open`
+- **Nulabilidade:** `notes` nullable
+- **Integridade:** FK para `financial_title`
+- **Indices:** índice composto em `title_id`, `installment_number`
+- **Enums:** `status`
+---
+### settlement
+- **Finalidade:** Evento financeiro real (pagamento, recebimento, transferência, ajuste).
+- **Colunas:**
+  - `id` (PK)
+  - `person_id` (FK para `person.id`, nullable)
+  - `bank_account_id` (FK para `bank_account.id`, nullable)
+  - `payment_method_id` (FK para `payment_method.id`, nullable)
+  - `settlement_type` (enum: `payable`, `receivable`, `transfer`, `adjustment`)
+  - `status` (enum: `pending`, `confirmed`, `reversed`)
+  - `settled_at` (datetime)
+  - `amount_cents` (integer)
+  - `description` (string, nullable)
+  - `external_reference` (string, nullable)
+  - `created_by_user_id` (FK para `user.id`, nullable)
+  - `created_at`, `updated_at`
+- **Defaults:** `status = pending`
+- **Nulabilidade:** campos opcionais nullable
+- **Integridade:** FK para `person`, `bank_account`, `payment_method`, `user`
+- **Indices:** índice em `settled_at`
+- **Enums:** `settlement_type`, `status`
+---
+### bank_statement
+- **Finalidade:** Lote de importação de extrato bancário.
+- **Colunas:**
+  - `id` (PK)
+  - `bank_account_id` (FK para `bank_account.id`)
+  - `source_type` (enum: `ofx`, `csv`, `manual`)
+  - `idempotency_key` (string, nullable)
+  - `period_start` (date, nullable)
+  - `period_end` (date, nullable)
+  - `imported_at` (datetime)
+  - `imported_by_user_id` (FK para `user.id`, nullable)
+  - `created_at`, `updated_at`
+- **Defaults:** -
+- **Nulabilidade:** campos opcionais nullable
+- **Integridade:** FK para `bank_account`, `user`
+- **Enums:** `source_type`
+---
+### bank_statement_line
+- **Finalidade:** Transações individuais do extrato.
+- **Colunas:**
+  - `id` (PK)
+  - `bank_statement_id` (FK para `bank_statement.id`)
+  - `bank_account_id` (FK para `bank_account.id`)
+  - `external_id` (string, nullable)
+  - `posted_date` (date)
+  - `amount_cents` (integer)
+  - `description` (string)
+  - `status` (enum: `imported`, `pending`, `reconciled`, `reversed`, `adjusted`)
+  - `dedupe_key` (string, único)
+  - `created_at`, `updated_at`
+- **Defaults:** `status = imported`
+- **Nulabilidade:** `external_id` nullable
+- **Integridade:** FK para `bank_statement`, `bank_account`
+- **Indices:** índice único em `dedupe_key`
+- **Enums:** `status`
+---
+### bank_reconciliation
+- **Finalidade:** Associação entre linha de extrato e settlement.
+- **Colunas:**
+  - `id` (PK)
+  - `bank_statement_line_id` (FK para `bank_statement_line.id`, único)
+  - `settlement_id` (FK para `settlement.id`, único)
+  - `status` (enum: `pending`, `reconciled`, `reversed`, `adjusted`)
+  - `matched_at` (datetime, nullable)
+  - `matched_by_user_id` (FK para `user.id`, nullable)
+  - `created_at`, `updated_at`
+- **Defaults:** `status = pending`
+- **Nulabilidade:** `matched_at`, `matched_by_user_id` nullable
+- **Integridade:** FK para `bank_statement_line`, `settlement`, `user`
+- **Indices:** unicidade em `bank_statement_line_id` e `settlement_id`
+- **Enums:** `status`
+---
+### audit_log
+- **Finalidade:** Registro de auditoria funcional.
+- **Colunas:**
+  - `id` (PK)
+  - `actor_user_id` (FK para `user.id`, nullable)
+  - `action` (string)
+  - `entity_table` (string)
+  - `entity_id` (string)
+  - `summary` (string, nullable)
+  - `before_data` (json, nullable)
+  - `after_data` (json, nullable)
+  - `ip_address` (string, nullable)
+  - `created_at`, `updated_at`
+- **Defaults:** -
+- **Nulabilidade:** campos opcionais nullable
+- **Integridade:** FK para `user`
+---
+### period_close
+- **Finalidade:** Controle de fechamento operacional de períodos.
+- **Colunas:**
+  - `id` (PK)
+  - `period_start` (date)
+  - `period_end` (date)
+  - `status` (enum: `open`, `closed`)
+  - `closed_at` (datetime, nullable)
+  - `closed_by_user_id` (FK para `user.id`, nullable)
+  - `notes` (string, nullable)
+  - `created_at`, `updated_at`
+- **Defaults:** `status = open`
+- **Nulabilidade:** campos opcionais nullable
+- **Integridade:** FK para `user`
+- **Enums:** `status`
+---
+### forecast_scenario
+- **Finalidade:** Cenários de planejamento financeiro.
+- **Colunas:**
+  - `id` (PK)
+  - `name` (string)
+  - `status` (enum: `active`, `inactive`)
+  - `is_default` (boolean)
+  - `created_at`, `updated_at`
+- **Defaults:** `status = active`, `is_default = false`
+- **Nulabilidade:** não nulo
+- **Enums:** `status`
+---
+### cashflow_projection
+- **Finalidade:** Projeções de fluxo de caixa.
+- **Colunas:**
+  - `id` (PK)
+  - `scenario_id` (FK para `forecast_scenario.id`)
+  - `projection_date` (date)
+  - `projection_type` (enum: `inflow`, `outflow`, `net`)
+  - `amount_cents` (integer)
+  - `notes` (string, nullable)
+  - `created_at`, `updated_at`
+- **Enums:** `projection_type`
+---
+### receivable_schedule
+- **Finalidade:** Agenda de recebíveis previstos.
+- **Colunas:**
+  - `id` (PK)
+  - `scenario_id` (FK para `forecast_scenario.id`)
+  - `person_id` (FK para `person.id`, nullable)
+  - `expected_date` (date)
+  - `amount_cents` (integer)
+  - `description` (string, nullable)
+  - `created_at`, `updated_at`
+---
+## 8. Regras de negócio relevantes
+- Valores monetários são armazenados em centavos para evitar erros de precisão.
+- Datas de competência e vencimento são separadas para análises corretas.
+- Histórico financeiro é imutável; correções são feitas via estorno ou ajuste, nunca exclusão.
+- Saldo aberto de parcelas (`open_amount_cents`) deve ser >= 0 e <= valor original.
+- Rateios e alocações devem respeitar unicidade e somatórios coerentes.
+- Períodos fechados bloqueiam operações diretas, permitindo apenas estornos sob regras.
+- Conciliações bancárias são 1:1 entre linha de extrato e settlement.
+- Auditoria é obrigatória para alterações relevantes.
+- Importação de extratos deve usar chave de deduplicação estável para evitar duplicidade.
+---
+## 9. Guia rápido de uso (exemplos)
+### Criar conta bancária
+```http
+POST /finance/bank-accounts
+Authorization: Bearer <token>
+Content-Type: application/json
+{
+  "bank": "Banco do Brasil",
+  "branch": "1234",
+  "account": "56789-0",
+  "type": "checking",
+  "description": "Conta principal",
+  "initial_balance": 100000
+}
+```
+### Criar título contas a pagar com parcelas
+```http
+POST /finance/accounts-payable/installments
+Authorization: Bearer <token>
+Content-Type: application/json
+{
+  "document_number": "FAT-2024-001",
+  "person_id": 123,
+  "due_date": "2024-07-31",
+  "total_amount": 1500.00,
+  "installments": [
+    { "installment_number": 1, "due_date": "2024-07-31", "amount": 500.00 },
+    { "installment_number": 2, "due_date": "2024-08-31", "amount": 500.00 },
+    { "installment_number": 3, "due_date": "2024-09-30", "amount": 500.00 }
+  ]
+}
+```
+### Registrar liquidação de parcela
+```http
+POST /finance/accounts-payable/installments/456/settlements
+Authorization: Bearer <token>
+Content-Type: application/json
+{
+  "installment_id": 456,
+  "amount": 500.00,
+  "settled_at": "2024-07-31T10:00:00Z",
+  "bank_account_id": 10,
+  "payment_channel": "TED",
+  "discount": 0,
+  "interest": 0,
+  "penalty": 0,
+  "description": "Pagamento via TED"
+}
+```
+### Importar extrato bancário
+```http
+POST /finance/statements/import
+Authorization: Bearer <token>
+Content-Type: multipart/form-data
+Form-data:
+- file: arquivo OFX ou CSV
+- bank_account_id: 10
+```
+### Estornar liquidação
+```http
+PATCH /finance/accounts-payable/installments/456/settlements/789/reverse
+Authorization: Bearer <token>
+Content-Type: application/json
+{
+  "reason": "Pagamento duplicado",
+  "memo": "Estorno realizado em 2024-08-01"
+}
+```
+---
+Este README foi atualizado para refletir a implementação atual do módulo financeiro `@hed-hog/finance` conforme código fonte e DTOs disponíveis.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@hed-hog/finance",
-  "version": "0.0.270",
+  "version": "0.0.274",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
@@ -9,14 +9,14 @@
     "@nestjs/core": "^11",
     "@nestjs/jwt": "^11",
     "@nestjs/mapped-types": "*",
-    "@hed-hog/contact": "0.0.270",
+    "@hed-hog/contact": "0.0.274",
     "@hed-hog/api-prisma": "0.0.5",
     "@hed-hog/api-pagination": "0.0.6",
-    "@hed-hog/tag": "0.0.270",
     "@hed-hog/api": "0.0.4",
     "@hed-hog/api-types": "0.0.1",
+    "@hed-hog/tag": "0.0.274",
     "@hed-hog/api-locale": "0.0.13",
-    "@hed-hog/core": "0.0.270"
+    "@hed-hog/core": "0.0.274"
   },
   "exports": {
     ".": {