Especificación · Gestor+

Modelo de datos

Gestor+ vive en tres nodos de la base compartida: el catálogo institucional de plantillas, el mapa de quién responde qué, y los riesgos que cada persona va formulando. Conocer el tercero exige entender una dualidad de claves que rompe cualquier vista que la ignore.

Mapa general

plantillas_config/{KEY}                // catálogo institucional (596 plantillas)
plantillas_asignadas/{claveUsuario}/{KEY} = true
riesgos_ptep/{uid}/{riskId}            // riesgos formulados, por usuario
GESTORPLUS/riesgos/counters/{SLUG}/{TIPO}  // consecutivos de los creados desde cero

Compartidos con la suite:
usuarios/{correoSaneado}               // perfil, roles_map y el puente uid

plantillas_config

El catálogo. La clave es el propio identificador del riesgo, así que la plantilla y el riesgo que nace de ella comparten código. Estructura completa en Plantillas de riesgo.

Campo	Descripción
`key` · `slug` · `procId` · `n`	Identidad y ubicación en el mapa de procesos.
`riskType`	`gestion` · `integridad` · `fiscal` · `informacion`.
`causaInmediata` · `causaEstructural`	Redacción institucional, con su conector incluido.
`factorOrigen` · `elementoMaterializacion` · `efectoDanoso`	Clasificación. El último solo en riesgos fiscales.
`preguntas[]`	La caracterización, con `descarta_if_no`.
`estado`	`pendiente` → `formulada` \| `descartada`. Marca el consumo de la plantilla.

La fuente de verdad es la base, no el código. En el frontend existe un catálogo semilla congelado con datos anteriores a la reformulación; no debe usarse para nada que no sea arranque en frío. Toda modificación va a la base.

plantillas_asignadas

plantillas_asignadas/{claveUsuario}/{KEY} = true

Determina qué ve cada líder. Si una plantilla no está asignada, su responsable simplemente no la encuentra.

La clave de usuario no es homogénea. Las asignaciones se guardan bajo correo saneado, mientras que los riesgos se guardan bajo uid de autenticación. La aplicación escucha ambas formas y las fusiona; cualquier vista nueva debe hacer lo mismo.

riesgos_ptep

riesgos_ptep/{uid}/{riskId} = {
  riskId, riskNum, fromTemplate,
  process:  { id: "p13", name: "Gestión Financiera" },
  riskType: { id: "fiscal", name: "Riesgos fiscales" },
  status:   "borrador" | "descartado" | "pendiente",
  step:     4,                       // paso donde quedó el asistente

  causaInmediata, causaEstructural, factorOrigen, elementoMaterializacion,
  matrix:         { p, i, value, zone, criterios[] },   // inherente
  matrixResidual: { p, i, value, zone },                // tras controles
  controlesList[], valores, tipologiaIntegridad,
  descarte,                          // justificación firmada, si se descartó
  sugerenciaDesc,                    // descripción institucional compuesta
  submittedAt, submittedBy, submittedByName, submittedByUid,
  createdAt, updatedAt
}

Los borradores no guardan quién es su dueño. El campo de autoría solo se llena al enviar. Para saber de quién es un borrador hay que resolver el uid de la ruta contra el directorio, lo que exige el índice descrito abajo.

El puente uid ↔ correo

El directorio de usuarios está indexado por correo saneado, pero los riesgos cuelgan del uid de autenticación. El campo que une ambos mundos es el uid guardado dentro de la ficha del usuario, que la aplicación escribe al iniciar sesión.

usuarios/{correoSaneado}/uid = "MzN6F9ZDniaJEblzWTq6gTp4n682"

Regla al construir una vista nueva: si vas a mostrar el dueño de algo guardado por uid, resuélvelo contra un índice uid → usuario. Buscar la clave directa en el directorio devuelve nada, y la columna termina mostrando el uid crudo.

Convenciones

La clave es el identificador

Plantilla y riesgo comparten código: eso es lo que permite ir del mapa al catálogo y al revés.

Conectores incluidos

Las causas se guardan con su «por» y su «debido a». El formulario los muestra como etiqueta fija.

Dos claves de usuario

Correo saneado para asignaciones y directorio; uid para riesgos. Siempre fusionar.

Escrituras masivas

Se hacen con scripts que usan credenciales de administración, con simulación previa y sin pisar lo ya diligenciado.

Antes de escribir en la base

Respalda el nodo que vas a tocar; hay un espacio de respaldos para eso.
Simula primero: los scripts de carga deben poder correr sin escribir.
Nunca sobrescribas una plantilla ya formulada o descartada: perderías el rastro de la respuesta.
Preserva las marcas de creación al reescribir una plantilla.
Valida que la sigla exista en el catálogo de procesos y que el tipo use el identificador interno, no el prefijo.
Si tocas asignaciones, recuerda que la clave es el correo saneado.

Relacionado: Identificadores · Roles y permisos.