# PROMPT: Dashboard "Economía del Cuidado" — Análisis Empresarial (v2)

> **Cambio clave respecto a v1:** toda la agregación y los filtros de privacidad
> corren **server-side** (RPC de Postgres). El cliente NUNCA consulta `answers` crudo.
> El k-anonimato (k≥5) y la exclusión de campos sensibles son **estructurales**, no
> dependen de recordar un filtro en cada query.

---

## Contexto de negocio

Dashboard analítico de la plataforma "Datos País sobre el Cuidado" (Paraguay). Es el producto de valor para las empresas participantes: entender el impacto de las responsabilidades de cuidado en su fuerza laboral y tomar decisiones basadas en evidencia.

**Audiencia:** directores de RRHH, sostenibilidad, gerencia general de empresas paraguayas.

---

## Stack técnico

- **Frontend:** Next.js 15 (App Router), TypeScript, Tailwind CSS
- **Base de datos:** Supabase (PostgreSQL) — misma instancia que el formulario
- **Gráficos:** Recharts (ya instalado)
- **Mapa:** SVG inline de Paraguay (NO librería externa — ver Widget 1). Esto evita
  incompatibilidades de peer-deps con React 19 y no agrega dependencias (alineado con
  la política de gobernanza del método).
- **NO agregar nuevas dependencias npm.**
- **Paleta RE:** `#43BBC8` (teal), `#494F4F` (oscuro), `#F8AD13` (naranja), `#EE761A` (naranja intenso), `#E7E6E5` (gris claro), blanco

---

## ⚠️ REGLAS DE PRIVACIDAD — NO NEGOCIABLES (leer primero)

Estas reglas son del proyecto (CLAUDE.md) y tienen prioridad sobre cualquier widget.
Si un widget no puede cumplirlas, NO se construye ese widget — se reporta el conflicto.

1. **k-anonimato k≥5 por construcción.** Toda celda, barra, punto, segmento o
   departamento que represente menos de 5 respondentes se SUPRIME (se muestra como
   "Datos insuficientes" o se agrega a un grupo mayor). No es post-filtro: las funciones
   RPC ya devuelven datos con la supresión aplicada. El cliente nunca ve un N<5.
2. **`3.4` (salario) jamás sale de la base.** Protegido por RLS server-side que niega
   `question_code='3.4'` al rol usado por el dashboard. El dashboard NO usa este dato
   en ningún cálculo ni widget. No alcanza con filtrarlo en el cliente.
3. **`7.1` (texto libre) jamás llega al dashboard.** Mismo tratamiento que `3.4`:
   excluido en la capa de datos, no en el cliente.
4. **El cliente NUNCA consulta la tabla `answers` directamente.** Todo pasa por
   funciones RPC que devuelven agregados ya suprimidos. Si el browser pudiera pedir
   filas crudas, la privacidad sería inspeccionable/evitable desde la consola.

---

## Arquitectura de datos (server-side)

### Capa 1 — Funciones RPC en Postgres (Supabase)
Crear funciones SQL (`SECURITY DEFINER` con search_path fijado) que:
- Reciben `survey_id` + filtros opcionales (departamento, género, etario, contrato)
- Calculan el agregado de cada widget
- **Aplican supresión k≥5 ANTES de devolver**
- Nunca tocan `3.4` ni `7.1`
- Devuelven JSON tipado

Las funciones van en una migración nueva: `migrations/0XX_dashboard_rpc.sql`.
Listar las funciones a crear (una por widget o agrupadas por afinidad):
```
rpc_dashboard_kpis(survey_id, filters)        → KPIs + N total
rpc_prevalencia_por_depto(survey_id, filters) → mapa (con supresión por depto)
rpc_heatmap_intensidad(survey_id, filters)    → celdas con N≥5
rpc_distribucion_cuidado(survey_id, filters)  → donut
rpc_politicas_gap(survey_id, filters)         → barras (demandadas vs existentes)
rpc_score_organizacional(survey_id, filters)  → gauge
rpc_piramide_demografica(survey_id, filters)  → pirámide (celdas con N≥5)
rpc_riesgo_retencion(survey_id, filters)      → tabla (segmentos con N≥5)
rpc_intensidad_vs_productividad(survey_id, filters) → reemplazo del scatter (ver Widget 8)
```

