Saltar a contenido

E-map Organizacional — Vista global de la organización

Tema: E-map Organizacional — Vista de RRHH / Dirección sobre toda la organización
Idioma: ES

Resumen en pocas palabras

El E-map Organizacional es la vista de más alto nivel sobre el estado existencial de toda la organización. Quienes tienen el permiso ORGANIZATION:READ_EMAP (típicamente RRHH o Dirección) pueden ver el score global de la organización, un historial mensual de evolución, el desglose por equipo y por persona, la tasa de respuesta, y un diagnóstico generado por IA que analiza el estado del conjunto y señala qué equipos o personas necesitan atención.

Objetivo de negocio

Que quienes tienen responsabilidad sobre toda la organización (RRHH, Dirección) tengan una visión consolidada del estado existencial de todos sus colaboradores, con el mismo nivel de análisis que el líder tiene sobre su equipo, pero escalado a la organización completa. El E-map Organizacional permite detectar brechas sistémicas, equipos en riesgo y personas que se desvían del estado general, sin necesidad de revisar cada equipo de forma individual.

Contexto y alcance

Qué está incluido

  • Score global de la organización (igual peso por equipo)
  • Historial mensual de evolución organizacional (últimos 12 meses)
  • Desglose por equipo: score del período, tamaño y alerta de ausencia
  • Desglose individual: score del período y alerta de ausencia por persona
  • Tasa de respuesta: qué porcentaje de la organización completó sesiones en las últimas 4 semanas
  • Diagnóstico IA generado bajo demanda: análisis por dimensión + lista de equipos/personas que necesitan atención
  • Navegación al detalle de un equipo dentro del contexto organizacional

Qué no está incluido en este documento

Actores

Actor Qué hace
Usuario con ORGANIZATION:READ_EMAP Ve el E-map organizacional completo, navega al detalle de equipos y solicita la generación del diagnóstico IA. Típicamente: RRHH, Dirección.
Sistema (backend) Calcula el score organizacional y el historial, agrega los datos de todos los miembros, genera el diagnóstico IA bajo demanda y controla el cooldown de generación.

Casos de uso

CU-1 Ver el E-map organizacional

El usuario con ORGANIZATION:READ_EMAP accede a la vista organizacional y ve: - El score global de la organización en las tres dimensiones (Efectiva → Afectiva → Perspectiva) - La tasa de respuesta: qué porcentaje de miembros completó al menos una sesión en las últimas 4 semanas - El historial mensual de evolución (últimos 12 meses) - El desglose por equipo: score del período, tamaño del equipo y si el equipo no tiene sesiones recientes - El desglose individual: score del período y si la persona no tiene sesiones recientes - Los diagnósticos IA generados previamente (últimos 12)

Si ningún miembro de la organización tiene sesiones en las últimas 4 semanas, se muestra estado vacío (absenceAlert).

CU-2 Ver el detalle de un equipo

Desde la vista organizacional, el usuario puede seleccionar un equipo específico (identificado por su líder) y ver su E-map grupal completo — el mismo que vería el líder de ese equipo. Incluye score del período, historial y diagnóstico IA del equipo si existe.

CU-3 Generar diagnóstico IA organizacional

El usuario solicita la generación del diagnóstico IA de la organización. El sistema analiza el estado actual del conjunto (últimas 4 semanas), llama a la IA y devuelve: - Comprender — análisis por dimensión: descripción del estado de la organización en efectiva, afectiva y perspectiva - Gestionar — texto resumen de gestión + lista de equipos o personas que necesitan atención, con el motivo

El diagnóstico queda guardado y es visible en el historial. Está sujeto a un cooldown configurable (por día o por mes): si ya se generó uno en el período activo, el sistema rechaza la solicitud e informa cuántos segundos faltan para el próximo período.

Cálculo del score organizacional

Score del período (últimas 4 semanas)

