Saltar al contenido principal

REP-007 — Tableros Personalizados

· 5 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

Implementación de la mejora REP-007 (Tableros Personalizados), dentro de 4.2 Analítica Avanzada: el tablero deja de ser una pantalla fija y pasa a ser una configuración persistida que cada usuario arma con los indicadores y reportes que le sirven, con plantillas predefinidas por rol y con la posibilidad de compartir su configuración con compañeros de la misma categoría.


📋 Alcance​

RFEntregable
RF-REP-007-01Tableros por rol: los cinco roles reales se agrupan en almacén, administración y auditoría; la categoría gobierna qué se puede ver y guardar
RF-REP-007-02Selección de indicadores: catálogo de 15 widgets servido por el backend, con elección, orden y ancho por usuario
RF-REP-007-03Tableros predefinidos: una plantilla por categoría, seeded, y cadena de respaldo para que /tablero nunca quede vacío
RF-REP-007-04Guardar y compartir: publicación de un tablero para el propio rol y copia profunda para quien lo adopta

🔐 La decisión que sostiene el RF-04: la seguridad en el servidor​

El requerimiento pide compartir configuraciones entre usuarios del mismo rol, y ahí hay un riesgo evidente: un tablero compartido lo escribe otro usuario. Si la visibilidad se decidiera en el cliente, un Almacenista podría publicar un tablero con widgets de auditoría dentro y un Auditor lo vería al copiarlo.

Por eso el catálogo vive en el backend (catalogo-tableros.ts) y la validación es doble:

  1. GET /catalogo no envía los widgets que la categoría del solicitante no puede ver.
  2. Al crear, actualizar, copiar y publicar, todo widget_id se valida contra el catálogo de la categoría; uno fuera de catálogo devuelve 400.

Al copiar un tablero, además, la copia pertenece a la categoría del que copia, no a la del origen: los widgets incompatibles se descartan y se informa cuántos.

🏷️ Roles → categorías de tablero​

CategoríaRoles
AlmacénAlmacenista · Auxiliar inventario
AdministraciónAdministrador · Usuario Interno
AuditoríaAuditor

Un rol desconocido cae en almacén, la categoría más restrictiva en cuanto a escritura: un rol nuevo sin mapear nunca gana visibilidad por omisión.

🧩 Catálogo de indicadores​

15 widgets, todos construidos sobre APIs que el módulo ya exponía (REP-001, REP-003, REP-005, REP-006, INV-004, INV-005, INV-006, SOL):

  • Almacén (10): stock total, alertas de stock, próximos a vencer, stock por categoría, movimientos por mes, resumen por almacén, reposición sugerida, conteos pendientes, solicitudes pendientes, proyección de necesidades.
  • Administración (9): KPIs de gestión, consumo por área, proyección, solicitudes, stock por categoría, resumen de almacenes, usuarios…
  • Auditoría (8): KPIs, log de operaciones, cargas masivas, conteos, consumo por área, próximos a vencer, usuarios.

Los widgets son de solo lectura: los que tienen vista completa enlazan a la página existente en lugar de duplicar acciones de escritura.

📊 Cadena de respaldo del tablero efectivo​

usuarios.id_tablero_activo
└─ NULL → mi tablero personal más reciente
└─ no existe → plantilla predefinida de mi categoría
└─ no existe → tablero sugerido con el set mínimo de mi categoría

/tablero nunca queda vacío. Y si un widget guardado ya no existe en el catálogo, se omite y el tablero informa cuántos se descartaron, en lugar de romperse.

🤝 Compartir sin pisar a nadie​

Publicar no impone nada: pone el tablero a disposición de la categoría para que quien quiera lo copie. La copia es profunda y transaccional —editar el original no la altera y viceversa—, y se activa automáticamente para que el usuario la vea de inmediato.

Se descartó el modelo push (aplicar la configuración a todos los del rol): cumple el RF al pie de la letra, pero destruye personalizaciones sin aviso.

🔌 API​

Bajo api/reportes/tableros, en el ReportesModule existente:

MétodoRutaPara qué
GET/catalogoIndicadores que mi rol puede ver (filtrado en el servidor)
GET/activoTablero efectivo, con la cadena de respaldo
GET/Mis tableros + plantillas de mi categoría
POST/ · PUT /:id · DELETE /:idGestión del tablero propio
POST/:id/copiarAdoptar una plantilla o el tablero de un compañero
POST/:id/activarCuál se abre en /tablero
POST/:id/publicarCompartir con mi rol, o retirar
PUT/plantillas/:categoriaRolDefinir la plantilla predefinida (solo Administrador)

🖥️ Interfaz​

Página nueva /tablero con ítem propio en el menú. /general-dashboard no se modificó: sigue intacto con sus pruebas E2E.

  • Grilla de 12 columnas con orden y ancho por widget (1–3), sin posiciones libres x/y: así se mantiene el responsive.
  • Cada tarjeta aísla su propio fallo: si una API no responde, el error aparece dentro de esa tarjeta y el resto del tablero sigue funcionando.
  • Selector de indicadores con buscador, orden (↑/↓) y ancho. Reordenar con botones en lugar de drag & drop: funciona con teclado y en móvil.
  • Panel de mis tableros y de plantillas de mi rol, con previsualización, copia y publicación.

✅ Verificación​

Backend: npx tsc --noEmit EXIT 0 · 368 pruebas en verde (50 nuevas) · migración 028 aplicada · npm run seed completo.

Contra la base real (scripts/verificar-tableros.ts): 21 de 21 contrastes OK. Los tres tableros predefinidos quedan guardados con 6–7 indicadores, el seeder es idempotente y el aislamiento se cumple en los datos: la plantilla de almacén no contiene ni un widget de auditoría ni de administración. Los 10 usuarios del sistema entran por la cadena de respaldo sin migración de datos.

Frontend: tsc --noEmit EXIT 0 · next lint sin warnings · 22 pruebas en verde (9 nuevas).

Corrección colateral: se reparó el import circular entre historial-reporte.entity.ts y reporte-programado.entity.ts, que rompía cualquier arranque por ts-node —incluido npm run seed— con ReferenceError: Cannot access 'reporte_programado_entity_1'.

📚 Documentación​


Requerimiento cubierto: REP-007 (Fase 4, Impacto Medio) — los 4 RF implementados y verificados.