### Capa 2 — Route Handlers (Next.js)
`app/api/dashboard/[widget]/route.ts` — llaman a las RPC con el cliente server-side
de Supabase (service_role NUNCA expuesto al browser; vive solo en el servidor).
Validan que `survey_id` exista y esté `live`.

### Capa 3 — Cliente
Los componentes hacen `fetch('/api/dashboard/...')`. Reciben datos ya agregados y
ya suprimidos. No tienen acceso a Supabase directo.

### Casteo de tipos
`answer_value` es TEXT. Las RPC deben castear explícitamente y manejar no-numéricos:
```sql
-- ejemplo dentro de una RPC
AVG(NULLIF(regexp_replace(answer_value, '[^0-9.]', '', 'g'), '')::numeric)
  FILTER (WHERE answer_value ~ '^[0-9.]+$')
```
Valores no parseables o nulos se excluyen del cálculo, no se cuentan como 0.

---

## Esquema de base de datos (referencia)

```sql
surveys (id UUID PK, title TEXT, status TEXT, brand_config JSONB, created_at TIMESTAMP)
responses (id UUID PK, survey_id UUID FK, ip_hash TEXT, created_at TIMESTAMP)
answers (id UUID PK, response_id UUID FK, question_code TEXT, answer_value TEXT, created_at TIMESTAMP)
consent_records (id UUID PK, response_id UUID, operational_consent BOOL, macro_consent BOOL, created_at TIMESTAMP)
```

### Códigos de preguntas (instrumento de 44)
- **A1** Departamento (18 deptos) · **A2** Ciudad · **A3** Barrio (texto) · **A4** Género · **A5** Rango etario · **A6** Educativo · **A7** Contrato
- **1.1** Discapacidad propia (→1.2-1.5) · **1.6** Cuida familiar (→1.7-1.12) · **1.13** Cuida adulto mayor (→1.14-1.16)
- **2.1-2.5** Intensidad (horas, tipo, red de apoyo)
- **3.1** Ausencias días/mes · **3.2** Tardanzas · **3.3** Reducción horas · **3.4** Salario 🔒 · **3.5** Gasto en cuidados
- **4.1-4.3** Sueño, tiempo libre, salud
- **5.1** Productividad (1-5) · **5.2** Consideró dejar el trabajo (Sí/No)
- **6.1** Empresa conoce (Sí/No/Parcial) · **6.2** Políticas que conoce (multi, max 3) · **6.3** Satisfacción (1-5) · **6.4** Políticas que necesita (multi) · **6.5** NPS (0-10)
- **7.1** Texto libre 🔒

---

## Ruta y estructura

`/dashboard?survey_id=UUID`

- Header `SurveyHeader` existente (marca RE)
- Sidebar izquierdo colapsable — filtros globales
- Grid principal de widgets
- Footer `SurveyFooter` existente

### Filtros globales (sidebar)
Multi-select Departamento · checkbox Género · slider dual Rango etario · checkbox Contrato · botón Resetear.
Los filtros se pasan como query params a los Route Handlers; las RPC los aplican server-side.
**Importante:** al combinar filtros, el N puede caer bajo 5 → el widget muestra "Datos insuficientes para esta combinación de filtros" en lugar de datos.

---

## WIDGETS

### Estado de N insuficiente
TODO widget tiene 3 estados: `loading` (skeleton) · `ok` (datos) · `suppressed`
("Datos insuficientes — se necesitan al menos 5 respuestas en este corte"). El estado
`suppressed` lo determina la RPC, no el cliente.

### 🗺️ WIDGET 1 — Mapa de Paraguay (OBLIGATORIO)
**Qué muestra:** prevalencia de cuidadores por departamento (% con Sí en `1.6` o `1.13`).
**Implementación SVG inline:**
- Crear `public/geo/paraguay-departamentos.svg` o un componente con los paths de los
  18 departamentos. Fuente del contorno: GeoJSON público de límites administrativos de
  Paraguay (nivel ADM1), simplificado. Si no se consigue un SVG fiel, usar una grilla
  esquemática de 18 celdas etiquetadas con los departamentos (cuadrícula tipo "tile map")
  — es aceptable como fallback y mantiene la interactividad.
