docs(okf): entidades e relacionamentos OKF do DashDescomplicar

2026-10-28 16:01:20 +00:00
parent f063a2ec8c
commit 61ae4697f9
48 changed files with 2610 additions and 0 deletions
@@ -0,0 +1,63 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, painel, financeiro, metricas]
+title: "Painel-Financeiro"
+---
+
+# Painel-Financeiro
+
+Painel de métricas financeiras do negócio Descomplicar®. Exibe receitas, despesas e lucro com gráficos de evolução e distribuição por categoria.
+
+## Responsabilidades
+
+- **Métricas Principais**: Vendas Mês, Vendas Ano, Despesas Mês, Despesas Ano, Lucro/Prejuízo
+- **Gráfico de Evolução**: Receita vs Despesa (últimos 12 meses) — Recharts BarChart
+- **Distribuição**: Despesas por categoria (pie chart visual)
+- **Formatação**: EUR com locale `pt-PT` (`formatEUR`)
+- **Estados**: Loading (pulse animation), Empty (null check), Error (console)
+
+## Stack
+
+- **React 19** + TypeScript 5.6
+- **Recharts 3**: BarChart, Bar, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer, Legend
+- **Framer Motion**: Stagger animations
+- **Lucide React**: DollarSign, TrendingUp, TrendingDown, Receipt, PiggyBank
+- **Tailwind CSS**: Glass cards, status colors (emerald para lucro, red para prejuízo)
+
+## Tipos
+
+- `FinancialData`: vendas_mes, vendas_ano, despesas_mes, despesas_ano, lucro_mes, lucro_ano, categorias[] (name, value), evolucao[] (mes, receita, despesa)
+
+## Componentes
+
+- `StatCard`: Card de métrica com label, valor formatado, ícone, cor
+- `CustomTooltip`: Tooltip do Recharts com formatação EUR
+- `formatEUR`: Conversor para locale PT-PT
+
+## API Consumida
+
+| API | Rota | Dados |
+|---|---|---|
+| Financial | `GET /api/financial` | Agregados de vendas/despesas MySQL |
+
+## Fontes de Dados (via API)
+
+- **`tblinvoices`**: Facturas (não-draft, não-canceladas) — vendas mês/ano, evolução 12 meses
+- **`tblexpenses`**: Despesas — despesas mês/ano, categorias, evolução 12 meses
+- **`tblexpenses_categories`**: JOIN para nomes de categorias
+
+## Localizações
+
+- **Código**: `src/pages/Financial.tsx` (251 linhas)
+- **Rota**: `/financial`
+
+## Dependências
+
+- **Express-API**: Rota `/api/financial`
+- **MySQL-Pool**: Dados de facturação do Desk CRM
+- **Dashboard-Engine**: Layout, navegação
+
+## Estado
+
+- Activo