Se usa la misma ventana rolling de 28 días que en el E-map grupal. Los pasos son:

  1. Score del período por persona: se promedian todos los E-maps de cada miembro dentro de las últimas 4 semanas. Si no tiene sesiones en el período, queda excluido.
  2. Score del período por equipo: se promedian los scores del período de los miembros del equipo con sesiones. Si ningún miembro del equipo tiene sesiones, el equipo no tiene score y se marca con absenceAlert.
  3. Score organizacional: se promedian los scores de todos los equipos con score. Cada equipo pesa igual, independientemente de su tamaño.

Un equipo de 2 personas y uno de 20 contribuyen con el mismo peso al score organizacional.

Agrupación por equipos

Los miembros se agrupan por su leader_id. Los usuarios sin líder asignado forman un grupo especial llamado "Dirección" (identificador interno: top-level).

Historial mensual

El historial usa meses calendario (no ventana rolling). Para cada mes se calcula el score organizacional con el mismo algoritmo de dos pasos (score por persona → score por equipo → score org). Se conservan los últimos 12 meses con al menos un E-map.

A diferencia del score actual, el historial usa todos los E-maps de cada usuario (sin límite de ventana), agrupados por mes de creación.

Diagnóstico IA organizacional

Cuándo se genera

El diagnóstico se genera bajo demanda mediante POST /emap/organization/diagnostic. No se genera automáticamente.

Cooldown

El sistema impide generar más de un diagnóstico por período. La granularidad del período es configurable:

Granularidad Comportamiento
Por día (defecto) Solo se puede generar un diagnóstico por día calendario.
Por mes Solo se puede generar un diagnóstico por mes calendario.

Si el usuario intenta generar un diagnóstico dentro del período activo, el sistema devuelve un error 422 indicando cuántos segundos faltan hasta el próximo período.

Qué produce

Campo Descripción
Comprender Análisis por cada dimensión (efectiva, afectiva, perspectiva): descripción del estado general de la organización en esa dimensión
Gestionar Texto de resumen sobre qué hacer como organización + lista de attend con los equipos o personas específicos que requieren atención, con el motivo
orgScore Snapshot del score organizacional en el momento de la generación
generatedAt Timestamp ISO de la generación

Outliers para el diagnóstico

Para enriquecer el diagnóstico, el sistema identifica a las personas más alejadas del score organizacional en cada dimensión (hasta 5 outliers por dimensión). Estos outliers se incluyen como contexto para la IA.

Historial de diagnósticos

Se conservan los últimos 12 diagnósticos generados. Se devuelven del más reciente al más antiguo.

Reglas de negocio

R-1.1 Requiere permiso ORGANIZATION:READ_EMAP

Solo los usuarios con el permiso ORGANIZATION:READ_EMAP pueden acceder a la vista organizacional y generar diagnósticos. Este permiso solo puede asignarse a roles de organizaciones SUPER_ADMIN. Ver 02-permisos.md.

R-1.2 Scoping automático a la propia organización

La vista siempre está limitada a los miembros de la organización del usuario autenticado. No hay acceso cross-org.

R-1.3 Score organizacional con peso igual por equipo

El score global se calcula promediando los scores de los equipos, no los de las personas. Un equipo pequeño y uno grande pesan igual.

R-1.4 Usuarios sin líder forman el grupo "Dirección"

Los miembros sin leader_id asignado se agrupan automáticamente en el equipo sintético "Dirección" (top-level). Aparecen en el desglose por equipo y en el desglose individual.

R-1.5 Historial en meses calendario (no rolling)

El historial usa meses calendario completos. La ventana rolling de 28 días solo aplica al score actual y al diagnóstico.

R-1.6 Cooldown de generación de diagnóstico configurable

La granularidad del cooldown (ORG_DIAGNOSTIC_COOLDOWN_GRANULARITY) es configurable entre day y month. El valor por defecto es day.

R-1.7 Máximo 12 diagnósticos en historial

El sistema almacena y expone los últimos 12 diagnósticos generados. Los anteriores no se eliminan pero no se devuelven en la respuesta estándar.

R-1.8 Tasa de respuesta refleja las últimas 4 semanas

