PRD: Panel financiero v2 — una quincena, gauge semicircular, sidebar presupuesto

[Jorg3L3on]

PRD: Panel financiero v2 — una quincena, gauge compacto, sidebar presupuesto

Status: Published for agent implementation
Target surface: /monthly/[year]/[month] (Panel financiero mensual)
Reference mock: attached ChatGPT mock (Jun 2026) — semi-circular gauge, hero “Disponible para gastar”, right “Presupuesto del mes” column

---

Problem Statement

Household users plan money in fortnights, but the current Panel financiero after the first UI pass still feels sparse, visually uneven, and operationally heavier than the target design. The full-ring income chart leaves dead space; the summary stacks three equal columns instead of emphasizing Disponible para gastar. Users can still switch to “Ambas quincenas”, which splits attention across two columns and duplicates chrome—while the product direction is now one fortnight at a time only. There is no at-a-glance monthly budget context beside the fortnight plan, even though budgets exist elsewhere in the app.

Solution

Redesign the Panel financiero as a single-fortnight-first experience: tighter vertical rhythm, a semi-circular income-commitment gauge (percent of fortnight income already committed via paid + pending expenses), a hero metric for Disponible para gastar with secondary Ingresos / Efectivo neto en cuentas, and an optional right sidebar for Presupuesto del mes (category breakdown). Remove dual-fortnight layout entirely and simplify controls to quincena selector only (1ª / 2ª).

User Stories

1. As a house member, I want to see only one fortnight at a time on the Panel financiero, so that I focus on the period I am planning without scanning two columns.
2. As a house member, I want to switch between 1ª and 2ª quincena with clear controls, so that I can plan each half-month without a separate “view both” mode.
3. As a house member, I want a compact gauge showing what share of my fortnight income is already committed, so that I understand pressure on my plan at a glance.
4. As a house member, I want Disponible para gastar to be the dominant number in the summary, so that I immediately see what remains after planned expenses.
5. As a house member, I want Ingresos del periodo and Efectivo neto en cuentas as supporting figures, so that I can reconcile income, plan, and cash positions without equal-weight clutter.
6. As a house member, I want less empty padding in the summary card, so that the panel feels dense and purposeful on desktop and mobile.
7. As a house member, I want the income gauge to reflect fortnight income (not catalog budgets), so that the chart matches how I think about “what I earned this quincena vs what I already allocated.”
8. As a house member, I want the gauge hidden or replaced with a clear empty state when fortnight income is zero, so that I am not misled by a 0% ring.
9. As a house member, I want to see Presupuesto del mes in a sidebar with total, used/available bar, and top categories, so that monthly budget context sits beside fortnight execution.
10. As a house member, I want the monthly budget sidebar to respect owner context (user vs house), so that numbers match the rest of the app.
11. As a house member, I want wallet balances and expense tabs (Gastos, Pagos tarjeta, Préstamos) to remain fully functional, so that this redesign does not regress planning workflows.
12. As a house member, I want summary expand/collapse to still show detailed breakdown (pagado, pendiente, ingresos por fuente, cargos TC, billeteras vs pendiente), so that power users keep depth on demand.
13. As a house member, I want table density and “mostrar resumen” preferences to persist per month/owner, so that my choices are remembered.
14. As a mobile user, I want the gauge placed efficiently (above metrics, compact height), so that I do not scroll through empty space before acting.
15. As a desktop user, I want the gauge beside the hero metrics in one card, so that the layout matches the reference mock proportions.
16. As a user returning after the change, I want any previous “Ambas quincenas” preference migrated to single-fortnight view, so that I am not stuck on a removed layout.
17. As a developer, I want gauge math centralized in a small pure module, so that percent committed is tested independently of SVG rendering.
18. As a developer, I want Playwright smoke on the monthly panel to assert gauge copy, single-fortnight controls, and absence of “Ambas”, so that regressions are caught in CI locally.

Implementation Decisions

Product / UX

• Remove layout mode both and all UI for “Ambas” / “Una quincena” period toggle; only Quincena: 1ª (1–15) | 2ª (16–fin) remains in chrome (plus existing options menu for resumen visible + table density).
• Keep month selector card full container width; keep fortnight content max-w-* constraint as today (user explicitly declined unifying widths).
• Summary card — collapsed (default) layout:
  • One outer card; two compact sub-boxes under the hero (per mock), not three equal-width columns.
  • Left: semi-circular 180° gauge (gradient stroke primary/violet), center {n}% + “del ingreso”.
  • Right: Disponible para gastar as dominant amount (gradient text emphasis per mock); below, sub-boxes for Ingresos del periodo and Dinero en cuentas (dot accent + amount each).
  • Tight padding; no full-circle gauge.
