15.1.1 Qué resuelve el ADC y el KPI por Contrato

Este módulo cubre dos cosas entrelazadas: el rol operativo Administrador de Contrato (ADC) — la persona responsable de uno o varios contratos o faenas — y el tablero KPI de Administradores, un scorecard que mide, contrato por contrato y persona por persona, el porcentaje de cierre de hallazgos. Juntos convierten una responsabilidad difusa («alguien tiene que cerrar las observaciones») en un indicador objetivo que puede sustentar el bono preventivo.

En terreno, cada faena o contrato tiene un administrador que responde por su gestión preventiva. Cuando una inspección levanta un hallazgo (una observacion de condición o conducta insegura), ese hallazgo debe cerrarse: asignar un plan de acción, verificarlo y darlo por resuelto. El KPI mide justamente eso: cuántos hallazgos se cerraron respecto del total, imputando el resultado a la persona titular del contrato.

El módulo resuelve problemas concretos de la línea de mando:

• Responsabilidad nominada: cada contrato tiene un titular (dueño del bono) y, opcionalmente, suplentes de respaldo. Se acaba el «no sabía que me tocaba a mí».
• Desempeño comparable: un ranking ordena a los administradores de peor a mejor % de cierre, para focalizar la gestión y el bono.
• Detección de contratos huérfanos: los contratos con hallazgos pero sin titular se destacan como riesgo de gestión.
• Aislamiento de datos: un ADC acotado solo ve y opera sus contratos, tanto en pantalla como en el servidor.

Figura 15.1 — Tablero «KPI de Administradores»: encabezado con la bajada del bono y las tres tarjetas de resumen.

15.1.2 Conceptos clave

15.1.3 Titularidad vs. rol acotado: dos conceptos ortogonales

Es importante no confundir dos cosas que se refuerzan pero son independientes:

• Ser titular de un contrato significa que a ti se te imputa el bono de ese contrato en el KPI. Se configura en el ContractForm (Sección 15.4).
• Tener rol acotado (isContractScoped) significa que solo ves y operas tus contratos. Se configura en el rol (Sección 15.5.3).

Un usuario puede ser titular sin rol acotado (carga el bono, pero ve toda la empresa) y puede tener rol acotado sin ser titular (solo ve sus contratos como suplente, pero no carga el bono). Ambos conceptos son ortogonales.

TITULARIDAD (adminUserId)           ROL ACOTADO (isContractScoped)
        |                                     |
  «a mí se me imputa                  «solo veo/opero
   el bono del contrato»               mis contratos»
        |                                     |
        v                                     v
  aparece en el KPI                    aislamiento de datos
  (ranking + scorecard)                (pantalla + servidor)

  Se combinan pero NO dependen uno del otro.

15.1.4 Encuadre normativo (Chile)

El módulo operacionaliza la responsabilidad del administrador de contrato y de la línea de mando sobre la gestión preventiva:

El acceso al módulo tiene dos capas: el tablero KPI (analítico, en el Hub de IA) y la configuración de titularidad (en el ContractHub). Además, el aislamiento ADC filtra lo que cada usuario ve dentro del tablero.

15.2.1 Acceso al tablero KPI

El tablero se abre desde el Hub de IA: entra a /ai, baja hasta la sección Herramientas de IA y haz clic en la tarjeta «KPI de Administradores». También puedes ir por URL directa a /ai/contract-kpi.

Figura 15.2 — Tarjeta «KPI de Administradores» dentro de la sección «Herramientas de IA» del Hub de IA.

15.2.2 Acceso a la configuración de titularidad

La asignación del titular y de los suplentes vive dentro del ContractHub (/admin/contracts), en el formulario de cada contrato (ContractForm). Para llegar: entra a /admin, abre Nodos Contractuales y usa «Abrir Nuevo Nodo» o el lápiz de edición de un contrato existente. El acceso a este hub se rige por los permisos habituales de administración de contratos (el Tenant Admin ve todo; el ADC acotado, solo lo suyo).

15.2.3 Qué ve cada perfil (aislamiento ADC)

El aislamiento se aplica antes de calcular el KPI y también al listar contratos. Depende de la bandera isContractScoped del rol del usuario:

Cómo se decide «sus contratos»

Cuando a un usuario se le asigna como titular (adminUserId) o dentro de los suplentes (deputyAdminUserIds) de un contrato, el sistema agrega ese contrato a su lista administeredContractIds (una relación inversa que se mantiene automáticamente). Esa lista es la que define su cartera. Un rol acotado sin contratos asignados no verá nada.

15.2.4 Rutas involucradas

El tablero /ai/contract-kpi es una única página de solo lectura compuesta por varios paneles. No tiene formularios, filtros de fecha, ni exportación: es puramente informativo. Su encabezado lo deja claro con la bajada literal: «El bono de los administradores depende de prevención — cierre de hallazgos por contrato.»

15.3.1 Fuente de datos y definiciones

El tablero lee las 500 observaciones más recientes de la empresa activa (ordenadas por fecha, de la más nueva a la más antigua) y las cruza con los contratos (ya filtrados por el aislamiento ADC) y con los usuarios (para resolver titular y suplentes reales, con su avatar y nombre).

15.3.2 Bandas de desempeño y % de cierre

Todo el tablero colorea el % de cierre en tres bandas:

El tablero ordena casi todo peor primero: los contratos y administradores con menor % de cierre aparecen arriba, para que la gestión se enfoque donde más duele. La nota al pie del tablero lo resume: «% de cierre = hallazgos cerrados / total · ordenado por desempeño (peor primero).»

15.3.3 Encabezado y KPI cards

Arriba del tablero, junto al título, hay tres tarjetas de resumen (KPI cards) que dan la foto global de la cartera:

Figura 15.3 — Encabezado del tablero con el título y las tres KPI cards: Contratos evaluados, Cierre promedio y Hallazgos abiertos.

15.3.4 Resumen visual (3 gráficos)

La sección «Resumen visual» presenta tres gráficos que resumen la cartera de un vistazo. Cada uno lleva una leyenda compacta con puntos de color, nombre y valor.

Figura 15.4 — Tablero KPI con la sección «Resumen visual»: barras de % de cierre por contrato y los donuts de bandas y de hallazgos.

Cuando no hay datos, cada gráfico muestra un estado vacío con el texto «Sin contratos con hallazgos».

Figura 15.5 — Tooltip del gráfico «% de cierre por contrato»: muestra el nombre completo, el administrador y el % de cierre exacto al pasar el cursor.

15.3.5 Ranking de Administradores

El corazón del tablero para el bono es el «Ranking de Administradores». Su bajada lo explica: «Desempeño imputado a la persona (titular real del contrato). % consolidado = promedio ponderado del cierre por nº de hallazgos de cada contrato (= cierres / hallazgos totales de su cartera). Peor primero.»

Figura 15.6 — «Ranking de Administradores»: cada fila muestra avatar, nombre, cartera y el % consolidado con su banda, ordenado peor primero.

Cada fila del ranking muestra:

• El número de posición (1, 2, 3…), con el peor desempeño primero.
• El avatar del titular (con su foto). Si es el grupo sin titular, un triángulo de advertencia.
• El nombre del titular. Si no hay titular: «Sin titular asignado» (en cursiva, con borde punteado).
• Un subtexto con la cartera: N contrato(s) · X abiertos (en rojo) · Y hallazgos.
• A la derecha, el % consolidado grande (coloreado por banda) y la etiqueta de banda.

Cómo se calcula el % consolidado por persona

El sistema agrupa los contratos por su titular (los sin titular caen en un grupo aparte). Para cada persona suma todos los cierres y todos los hallazgos de su cartera completa y calcula: consolidado = cierres totales ÷ hallazgos totales × 100. Es decir, un promedio ponderado por número de hallazgos: un contrato con muchos hallazgos pesa más que uno con pocos. Si la persona no tiene hallazgos en ninguno de sus contratos (total = 0), su consolidado es 100%. El ranking se ordena peor primero.

Si no hay ningún administrador con contratos evaluables (y el tablero ya terminó de cargar), el ranking muestra el estado vacío: «Sin administradores con contratos evaluables.»

Figura 15.7 — Fila «Sin titular asignado» del ranking: borde punteado y triángulo de advertencia, sin avatar ni nombre.

