@hed-hog/finance 0.0.276 → 0.0.279

package/README.md

@@ -133,6 +133,7 @@ O módulo financeiro gerencia o ciclo completo da gestão financeira corporativa
 |--------|-------------------------------|------|-------------------------------|-------------------------------------------------------------------------------------------------------|------------------------|----------------------|
 | 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   |
@@ -244,6 +245,18 @@ O módulo financeiro gerencia o ciclo completo da gestão financeira corporativa
 }
 ```
 
+### 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
@@ -256,24 +269,20 @@ O módulo financeiro gerencia o ciclo completo da gestão financeira corporativa
 }
 ```
 
-### CreateTransferDto
+### CreateCostCenterDto
 
 ```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;
+  name: string; // obrigatório
 }
 ```
 
-### CreateFinanceTagDto
+### UpdateCostCenterDto
 
 ```ts
 {
-  name: string; // obrigatório, string não vazia
-  color?: string; // opcional, cor hexadecimal válida
+  name?: string;
+  status?: 'active' | 'inactive';
 }
 ```
 
@@ -307,23 +316,6 @@ O módulo financeiro gerencia o ciclo completo da gestão financeira corporativa
 }
 ```
 
-### CreateCostCenterDto
-
-```ts
-{
-  name: string; // obrigatório
-}
-```
-
-### UpdateCostCenterDto
-
-```ts
-{
-  name?: string;
-  status?: 'active' | 'inactive';
-}
-```
-
 ### SendCollectionDto
 
 ```ts