- Color por departamento: escala `#E7E6E5` (baja) → `#43BBC8` (alta).
- **Departamentos con N<5 se pintan en gris neutro con patrón rayado y tooltip "Datos
  insuficientes"** — NO muestran porcentaje.
- Hover: tooltip con nombre + % + N (solo si N≥5).
- Click: filtra el dashboard a ese departamento.

### 📊 WIDGET 2 — KPI Cards
1. **% Cuidadores activos** — `1.1=Sí` OR `1.6=Sí` OR `1.13=Sí`
2. **Prom. días ausencia/mes** — media de `3.1` (casteo numérico)
3. **Score bienestar** — media de `5.1` (1-5 → 0-100%)
4. **NPS Cuidador** — de `6.5`. **Solo se muestra si N≥10**; si no, "N insuficiente para NPS".
Card: número grande teal, label, animación de conteo al cargar.

### 🔥 WIDGET 3 — Heatmap intensidad vs. ausentismo
X = horas semanales (`2.1`, en bins) · Y = días ausencia (`3.1`, en bins).
Celdas coloreadas por densidad. **Celdas con N<5 se muestran vacías/neutras**, no con
su conteo real. Insight: correlación carga↔ausentismo.

### 🍩 WIDGET 4 — Donut: tipo de cuidado
% discapacidad propia (`1.1`) / cuidador familiar (`1.6`) / cuidador adulto mayor (`1.13`).
Solapamiento calculado (categorías no excluyentes). Agregado simple, sin riesgo de k
salvo que el total del survey sea <5 (entonces todo el widget es `suppressed`).

### 📈 WIDGET 5 — Barras: gap de políticas
Top 8 de `6.4` (necesitadas) vs `6.2` (existentes). Teal = necesidad, naranja = ya existe.
Insight: brecha demanda/oferta de políticas.

### 🎯 WIDGET 6 — Gauge: madurez organizacional
Compuesto: `6.1` (Sí=1/Parcial=0.5/No=0) + `6.3` normalizado + `6.5` normalizado.
Score 0-100. Zonas: 0-33 rojo "Baja madurez" / 34-66 naranja "En desarrollo" / 67-100 teal "Consciente".

### 👥 WIDGET 7 — Pirámide demográfica
Rango etario (`A5`) × género (`A4`). Mujeres izquierda (`#EE761A`), hombres derecha
(`#43BBC8`), no binario (`#F8AD13`). **Cada celda (etario×género) con N<5 se colapsa**
al rango contiguo o se omite con nota al pie.

### 💸 WIDGET 8 — Intensidad de cuidado vs. productividad (REEMPLAZA al scatter)
> El scatter original graficaba un punto por persona = dato individual, reidentificable.
> Se reemplaza por un **hexbin / binned heatmap agregado**:
- X = horas de cuidado (`2.1`, bins) · Y = productividad (`5.1`, 1-5)
- Color de cada bin = cantidad de respondentes (solo bins con N≥5)
- Línea de tendencia calculada sobre los bins, no sobre individuos
- Insight idéntico al scatter (relación carga↔productividad) sin exponer personas
- **NO usa `3.5` (gasto) como en v1**, porque cruzar gasto+productividad+género+horas en
  un punto individual era el vector de reidentificación más fuerte.

### 📋 WIDGET 9 — Tabla de riesgo de retención
Segmentos: Alto (`5.2=Sí` AND `6.3≤2`) / Medio (`5.2=Sí` OR `6.3≤2`) / Bajo (resto).
Columnas: Segmento · N · % del total · Política más demandada del segmento.
> **Cambio vs v1:** se ELIMINA la columna "Depto. más frecuente". Cruzar segmento de
> riesgo × departamento producía celdas de N=1-2 reidentificables en el piloto.
> **Cada segmento con N<5 se muestra como "—" (suprimido)**, no con su conteo.

---

