fix(financeiro): alinhar saldo, métricas e relatórios

src/features/dashboard/components/dashboard-metrics-cards.tsx

@@ -7,6 +7,7 @@ import {
 	RiScalesLine,
 	RiSubtractLine,
 } from "@remixicon/react";
+import { MetricsCardInfoButton } from "@/features/dashboard/components/metrics-card-info-button";
 import type { DashboardCardMetrics } from "@/features/dashboard/dashboard-metrics-queries";
 import MoneyValues from "@/shared/components/money-values";
 import {
@@ -36,6 +37,14 @@ const CARDS = [
 		icon: RiArrowDownLine,
 		invertTrend: false,
 		iconClass: "text-success",
+		helpTitle: "Como calculamos receitas",
+		helpLines: [
+			"Somamos os lançamentos do tipo Receita no período selecionado.",
+			"Consideramos lançamentos efetivados e não efetivados do pagador principal (admin).",
+			"Movimentações de contas marcadas como não consideradas no saldo total ficam fora deste card.",
+			"Não entram transferências internas nem lançamentos automáticos de fatura.",
+			"Saldo inicial também fica fora quando a conta está marcada para desconsiderá-lo das receitas.",
+		],
 	},
 	{
 		label: "Despesas",
@@ -44,14 +53,29 @@ const CARDS = [
 		icon: RiArrowUpLine,
 		invertTrend: true,
 		iconClass: "text-destructive",
+		helpTitle: "Como calculamos despesas",
+		helpLines: [
+			"Somamos os lançamentos do tipo Despesa no período selecionado.",
+			"Consideramos lançamentos efetivados e não efetivados do pagador principal (admin).",
+			"Movimentações de contas marcadas como não consideradas no saldo total ficam fora deste card.",
+			"Não entram transferências internas nem lançamentos automáticos de fatura.",
+			"O valor mostrado é a saída efetiva do período, sempre em número positivo no card.",
+		],
 	},
 	{
 		label: "Balanço",
-		subtitle: "Receitas menos despesas",
+		subtitle: "Receitas, despesas e ajustes entre contas",
 		key: "balanco",
 		icon: RiScalesLine,
 		invertTrend: false,
 		iconClass: "text-warning",
+		helpTitle: "Como calculamos o balanço",
+		helpLines: [
+			"Partimos de receitas menos despesas do período.",
+			"Receitas e despesas de contas marcadas como não consideradas no saldo total ficam fora do cálculo base.",
+			"Depois aplicamos ajustes de transferências entre contas consideradas e não consideradas no saldo total.",
+			"Se a transferência entra em conta considerada, soma. Se sai de conta considerada para conta não considerada, subtrai.",
+		],
 	},
 	{
 		label: "Previsto",
@@ -60,6 +84,13 @@ const CARDS = [
 		icon: RiCalendarCheckLine,
 		invertTrend: false,
 		iconClass: "text-cyan-600",
+		helpTitle: "Como calculamos o previsto",
+		helpLines: [
+			"Acumulamos o balanço mês a mês até o período atual.",
+			"Ele usa a mesma regra do card de balanço em cada mês do histórico.",
+			"Receitas e despesas de contas marcadas como não consideradas no saldo total ficam fora desse acumulado.",
+			"Por isso também reflete ajustes de transferências entre contas consideradas e não consideradas.",
+		],
 	},
 ] as const;
 
@@ -104,7 +135,16 @@ export function DashboardMetricsCards({ metrics }: DashboardMetricsCardsProps) {
 	return (
 		<div className="grid grid-cols-1 gap-3 @xl/main:grid-cols-2 @5xl/main:grid-cols-4">
 			{CARDS.map(
-				({ label, subtitle, key, icon: Icon, invertTrend, iconClass }) => {
+				({
+					label,
+					subtitle,
+					key,
+					icon: Icon,
+					invertTrend,
+					iconClass,
+					helpTitle,
+					helpLines,
+				}) => {
 					const metric = metrics[key];
 					const trend = getTrend(metric.current, metric.previous);
 					const TrendIcon = TREND_ICONS[trend];
@@ -119,9 +159,14 @@ export function DashboardMetricsCards({ metrics }: DashboardMetricsCardsProps) {
 							<CardHeader>
 								<div className="flex items-start justify-between">
 									<div>
-										<CardTitle className="flex items-center gap-1 tracking-tight">
+										<CardTitle className="flex items-center gap-1.5 tracking-tight">
 											<Icon className={cn("size-4", iconClass)} aria-hidden />
 											{label}
+											<MetricsCardInfoButton
+												label={label}
+												helpTitle={helpTitle}
+												helpLines={helpLines}
+											/>
 										</CardTitle>
 										<CardDescription className="mt-1.5 tracking-tight">
 											{subtitle}