npm package: @hed-hog/finance
Description: 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.
Latest version: 0.0.303

# Módulo Finance - Biblioteca HedHog

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. Visão geral do módulo

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. Escopo e responsabilidades

- 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.

---

## 3. Endpoints

### FinanceAuditLogsController

| 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  |

---

### FinanceBankAccountsController

| Método | Path                      | Auth | Descrição                | Parâmetros/Body                                                                                  | Resposta           | Erros Comuns          |
|--------|---------------------------|------|-------------------------|-------------------------------------------------------------------------------------------------|--------------------|----------------------|
| GET    | /finance/bank-accounts     | Sim  | Lista contas bancárias   | -                                                                                               | Lista de contas     | 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: `{ bank?: string; branch?: string; account?: string; type?: string; description?: string; status?: 'active' | 'inactive' }`       | Conta atualizada    | 400 Validação, 404   |
| DELETE | /finance/bank-accounts/:id | Sim  | Remove conta bancária    | -                                                                                               | Confirmação         | 404 Not Found        |

---

### FinanceCategoriesController

| 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: `{ name?: string; kind?: string; parent_id?: number; status?: 'active' | 'inactive' }`      | 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         | 404 Not Found        |

---

### FinanceCollectionsController

| 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   |

---

### FinanceCostCentersController

| Método | Path                      | Auth | Descrição               | Parâmetros/Body                                                                                  | Resposta           | Erros Comuns          |
|--------|---------------------------|------|------------------------|-------------------------------------------------------------------------------------------------|--------------------|----------------------|
| GET    | /finance/cost-centers     | Sim  | Lista centros de custo  | -                                                                                               | Lista de centros    | 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         | 404 Not Found        |

---

### FinanceDataController

| 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       | 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   |

---

### FinanceInstallmentsController

| 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        |
| GET    | /finance/titles/:id/settlements-history                     | Sim  | Histórico de liquidações do título| Path param: `id`                                                                                       | Histórico de liquidações   | 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: `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: `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  |
| POST   | /finance/bank-reconciliations  | Sim  | Cria conciliação bancária      | Body: `{ title_id: number; installment_id: number; bank_statement_line_id: number; payment_channel?: string; description?: string }` | Conciliação criada      | 400 Validação, 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

### CreateBankAccountDto

```ts
{
  bank: string; // obrigatório
  branch?: string;
  account?: string;
  type: string; // obrigatório
  description?: string;
  initial_balance?: number; // >= 0
}
```

### UpdateBankAccountDto

```ts
{
  bank?: string;
  branch?: string;
  account?: string;
  type?: string;
  description?: string;
  status?: 'active' | 'inactive';
}
```

### CreateFinancialTitleDto

```ts
{
  document_number: string; // obrigatório, não vazio
  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;
}
```

### RejectTitleDto

```ts
{
  reason?: string;
}
```

### ReverseSettlementDto

```ts
{
  reason?: string;
  memo?: string;
}
```

### CreateBankReconciliationDto

```ts
{
  title_id: number; // obrigatório
  installment_id: number; // obrigatório
  bank_statement_line_id: number; // obrigatório
  payment_channel?: string;
  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;
}
```

### CreateCostCenterDto

```ts
{
  name: string; // obrigatório
}
```

### UpdateCostCenterDto

```ts
{
  name?: string;
  status?: 'active' | 'inactive';
}
```

### CreateFinanceCategoryDto

```ts
{
  name: string; // obrigatório
  kind: string; // obrigatório
  parent_id?: number; // opcional
}
```

### UpdateFinanceCategoryDto

```ts
{
  name?: string;
  kind?: string;
  parent_id?: number;
  status?: 'active' | 'inactive';
}
```

### MoveFinanceCategoryDto

```ts
{
  parent_id?: number;
  position?: number;
}
```

### SendCollectionDto

```ts
{
  message: string; // obrigatório, min 5 e max 2000 caracteres
  subject?: string; // opcional, max 255 caracteres
}
```

### RegisterCollectionAgreementDto

```ts
{
  amount: number; // obrigatório, min 0.01
  installments: number; // obrigatório, entre 1 e 120
  first_due_date: string; // obrigatório, ISO date
  notes?: string; // opcional
}
```

### UpdateInstallmentTagsDto

```ts
{
  tag_ids?: number[]; // opcional, array de números únicos e >= 1
}
```

### CreatePeriodCloseDto

```ts
{
  period_start: string; // obrigatório, ISO date
  period_end: string; // obrigatório, ISO date
  notes?: string; // opcional
  status?: 'open' | 'closed'; // opcional
}
```

### ExtractFinancialTitleFromFileDto

```ts
{
  file_id?: number; // opcional
}
```

### 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;
}
```

### CreateFinanceTagDto

```ts
{
  name: string; // obrigatório, string não vazia
  color?: string; // opcional, cor hexadecimal válida
}
```

### UpdateFinanceScenarioSettingsDto

```ts
{
  atrasoMedio: number;
  taxaInadimplencia: number;
  crescimentoReceita: number;
  setAsDefault?: boolean;
}
```

---

## 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, não nulo)
  - `status` (enum: `active`, `inactive`, default `active`)
  - `default_currency` (string, não nulo, ex: `BRL`)
  - `timezone` (string, não nulo, ex: `America/Sao_Paulo`)
  - `created_at`, `updated_at` (timestamps)
- **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`, default `active`)
  - `created_at`, `updated_at`
- **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`, default `active`)
  - `created_at`, `updated_at`
- **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`, default `active`)
  - `created_at`, `updated_at`
- **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`, default `active`)
  - `created_at`, `updated_at`
- **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`, default `draft`)
  - `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`
- **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`, default `open`)
  - `notes` (string, nullable)
  - `created_at`, `updated_at`
- **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`, default `pending`)
  - `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`
- **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`
- **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`, default `imported`)
  - `dedupe_key` (string, único)
  - `created_at`, `updated_at`
- **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`, default `pending`)
  - `matched_at` (datetime, nullable)
  - `matched_by_user_id` (FK para `user.id`, nullable)
  - `created_at`, `updated_at`
- **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`
- **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`, default `open`)
  - `closed_at` (datetime, nullable)
  - `closed_by_user_id` (FK para `user.id`, nullable)
  - `notes` (string, nullable)
  - `created_at`, `updated_at`
- **Integridade:** FK para `user`
- **Enums:** `status`

---

### forecast_scenario

- **Finalidade:** Cenários de planejamento financeiro.
- **Colunas:**
  - `id` (PK)
  - `name` (string)
  - `status` (enum: `active`, `inactive`, default `active`)
  - `is_default` (boolean, default `false`)
  - `created_at`, `updated_at`
- **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
```

### Criar conciliação bancária

```http
POST /finance/bank-reconciliations
Authorization: Bearer <token>
Content-Type: application/json

{
  "title_id": 123,
  "installment_id": 456,
  "bank_statement_line_id": 789,
  "payment_channel": "PIX",
  "description": "Conciliação automática"
}
```

### 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.