REP-007 — Tableros Personalizados
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
| RF | Entregable |
|---|---|
| RF-REP-007-01 | Tableros 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-02 | Selección de indicadores: catálogo de 15 widgets servido por el backend, con elección, orden y ancho por usuario |
| RF-REP-007-03 | Tableros predefinidos: una plantilla por categoría, seeded, y cadena de respaldo para que /tablero nunca quede vacío |
| RF-REP-007-04 | Guardar 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:
GET /catalogono envía los widgets que la categoría del solicitante no puede ver.- Al crear, actualizar, copiar y publicar, todo
widget_idse 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ía | Roles |
|---|---|
| Almacén | Almacenista · Auxiliar inventario |
| Administración | Administrador · Usuario Interno |
| Auditoría | Auditor |
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étodo | Ruta | Para qué |
|---|---|---|
| GET | /catalogo | Indicadores que mi rol puede ver (filtrado en el servidor) |
| GET | /activo | Tablero efectivo, con la cadena de respaldo |
| GET | / | Mis tableros + plantillas de mi categoría |
| POST | / · PUT /:id · DELETE /:id | Gestión del tablero propio |
| POST | /:id/copiar | Adoptar una plantilla o el tablero de un compañero |
| POST | /:id/activar | Cuál se abre en /tablero |
| POST | /:id/publicar | Compartir con mi rol, o retirar |
| PUT | /plantillas/:categoriaRol | Definir 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.