@@ -371,6 +363,38 @@ O módulo financeiro gerencia o ciclo completo da gestão financeira corporativa
 }
 ```
 
+### 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
@@ -750,6 +774,22 @@ Form-data:
 - 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

package/hedhog/data/menu.yaml

@@ -322,6 +322,52 @@
       - where:
           slug: admin-finance
 
+- menu_id:
+    where:
+      slug: /finance/reports
+  icon: chart-no-axes-combined
+  url: /finance/reports/overview-results
+  name:
+    en: Results Overview
+    pt: Visão Geral dos Resultados
+  slug: /finance/reports/overview-results
+  relations:
+    role:
+      - where:
+          slug: admin
+      - where:
+          slug: admin-finance
+- menu_id:
+    where:
+      slug: /finance/reports
+  icon: chart-bar-big
+  url: /finance/reports/top-customers
+  name:
+    en: Top Customers
+    pt: Principais Clientes
+  slug: /finance/reports/top-customers
+  relations:
+    role:
+      - where:
+          slug: admin
+      - where:
+          slug: admin-finance
+- menu_id:
+    where:
+      slug: /finance/reports
+  icon: chart-pie
+  url: /finance/reports/top-operational-expenses
+  name:
+    en: Top Operational Expenses
+    pt: Principais Gastos Operacionais
+  slug: /finance/reports/top-operational-expenses
+  relations:
+    role:
+      - where:
+          slug: admin
+      - where:
+          slug: admin-finance
+
 - menu_id:
     where:
       slug: /finance

package/hedhog/frontend/app/reports/_lib/report-aggregations.ts.ejs

@@ -0,0 +1,275 @@
+import {
+  customerRevenueMock,
+  financialResultsMock,
+  operationalExpensesMock,
+  type GroupBy,
+} from './report-mocks';
+
+const dateFormatter = new Intl.DateTimeFormat('pt-BR');
+
+function toDate(value: string) {
+  return new Date(`${value}T00:00:00`);
+}
+
+function isWithinRange(date: string, from: string, to: string) {
+  return date >= from && date <= to;
+}
+
+function startOfWeek(date: Date) {
+  const current = new Date(date);
+  const day = current.getDay();
+  const diff = day === 0 ? -6 : 1 - day;
+  current.setDate(current.getDate() + diff);
+  current.setHours(0, 0, 0, 0);
+
+  return current;
+}
+
+function getIsoWeek(date: Date) {
+  const current = new Date(
+    Date.UTC(date.getFullYear(), date.getMonth(), date.getDate())
+  );
+  const dayNum = current.getUTCDay() || 7;
+  current.setUTCDate(current.getUTCDate() + 4 - dayNum);
+  const yearStart = new Date(Date.UTC(current.getUTCFullYear(), 0, 1));
+
+  return Math.ceil(
+    ((current.getTime() - yearStart.getTime()) / 86400000 + 1) / 7
+  );
+}
+
+function getBucketKey(date: string, groupBy: GroupBy) {
+  const d = toDate(date);
+
+  if (groupBy === 'day') {
+    return date;
+  }
+
+  if (groupBy === 'week') {
+    const weekStart = startOfWeek(d);
+    const isoWeek = getIsoWeek(weekStart);
+    return `${weekStart.getFullYear()}-W${String(isoWeek).padStart(2, '0')}`;
+  }
+
+  if (groupBy === 'month') {
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+  }
+
+  return String(d.getFullYear());
+}
+
+export function formatBucketLabel(bucket: string, groupBy: GroupBy) {
+  if (groupBy === 'day') {
+    return dateFormatter.format(toDate(bucket));
+  }
+
+  if (groupBy === 'week') {
+    const [year, week] = bucket.split('-W');
+    return `Sem ${Number(week)}/${year}`;
+  }
+
+  if (groupBy === 'month') {
+    const [year, month] = bucket.split('-');
+    return `${month}/${year}`;
+  }
+
+  return bucket;
+}
+
+function sortBuckets(a: string, b: string, groupBy: GroupBy) {
+  if (groupBy === 'year' || groupBy === 'month' || groupBy === 'day') {
+    return a.localeCompare(b);
+  }
+
+  const [aYear, aWeek] = a.split('-W');
+  const [bYear, bWeek] = b.split('-W');
+  const yearDiff = Number(aYear) - Number(bYear);
+
+  if (yearDiff !== 0) {
+    return yearDiff;
+  }
+
+  return Number(aWeek) - Number(bWeek);
+}
+
+export function aggregateOverview(params: {
+  from: string;
+  to: string;
+  groupBy: GroupBy;
+}) {
+  const { from, to, groupBy } = params;
+  const grouped = new Map<
+    string,
+    {
+      period: string;
+      label: string;
+      faturamento: number;
+      despesasEmprestimos: number;
+      diferenca: number;
+      aporteInvestidor: number;
+      emprestimoBanco: number;
+      despesas: number;
+    }
+  >();
+
+  for (const item of financialResultsMock) {
+    if (!isWithinRange(item.date, from, to)) {
+      continue;
+    }
+
+    const bucket = getBucketKey(item.date, groupBy);
+    const current = grouped.get(bucket) || {
+      period: bucket,
+      label: formatBucketLabel(bucket, groupBy),
+      faturamento: 0,
+      despesasEmprestimos: 0,
+      diferenca: 0,
+      aporteInvestidor: 0,
+      emprestimoBanco: 0,
+      despesas: 0,
+    };
+
+    current.faturamento += item.faturamento;
+    current.aporteInvestidor += item.aporteInvestidor;
+    current.emprestimoBanco += item.emprestimoBanco;
+    current.despesas += item.despesas;
+    current.despesasEmprestimos += item.despesas + item.emprestimoBanco;
+    current.diferenca = current.faturamento - current.despesasEmprestimos;
+
+    grouped.set(bucket, current);
+  }
+
+  return Array.from(grouped.values()).sort((a, b) =>
+    sortBuckets(a.period, b.period, groupBy)
+  );
+}
+
+export function aggregateTopCustomers(params: {
+  from: string;
+  to: string;
+  groupBy: GroupBy;
+  topN?: number;
+}) {
+  const { from, to, groupBy, topN = 20 } = params;
+
+  const byCustomer = new Map<string, number>();
+  const byBucket = new Map<string, number>();
+
+  for (const item of customerRevenueMock) {
+    if (!isWithinRange(item.date, from, to)) {
+      continue;
+    }
+
+    const current = byCustomer.get(item.customer) || 0;
+    byCustomer.set(item.customer, current + item.value);
+
+    const bucket = getBucketKey(item.date, groupBy);
+    const currentBucket = byBucket.get(bucket) || 0;
+    byBucket.set(bucket, currentBucket + item.value);
+  }
+
+  const sorted = Array.from(byCustomer.entries())
+    .map(([customer, value]) => ({ customer, value }))
+    .sort((a, b) => b.value - a.value);
+
+  const topCustomers = sorted.slice(0, topN);
+  const total = sorted.reduce((acc, row) => acc + row.value, 0);
+  const top5 = topCustomers
+    .slice(0, 5)
+    .reduce((acc, row) => acc + row.value, 0);
+
+  const pieData = topCustomers.slice(0, 9);
+  const othersValue = sorted.slice(9).reduce((acc, row) => acc + row.value, 0);
+
+  if (othersValue > 0) {
+    pieData.push({ customer: 'Outros', value: othersValue });
+  }
+
+  const groupedPeriods = Array.from(byBucket.entries())
+    .map(([period, value]) => ({
+      period,
+      label: formatBucketLabel(period, groupBy),
+      value,
+    }))
+    .sort((a, b) => sortBuckets(a.period, b.period, groupBy));
+
+  return {
+    total,
+    top5,
+    top5Percent: total > 0 ? (top5 / total) * 100 : 0,
+    topCustomers,
+    pieData,
+    groupedPeriods,
+  };
+}
+
+export function aggregateOperationalExpenses(params: {
+  from: string;
+  to: string;
+  groupBy: GroupBy;
+  topN?: number;
+}) {
+  const { from, to, groupBy, topN = 20 } = params;
+
+  const byCategory = new Map<
+    string,
+    { category: string; costCenter: string; value: number }
+  >();
+  const byCostCenter = new Map<string, number>();
+  const byBucket = new Map<string, number>();
+
+  for (const item of operationalExpensesMock) {
+    if (!isWithinRange(item.date, from, to)) {
+      continue;
+    }
+
+    const currentCategory = byCategory.get(item.category) || {
+      category: item.category,
+      costCenter: item.costCenter,
+      value: 0,
+    };
+
+    currentCategory.value += item.value;
+    byCategory.set(item.category, currentCategory);
+
+    const currentCenter = byCostCenter.get(item.costCenter) || 0;
+    byCostCenter.set(item.costCenter, currentCenter + item.value);
+
+    const bucket = getBucketKey(item.date, groupBy);
+    const currentBucket = byBucket.get(bucket) || 0;
+    byBucket.set(bucket, currentBucket + item.value);
+  }
+
+  const sorted = Array.from(byCategory.values()).sort(
+    (a, b) => b.value - a.value
+  );
+  const topExpenses = sorted.slice(0, topN);
+  const total = sorted.reduce((acc, item) => acc + item.value, 0);
+
+  const pieData = Array.from(byCostCenter.entries()).map(([name, value]) => ({
+    name,
+    value,
+  }));
+
+  const groupedPeriods = Array.from(byBucket.entries())
+    .map(([period, value]) => ({
+      period,
+      label: formatBucketLabel(period, groupBy),
+      value,
+    }))
+    .sort((a, b) => sortBuckets(a.period, b.period, groupBy));
+
+  return {
+    total,
+    topExpenses,
+    pieData,
+    groupedPeriods,
+  };
+}
+
+export function getDefaultDateRange() {
+  return {
+    from: '2021-01-01',
+    to: '2026-12-31',
+  };
+}

package/hedhog/frontend/app/reports/_lib/report-mocks.ts.ejs

@@ -0,0 +1,186 @@
+export type GroupBy = 'day' | 'week' | 'month' | 'year';
+
+export interface FinancialResultEntry {
+  date: string;
+  faturamento: number;
+  emprestimoBanco: number;
+  aporteInvestidor: number;
+  despesas: number;
+}
+
+export interface CustomerRevenueEntry {
+  date: string;
+  customer: string;
+  value: number;
+}
+
+export interface OperationalExpenseEntry {
+  date: string;
+  category: string;
+  costCenter: string;
+  value: number;
+}
+
+const customerNames = [
+  'VALE',
+  'CALIAN',
+  'ALURA',
+  'FIAP',
+  'UDEMY',
+  'HIREWORK',
+  'PAULO DE TARSO',
+  'BRCLICK',
+  'DISTRITO',
+  'COINBIT CLUB',
+  'IT GLOBAL',
+  'INFINITY LEGACY',
+  'XFX',
+  'CLASS',
+  'IMPACTA',
+  'AFX',
+  'SOLARIUM',
+  'ADVANCED RESOURCES',
+  'BMX SCHOOL',
+  'CODE NATION',
+  'NEXT LEVEL',
+  'MEGA TECH',
+  'EDU PRO',
+  'CONECTA BR',
+  'SABER MAIS',
+];
+
+const topCustomerMultipliers: Record<string, number> = {
+  VALE: 4.5,
+  CALIAN: 2.4,
+  ALURA: 1.65,
+  FIAP: 1.45,
+};
+
+const expenseCategories = [
+  { category: 'Folha de Pagamento', costCenter: 'Pessoas', weight: 4.6 },
+  { category: 'Marketing', costCenter: 'Comercial', weight: 3.4 },
+  { category: 'Tecnologia SaaS', costCenter: 'TI', weight: 3.1 },
+  { category: 'Infraestrutura Cloud', costCenter: 'TI', weight: 2.8 },
+  {
+    category: 'Jurídico e Compliance',
+    costCenter: 'Administrativo',
+    weight: 2.1,
+  },
+  {
+    category: 'Facilities e Escritório',
+    costCenter: 'Administrativo',
+    weight: 1.9,
+  },
+  { category: 'Treinamentos', costCenter: 'Pessoas', weight: 1.7 },
+  { category: 'Viagens e Eventos', costCenter: 'Comercial', weight: 1.5 },
+  { category: 'Suporte ao Cliente', costCenter: 'Operações', weight: 2.0 },
+  {
+    category: 'Ferramentas Financeiras',
+    costCenter: 'Financeiro',
+    weight: 1.3,
+  },
+  { category: 'Consultorias', costCenter: 'Operações', weight: 1.2 },
+  { category: 'Seguros', costCenter: 'Financeiro', weight: 0.9 },
+];
+
+function clamp(value: number, min: number, max: number) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function monthSeed(year: number, monthIndex: number) {
+  return year * 17 + monthIndex * 31;
+}
+
+function buildMonthlyDates() {
+  const dates: string[] = [];
+
+  for (let year = 2021; year <= 2026; year += 1) {
+    for (let month = 1; month <= 12; month += 1) {
+      dates.push(`${year}-${String(month).padStart(2, '0')}-01`);
+    }
+  }
+
+  return dates;
+}
+
+const monthlyDates = buildMonthlyDates();
+
+export const financialResultsMock: FinancialResultEntry[] = monthlyDates.map(
+  (date, index) => {
+    const d = new Date(`${date}T00:00:00`);
+    const year = d.getFullYear();
+    const month = d.getMonth();
+    const growthFactor = 1 + (year - 2021) * 0.08;
+    const seasonality = Math.sin((month / 12) * Math.PI * 2) * 0.18;
+    const trend = 1 + index * 0.006;
+    const seed = monthSeed(year, month);
+
+    const faturamento = Math.round(
+      (260000 + seasonality * 70000 + (seed % 13) * 3500) * trend * growthFactor
+    );
+
+    const despesas = Math.round(
+      (190000 +
+        Math.cos((month / 12) * Math.PI * 2) * 45000 +
+        (seed % 7) * 4200) *
+        (0.93 + (year - 2021) * 0.035)
+    );
+
+    const emprestimoBanco =
+      month % 6 === 1 ? Math.round(22000 + (seed % 9) * 1800) : 0;
+
+    const aporteInvestidor =
+      year === 2023 && (month === 2 || month === 8)
+        ? 175000
+        : year === 2024 && month === 1
+          ? 50000
+          : year === 2025 && month === 4
+            ? 52000
+            : 0;
+
+    return {
+      date,
+      faturamento: clamp(faturamento, 120000, 530000),
+      emprestimoBanco,
+      aporteInvestidor,
+      despesas: clamp(despesas, 130000, 430000),
+    };
+  }
+);
+
+export const customerRevenueMock: CustomerRevenueEntry[] = monthlyDates.flatMap(
+  (date, monthIndex) => {
+    const dateObj = new Date(`${date}T00:00:00`);
+    const seasonal =
+      1 + Math.sin((dateObj.getMonth() / 12) * Math.PI * 2) * 0.08;
+
+    return customerNames.map((customer, index) => {
+      const base = Math.max(1800, 46000 - index * 1850);
+      const priorityBoost = topCustomerMultipliers[customer] || 1;
+      const variation = 1 + ((monthIndex + index * 3) % 9) * 0.023;
+
+      return {
+        date,
+        customer,
+        value: Math.round(base * priorityBoost * seasonal * variation),
+      };
+    });
+  }
+);
+
+export const operationalExpensesMock: OperationalExpenseEntry[] =
+  monthlyDates.flatMap((date, monthIndex) =>
+    expenseCategories.map((entry, categoryIndex) => {
+      const monthPulse = 1 + ((monthIndex + categoryIndex) % 7) * 0.04;
+      const quarterEffects = [1.04, 0.97, 1.1, 0.99] as const;
+      const quarterEffect =
+        quarterEffects[Math.floor((monthIndex % 12) / 3)] ?? 1;
+
+      return {
+        date,
+        category: entry.category,
+        costCenter: entry.costCenter,
+        value: Math.round(14000 * entry.weight * monthPulse * quarterEffect),
+      };
+    })
+  );