merca y ch

Reference KPI dashboard plan.md

@@ -0,0 +1,55 @@
+### 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](/home/mdares03/benell/prisma/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](/home/mdares03/benell/src/app/(app)/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).