Benell/Reference KPI dashboard plan.md

Weekly KPI Board V1 (Owner Dashboard + Scoped Leader View + PDF Export)

Summary

• Build a new weekly KPI visualization layer on the main dashboard using the KPI structure from PDF KPI breakdown.pdf (responsabilidad, objetivo/indicador, quantity/quality, % cumplimiento, fecha/compromiso).
• Power V1 with weekly snapshot data in Prisma (seeded from the extracted PDF rows first), exposed via internal API.
• Show full board to owner, scoped board to leader by department, and keep employee without dashboard access.
• Include a print-optimized export flow for “Save as PDF”.

Implementation Changes

• Add weekly KPI persistence models in schema.prisma:
  • WeeklyKpiSnapshot (weekStart, weekEnd, source, timestamps).
  • WeeklyKpiSection (raw section label, optional mapped DepartmentKey, owner/team labels, sort order).
  • WeeklyKpiRow (KPI text fields + parsed compliance/value fields + derived status + sort order).
• Seed initial snapshot from the PDF baseline into the week of March 16–22, 2026 (PDF creation date is March 18, 2026), preserving raw labels exactly.
• Add KPI API surface:
  • GET /api/kpis/weekly?weekStart=YYYY-MM-DD (grouped board payload with role-based scoping).
  • POST /api/kpis/weekly/ingest (upsert snapshot payload for future platform-generated data).
  • PATCH /api/kpis/weekly/rows/:id (owner + relevant leader edits for label/target/compliance text corrections).
• Update access control so /dashboard is allowed for owner and leader (leaders receive department-scoped dataset).
• Extend dashboard/page.tsx with a hybrid KPI board:
  • Header KPI summary cards (total rows, on-track %, at-risk count, due-soon count).
  • Department/section blocks with sortable table rows and visual status chips/progress bars.
  • Search + status + section filters.
• Add print export mode:
  • Print-focused dashboard route/view with A4 CSS and hidden interactive controls.
  • “Exportar PDF” button triggers print flow (window.print) for browser Save-as-PDF.

Public APIs / Interfaces / Types

• New Prisma entities: WeeklyKpiSnapshot, WeeklyKpiSection, WeeklyKpiRow.
• New shared DTOs for KPI board payload (KpiBoardResponse, KpiSectionDTO, KpiRowDTO).
• New status enum for visualization and filtering (on_track, watch, risk, no_score).
• Ingest contract supports raw text + optional parsed fields so platform integration can incrementally mature without breaking UI.

Test Plan

• Unit tests:
  • compliance/value parser from mixed text ("90%", "800,000", "PLAN 50%").
  • row status derivation and due-soon/risk classification.
• API tests:
  • authz for owner/leader/employee.
  • leader scoping returns only mapped department sections.
  • ingest upsert idempotency by (weekStart, section, row key).
• UI tests:
  • filters/sorting behavior and risk highlighting.
  • dashboard renders sectioned KPI table without text overflow.
  • print view renders cleanly in desktop/mobile and produces expected PDF layout.
• Regression checks:
  • existing non-KPI dashboard blocks still render.
  • projects/marketing routes unaffected.

Assumptions And Defaults

• Week cadence is Monday–Sunday in America/Mexico_City.
• V1 uses seeded PDF-derived data plus API-ready schema; external platform wiring uses the ingest endpoint in the next step.
• Raw PDF labels remain source of truth in V1; optional enum mapping is additive.
• Leader visibility is department-scoped only; owner is global.
• PDF export in V1 is print-layout based (not backend file rendering).