responseRate es la fracción miembros con sesión en últimas 4 semanas / total miembros. Si la organización no tiene miembros, es 0.

Validaciones y mensajes al usuario

  • Sin permiso ORGANIZATION:READ_EMAP: Error 403 — acceso denegado.
  • Cooldown activo al generar diagnóstico: Error 422 con retryAfterSeconds indicando cuánto tiempo falta para el próximo período.
  • Líder fuera de la organización (al consultar equipo): Error 403.
  • Sin sesiones en la organización: La vista se devuelve con absenceAlert: true y sin orgScore.
  • No autenticado: Error 401.

Criterios de aceptación

AC-1 Vista organizacional completa

El usuario con ORGANIZATION:READ_EMAP puede consultar el E-map organizacional y recibe: orgScore (si hay sesiones), history (hasta 12 meses), teams (desglose por equipo), individuals (desglose por persona), responseRate, absenceAlert y aiDiagnostics (últimos 12).

AC-2 Score con peso igual por equipo

El score organizacional se calcula promediando los scores de los equipos, no de las personas. Un equipo sin score (sin sesiones) no afecta el promedio.

AC-3 Detalle de equipo navegable

Desde la vista organizacional, el usuario puede consultar el E-map completo de un equipo específico (por leaderId). El equipo debe pertenecer a la organización del usuario; cualquier otro devuelve 403.

AC-4 Diagnóstico IA bajo demanda con cooldown

Al solicitar un diagnóstico, si no existe uno en el período activo, el sistema genera y devuelve el diagnóstico con comprender (por dimensión) y gestionar (texto + attend). Si ya existe uno en el período, devuelve 422 con retryAfterSeconds.

AC-5 Usuarios sin líder en "Dirección"

Los usuarios sin leader_id asignado aparecen agrupados bajo el equipo "Dirección" tanto en el desglose de equipos como en el desglose individual.

AC-6 Sin acceso para usuarios sin permiso

Un usuario sin ORGANIZATION:READ_EMAP recibe 403 en cualquier endpoint del E-map organizacional.

Trazabilidad

ID Tipo Descripción breve Criterio de prueba
CU-1 Caso de uso Ver E-map organizacional completo AC-1
CU-2 Caso de uso Ver detalle de un equipo AC-3
CU-3 Caso de uso Generar diagnóstico IA org AC-4
R-1.1 Regla Requiere ORGANIZATION:READ_EMAP AC-6
R-1.2 Regla Scoping a propia organización AC-3
R-1.3 Regla Score con peso igual por equipo AC-2
R-1.4 Regla Sin líder → grupo "Dirección" AC-5
R-1.5 Regla Historial en meses calendario AC-1
R-1.6 Regla Cooldown configurable día/mes AC-4
R-1.7 Regla Máximo 12 diagnósticos en historial AC-1
R-1.8 Regla responseRate sobre últimas 4 semanas AC-1
AC-1 Aceptación Vista completa con todos los campos Campos presentes y correctos
AC-2 Aceptación Peso igual por equipo Cálculo verificado
AC-3 Aceptación Detalle de equipo navegable 200 en org / 403 fuera
AC-4 Aceptación Diagnóstico con cooldown 200 nuevo / 422 en cooldown
AC-5 Aceptación Grupo Dirección para sin líder Aparece en teams e individuals
AC-6 Aceptación 403 sin permiso Todos los endpoints bloqueados

Supuestos

  • La relación líder-liderado se gestiona a través del módulo de Liderazgo. Ver 15-liderazgo.md.
  • El permiso ORGANIZATION:READ_EMAP solo puede asignarse en organizaciones SUPER_ADMIN. Ver 02-permisos.md.
  • El prompt de la IA para el diagnóstico organizacional es externo al repo (gestionado por el equipo de producto); el sistema solo lo invoca.

Correcciones / historial de validación

Fecha Versión Cambio
2026-06-10 v1.0 Documento inicial. E-map organizacional: score global (peso igual por equipo), historial mensual, desglose por equipo e individual, tasa de respuesta, diagnóstico IA bajo demanda con cooldown configurable.