15.3.6 Scorecards por contrato

Debajo del ranking hay una grilla de scorecards, una tarjeta por contrato, también ordenadas peor primero. Cada scorecard detalla la situación de un contrato concreto.

Figura 15.8 — Scorecards por contrato: administrador titular, suplentes, % de cierre con barra de progreso y contadores de hallazgos.

Si no hay contratos con hallazgos (y el tablero ya cargó), la grilla muestra: «No hay contratos con hallazgos en el periodo.»

15.3.7 Reincidencia por trabajador

Al final del tablero puede aparecer un panel condicional: «Reincidencia por trabajador». Solo se muestra si hay trabajadores con 2 o más hallazgos en los que figuran como involucrados. Su bajada es: «Trabajadores con ≥2 hallazgos involucrados — base de la carta de amonestación.»

Muestra hasta 8 trabajadores, ordenados por número de hallazgos (de mayor a menor). Cada fila lleva: la posición, el nombre, el RUT, un badge opcional «X alta» (si hay hallazgos de severidad alta) y el conteo total de hallazgos.

Figura 15.9 — Panel «Reincidencia por trabajador»: lista de trabajadores con 2 o más hallazgos y badge de severidad alta.

15.3.8 Botones, acciones y estados de la UI

El tablero tiene muy pocas acciones porque es de solo lectura:

Estados posibles del tablero:

Figura 15.10 — Tablero KPI sin datos: los gráficos muestran «Sin contratos con hallazgos» y el ranking/grilla sus estados vacíos.

Figura 15.11 — Mensaje «Empresa Requerida» cuando no hay empresa activa, con los botones «Seleccionar Empresa» y «Volver».

15.3.9 Interpretación de los indicadores (guía numérica)

El tablero te da números, pero la gestión la decides tú. Esta sección documenta cada indicador con tres preguntas: qué mide, cómo se calcula y un ejemplo práctico con datos para saber qué decisión tomar. Úsala como hoja de referencia cuando presentes el tablero en un comité o prepares el corte del bono.

Qué mide y cómo se calcula cada KPI

Ejemplos interpretados, indicador por indicador

El ContractForm es donde se define quién responde por cada contrato. Se abre desde el ContractHub con «Abrir Nuevo Nodo» (título «Nuevo Nodo Contractual») o con el lápiz de edición (título «Editar Nodo Contractual»). Aquí se asigna el titular ADC y sus suplentes.

Figura 15.12 — ContractForm: la sección «Administración del Contrato» con el selector de titular y el bloque de suplentes.

15.4.1 Campos del formulario

La sección «Administración del Contrato»

El bloque del titular y los suplentes vive bajo un encabezado con ícono de escudo, «Administración del Contrato», con el subtitulo literal: «El titular es el único responsable del cumplimiento y del KPI; los suplentes son respaldo.»

• Al seleccionar un titular, aparece una tarjeta con su avatar, su nombre y el badge «Responsable del KPI», más un botón X («Quitar titular»).
• Cada suplente se muestra como un chip con avatar, nombre y una X («Quitar suplente»).
• Mientras cargan los usuarios: caja «Cargando usuarios...».
• Si la empresa no tiene usuarios: caja ámbar «No hay usuarios en esta empresa para asignar como titular.».

Figura 15.13 — Tarjeta del titular seleccionado con avatar, nombre y el badge «Responsable del KPI», más el botón X para quitarlo.

Figura 15.14 — Suplentes agregados como chips con avatar y su botón X de «Quitar suplente».

Indicadores de estado calculados

Según las fechas, el formulario muestra banners automáticos (no editables):

• Si la fecha de fin ya paso: banner rojo «Este contrato se marcara como VENCIDO» / «La fecha de fin es anterior a hoy».
• Si la fecha de inicio es futura: banner ámbar «Este contrato estara PENDIENTE de iniciar» / «La fecha de inicio es posterior a hoy».

Figura 15.15 — Banner rojo «Este contrato se marcara como VENCIDO» cuando la fecha de fin ya pasó.

15.4.2 Botones y acciones

15.4.3 Estados de la UI

Figura 15.16 — Validaciones del formulario: errores en rojo bajo cada campo con su mensaje textual.