• Gauge metric (unchanged business rule from prior agreement):
  percentCommitted = round((pagado + pendiente) / ingresosDelPeriodo * 100); clamp display arc at 100% but allow label to show >100 if over-committed; hide gauge when ingresosDelPeriodo <= 0.
• Expanded summary: retain current detailed blocks (colored cards/lists) — no flattening in expand state.

Page layout

• Desktop (xl+): CSS grid — main column (~2fr) + Presupuesto del mes sidebar (~1fr, min width ~280px). Main column order: wallets strip → quincena controls → single FortnightColumn → (existing tabs/table).
• Below xl: sidebar stacks below main column OR collapses into a collapsible section — default: stack below to avoid hiding budget on tablet; document choice in implementation (prefer stack for v1).

Modules (deep / testable)

Module	Responsibility
fortnight-income-commitment (existing)	Pure percent + edge cases
FortnightIncomeGauge (new, replaces ring)	Semi-circular SVG; props: percent, periodIncome; no data fetching
FortnightSummaryHero (new)	Composes gauge + hero metrics; props from fortnight summary DTO
MonthlyBudgetSidebar (new)	Client presentation; props: monthly budget aggregate DTO
monthly-budget-panel.service (new, server)	Resolve owner-scoped monthly budget total, spent, by category for calendar month
MonthlyFortnightView (modify)	Drop layout state, both grid, dual headers; render one column
FortnightViewControls (modify)	Remove Período group and layout callbacks
SummaryBlock (modify)	Delegate collapsed hero to FortnightSummaryHero or inline refactor; shrink padding

Data / API

• Fortnight summary: continue getReportSummary / existing fortnight bundle per period; no budget fields on summary.
• Monthly budget sidebar: new read endpoint or server loader field on monthly page, e.g. GET /api/monthly/[year]/[month]/budget-panel returning:
  • totalBudget, spent, available
  • categories: { id, name, icon?, spent, percentOfBudget, accent? }[] (top 5–6, ordered by spent desc)
  • Empty state when no active budgets for month
• Sidebar UI sections (mock): heading “Presupuesto del mes”, total amount, gradient bar with $ usado / $ disponible captions; heading “Top categorías”; rows with icon + name + amount + % + mini bar; Ver reporte completo button.
• Reuse budget period logic where possible (Budget, BudgetPeriod, allocations); align spent definition with budgets page (document in service).
• All queries scoped with ownerFilter from getOwnerContext.

Persistence / migration

• Stop reading/writing micasa.planificacion.layout; on hydrate, ignore stored both → treat as single.
• Keep micasa.planificacion.period:{scope} for 1ª/2ª.
• Keep summary visible + table density keys.

Header chrome (required for mock parity)

• Month row: Cambiar periodo (month picker / nav pattern) and Filtros (consolidated view filters menu) beside title area, in addition to prev/next arrows and badge Actual.
• Breadcrumbs Inicio > {Mes año} optional if shell already provides equivalent context.

Visual system

• Follow fintech tokens: font-mono tabular-nums for money; calm card shells; gauge gradient acceptable on stroke only (not full panel tint increase).
• Playwright script update: assert no “Ambas”, assert “del ingreso” on gauge, screenshot desktop/mobile.

Architectural

• FortnightColumn dualColumnLayout prop becomes unused — remove.
• /fortnight/[year]/[month]/[period] may keep current SummaryBlock or later align to hero layout — out of scope unless trivial reuse of FortnightSummaryHero.

Testing Decisions

• Good tests: pure functions (percent committed), gauge clamp/empty state, migration helper for layout preference; service tests for monthly budget aggregation with fixture data (similar to loan.service.test.ts / budget helpers).
• Modules tested: fortnight-income-commitment, FortnightIncomeGauge (render percent → stroke offset or aria-label), monthly-budget-panel.service, layout migration util.
• Not required: pixel-perfect SVG snapshot tests; Playwright remains manual/CI optional script.
• Prior art: fortnight-income-commitment.test.ts, fortnight-summary-header.test.ts, scripts/playwright-panel-financiero.sh, budgets page ProgressBar patterns.