## Diseño visual — "deslumbrante"
- Fondo `#0F1923` (oscuro premium) · widgets `#1A2535` con borde teal 20% opacity
- Texto principal blanco, secundario `#E7E6E5`
- CSS Grid 12 columnas, responsive
- KPI con counter animation (requestAnimationFrame), `tabular-nums`
- Hover en widget: `box-shadow: 0 0 20px #43BBC830`
- Transición de filtro 300ms ease

**Layout (12 cols):**
```
Fila 1: [KPI×4] cada uno 3 cols
Fila 2: [MAPA 6 cols][DONUT 3 cols][GAUGE 3 cols]
Fila 3: [HEATMAP 6 cols][PIRÁMIDE 6 cols]
Fila 4: [BARRAS 6 cols][INTENSIDAD/PRODUCTIVIDAD 6 cols]
Fila 5: [TABLA RIESGO 12 cols]
```

---

## Archivos a crear

```
migrations/
  0XX_dashboard_rpc.sql        — funciones RPC con supresión k≥5
  0XX_rls_deny_sensitive.sql   — RLS que niega 3.4 y 7.1 al rol del dashboard

app/dashboard/
  page.tsx
  loading.tsx
app/api/dashboard/
  [widget]/route.ts            — o un route.ts por widget

components/dashboard/
  kpi-cards.tsx · paraguay-map.tsx · heatmap-widget.tsx · donut-cuidados.tsx
  politicas-bar.tsx · gauge-organizacional.tsx · piramide-demografica.tsx
  intensidad-productividad.tsx · tabla-riesgo.tsx · filter-sidebar.tsx · widget-shell.tsx

lib/
  dashboard-queries.ts  — fetch a los Route Handlers (NO Supabase directo)
  dashboard-types.ts
  dashboard-utils.ts    — NPS, score organizacional, regresión sobre bins
```

---

## Entregables (DoD)

- [ ] Migración de RPC aplicada; cada función aplica supresión k≥5 internamente
- [ ] Migración RLS que niega `3.4` y `7.1` aplicada y verificada
- [ ] El cliente NO importa el cliente de Supabase para datos — solo hace fetch a `/api/dashboard`
- [ ] `/dashboard?survey_id=UUID` carga con datos reales
- [ ] Los 9 widgets renderizan en uno de los 3 estados (loading/ok/suppressed)
- [ ] Mapa de Paraguay interactivo (hover + click filtra)
- [ ] Filtros globales afectan todos los widgets via query params server-side
- [ ] Widget 8 es agregado (hexbin), NO scatter individual
- [ ] Tabla de riesgo SIN columna de departamento
- [ ] Test manual: con un survey de N=3, todos los widgets muestran "suppressed"
- [ ] `grep -r "3.4" app/ components/ lib/` no encuentra el código usándolo como dato
- [ ] Build sin errores (`next build`)
- [ ] `git diff --name-only HEAD` — solo archivos del scope

## Qué NO hacer
- ❌ Cliente consultando `answers` directo (todo via RPC/Route Handler)
- ❌ Filtros de privacidad en el cliente como única protección
- ❌ Exponer `3.4` o `7.1` en cualquier capa
- ❌ Widgets que grafiquen individuos (scatter de personas, tablas con cruces de N<5)
- ❌ service_role en código de cliente o en `NEXT_PUBLIC_*`
- ❌ Agregar dependencias npm
- ❌ Tocar el formulario, `app/actions/` de submit, o RLS existente de escritura

## Qué reportar
```
Verificado:
- migración RPC aplicada: [funciones creadas]
- migración RLS aplicada: 3.4 y 7.1 negados — confirmado con query de prueba
- cliente sin acceso directo a answers: confirmado (grep)
- build exitoso
- archivos creados: [lista]
- widgets en estado ok / suppressed con datos actuales: [lista]
- prueba k-anonimato (survey N<5 → suppressed): [resultado]
- mapa interactivo: [descripción]

Asumido:
- validación visual pendiente del director

Decisiones proactivas (Nivel 2):
- [cambios fuera de scope exacto]

Conflictos de scope (si git diff mostró algo no autorizado):
- [archivo + qué se hizo]
```