15.4.4 Reglas de negocio al guardar

Al guardar, el sistema ejecuta varias acciones automáticas dentro de una transacción, para mantener la coherencia entre el contrato, el KPI legado y las carteras de los usuarios:

• Denormaliza el nombre del titular en gerenteAdmin (usado por el informe SSOMA y el KPI legado). Si se quita el titular, ese campo se limpia; si nunca hubo titular, no se toca un valor legado existente.
• Reconcilia la relación inversa administeredContractIds: agrega este contrato a la cartera de los usuarios que son titular o suplente, y lo quita de quienes dejaron de serlo.
• Sanitiza los suplentes: nunca incluye al titular ni ids vacíos.
• Al desactivar o archivar el contrato, se quita su id de las carteras de titular y suplentes (dejan de administrarlo).
• Existe una reconciliación masiva que reconstruye las carteras de todos los usuarios de una empresa; se usa para reparar denormalización desincronizada (ver Solución de problemas).

El ContractHub (/admin/contracts) es el listado de contratos, llamados «Nodos Contractuales» dentro de la «Estructura Orgánica de Faenas». Es relevante para este capítulo porque es donde se aplica el aislamiento ADC a la vista de contratos y desde donde se abre el ContractForm.

Figura 15.17 — ContractHub: lista de nodos contractuales con filtros por estado y las acciones por tarjeta.

15.5.1 Lista de nodos, filtros y estados

La lista ofrece filtros con conteo: «Todos», «Activos», «Vencidos» e «Inactivos». El botón «Abrir Nuevo Nodo» lanza el ContractForm. Cada tarjeta de contrato tiene tres acciones: el lápiz (editar), la papelera / reactivar (baja o alta lógica) y «Gestionar Estructura Operativa».

Estados de la lista:

15.5.2 Desactivar y reactivar un contrato

Desde la tarjeta de un contrato puedes darlo de baja o de alta lógica. Ambas acciones piden confirmación en un modal.

Figura 15.18 — Modal «Desactivar Contrato»: pide escribir «DESACTIVAR» para habilitar el botón de confirmación.

15.5.3 Configurar un usuario como ADC acotado

Para que un usuario quede acotado a sus contratos hacen falta tres cosas, en este orden:

Caso 1: Asignar un administrador de contrato (titular) y suplentes

1. Ve a /admin/contracts (ContractHub).
2. Edita un contrato (lápiz) o pulsa «Abrir Nuevo Nodo».
3. En la sección «Administración del Contrato», abre el selector «Administrador de Contrato (titular)» y busca por nombre o RUT.
4. Selecciona al responsable: aparece su tarjeta con el badge «Responsable del KPI».
5. (Opcional) Agrega suplentes en «Suplentes (opcional)»: se muestran como chips.
6. Guarda con «Crear Contrato» / «Guardar Cambios».
7. Efecto: el titular pasa a aparecer en el KPI y su cartera se actualiza (si su rol es acotado, ya ve este contrato).

Caso 2: Revisar el desempeño y detectar administradores críticos

1. Ve a /ai y abre la tarjeta «KPI de Administradores».
2. Lee las tres KPI cards: contratos evaluados, cierre promedio y hallazgos abiertos.
3. En «Resumen visual», mira cuántos contratos están en banda Crítico.
4. Baja a «Ranking de Administradores»: el primero de la lista es el de peor % consolidado, el foco del bono y de la gestión.
5. Revisa sus scorecards para ver qué contrato específico arrastra el ranking.

Caso 3: Detectar contratos sin responsable (riesgo de gestión)

1. Abre el KPI.
2. En el ranking, busca la fila «Sin titular asignado» (borde punteado + triángulo).
3. Observa cuántos contratos y hallazgos caen ahí.
4. Ve a /admin/contracts, edita esos contratos y asigna un titular (Caso 1).

Caso 4: Configurar un usuario como ADC acotado

1. Confirma que su rol tenga isContractScoped activo (hoy se setea en la base de datos).
2. Asigna ese rol al usuario en /admin/users.
3. Asígnalo como titular o suplente de sus contratos en /admin/contracts.
4. El usuario verá solo sus contratos en ContractHub y en el KPI, y solo podrá operar registros de esos contratos.