Out of Scope

• Changing month header card width to match fortnight column.
• Redesigning wallet carousel cards or expense row UI (beyond spacing tweaks).
• Replacing Radix charts library / adding Recharts for sidebar (CSS bars acceptable v1).
• Fortnight detail route (/fortnight/...) full layout parity with mock.
• Budget editing/creation from sidebar (read-only panel + link via Ver reporte completo only).
• Liquidity projection or dashboard Inicio changes.
• Removing second fortnight data from server — still fetch both summaries for fast period switch; only render one.

Visual parity checklist (reference mock — Jun 2026)

Implementation must match the shared mockup layout and hierarchy. Copy differences noted where business rules override design text.

Mock region	Required UI	Issue
Month header	Title “{Mes} {Año}”, subtitle “Panel financiero mensual”, badge Actual, prev/next month, buttons Cambiar periodo + Filtros	#91
Wallet strip	Horizontal account cards (balances, Pagada on cards when applicable)	existing (no regression)
Resumen card	Title + date range; semi-circular gauge left; right: hero Disponible para gastar (largest, gradient emphasis); two compact sub-boxes below: Ingresos del periodo + Dinero en cuentas (colored dot per metric)	#88
Gauge center	{n}% + label del ingreso (mock shows “del presupuesto usado” — use ingreso per product)	#88
Right column	Section Presupuesto del mes: total budget amount, gradient progress bar, labels $X usado / $Y disponible	#89
Right column	Section Top categorías: rows with icon, name, spent amount, % of budget, thin per-category progress bar (e.g. Alimentos, Transporte, Servicios, Entretenimiento, Otros)	#89
Right column	Footer CTA Ver reporte completo (chart icon) → budgets/report route	#89
Page grid	Desktop: main column (~2fr) + right sidebar (~1fr) beside summary/transactions; mobile: stack	#89
Fortnight scope	One quincena only (no Ambas); 1ª/2ª toggle remains	#87
Transactions	Tabs Gastos / Pagos tarjeta / Préstamos, + Agregar gasto, table with status chips	existing (no regression)

Further Notes

• Supersedes visual direction from Notion/doc “Panel financiero — reestructuración UI/UX” where gauge depended on BIWEEKLY budgets; income-commitment gauge is canonical.
• Branch feat/panel-financiero-ui-restructure contains v1 work; v2 can continue on same feature branch or feat/panel-financiero-v2.
• Mock copy “del presupuesto usado” is incorrect for MiCasa; use “del ingreso” / “comprometido del ingreso de la quincena”.
• Collapsed summary uses two small sub-boxes under the hero (per mock), not three equal columns or heavy nested cards.

[Jorg3L3on]

Slice issues (vertical)

#	Title	Blocked by
#87	Solo una quincena (eliminar vista Ambas)	—
#88	Gauge semicircular + resumen compacto	#87
#89	Sidebar Presupuesto del mes (API + UI)	—
#90	Playwright smoke v2	#87, #88, #89

Suggested integration branch: feat/panel-financiero-v2

[Jorg3L3on]

Revisión vs mock (Jun 2026)

Actualicé el PRD y los slices para paridad visual con la imagen compartida.

Elemento del mock	Issue
Gauge semicircular + % del ingreso	#88
Hero Disponible + sub-cajas Ingresos / Dinero en cuentas	#88
Presupuesto del mes (total, barra, $ usado / disponible)	#89
Top categorías (%, barra por fila)	#89
Ver reporte completo	#89
Grid main + sidebar	#89
Solo una quincena (sin Ambas)	#87
Cambiar periodo + Filtros en header	#91 (nuevo)
Smoke E2E	#90

Nota de copy: el mock dice “del presupuesto usado”; en producto seguimos “del ingreso” (compromiso de ingreso de la quincena).

Checklist completo en tasks/prd-panel-financiero-v2.md → sección Visual parity checklist.

[Jorg3L3on]

Ship-feature — implementado en feat/panel-financiero-v2

Slices #87–#91 y #90 implementados en un commit de integración (cbbc25c) y pusheados a la rama de feature.

Preview: merge de slices = código en feat/panel-financiero-v2 (sin PRs individuales por slice; mismo resultado en la rama de integración).

Release PR feat/panel-financiero-v2 → main abierto para revisión; no mergeado a main (según instrucción).

Verificar local: npm run dev + bash scripts/playwright-panel-financiero.sh