Especificación · PolariScore

Modelo de datos

Todo PolariScore vive bajo el prefijo PolariScore/ de la base Realtime Database del proyecto sigunitropico —la misma que usan el resto de aplicaciones de la suite—. Un árbol anidado con las políticas y tres nodos hermanos para seguimiento, evidencias y directorio.

Mapa general

PolariScore/ ├── politicas/{P-00n} │ ├── objetivos_especificos/{OBJ-0n} │ │ └── acciones/{IAP-00n} │ │ ├── anios[] — programación por posición │ │ ├── Indicador — hitos + programación anual │ │ └── evidencias{} — copia legado, casi vacía │ ├── documentos/{pushId} — actos administrativos, informes │ ├── historial_total_politica/{DD-MM-AAAA} │ ├── total_acciones_completadas/{DD-MM-AAAA} │ └── total_evidencias/{DD-MM-AAAA} ├── seguimientos/{IAP-00n} — ejecutado por año + historial ├── evidencias/{IAP-00n}/{EV-00n} — catálogo real + uploads por ciclo ├── responsables/{Rn} — copia local del directorio ⚠ datos personales ├── config/notif_emails — destinatarios de los correos ├── meta/nextPoliticaNumber — secuencia de ids └── fecha_actualizacion Fuera del prefijo (compartidos con la suite): usuarios/{correoSaneado} — correo, nombre, roles_map responsables/{Rn} — directorio institucional (lo escribe la carga masiva) notificaciones/{pushId} — feed unificado, app: "polariscore"

Política

Campo	Tipo	Descripción
`id`	string	`P-001`… El siguiente número lo reserva `meta/nextPoliticaNumber`.
`titulo`	string	Nombre de la política.
`objetivo_general`	string	El propósito declarado en el acto administrativo.
`fecha_politica`	string	`DD/MM/AAAA`. Su año define el año inicial con el que se mapea el arreglo `anios` de cada acción.
`importancia_politica`	number	Valor descriptivo heredado del formato de carga. No pondera unas políticas frente a otras: la suma de todas no da 1.
`totalPolitica`	number 0–100	El cumplimiento calculado. Se refresca al abrir la ficha de la política.
`historial_total_politica`	object	`{ "DD-MM-AAAA": valor }` — una entrada por día en que el total cambió. Alimenta la curva de evolución.
`objetivos_especificos`	object	Los objetivos, indexados por `OBJ-0n`.
`documentos`	object	Documentos oficiales de la política (ver abajo).
`responsables`	string	Códigos separados por coma: `"R136, YJ88WH"`. Se resuelven contra el directorio.
`correos_responsables`	string	Correos de contacto, también separados por coma.
`imgUrl`	string	Imagen de portada de la ficha.
`total_evidencias` · `total_acciones_completadas`	object	Series por fecha con conteos históricos: `{ "01-07-2026": { total: 15 } }`.
`fecha_actualizacion`	number · string	Marca del último cambio. Conviven timestamps y fechas `AAAA-MM-DD` según quién escribió.

Objetivo específico

Campo	Tipo	Descripción
`id_objetivo`	string	`OBJ-01`…
`objetivo_especifico`	string	El enunciado del objetivo.
`importancia_objetivo`	number 0–1	El peso que sí cuenta. Los objetivos de una política deben sumar 1; nada lo valida.
`acciones`	object	Las acciones, indexadas por `IAP-00n`.

Acción

Campo	Tipo	Descripción
`id_accion`	string	`IAP-001`… Es único en todo el sistema, no por política: los índices de seguimiento y evidencias cuelgan de él.
`accion`	string	Lo que se compromete a hacer.
`indicador`	string	Descripción corta de lo que se mide (texto libre).
`Indicador`	object	El indicador formal, con hitos y programación anual. Ojo a la mayúscula: es un nodo distinto del anterior. Ver Indicadores e hitos.
`anios`	array	Arreglo contiguo con lo programado por año, en orden. Su longitud define el horizonte de la acción (hoy hay de 6, 7 y 8 años).
`importancia_accion`	number 0–1	Peso de la acción. No interviene en el cumplimiento del objetivo; solo lo usa el KPI agregado de la v1.
`forma_acumulacion`	string	`Flujo` · `Acumulado` · `Stock` · `Reducción`. Informativo, con variantes de mayúsculas sin normalizar.
`tipo_dato_acumulado`	string	`entero` · `porcentaje`.
`total_valor_politica`	number	Copia del valor de la política que traía la fila del Excel de carga.
`evidencias`	object	Legado Copia embebida del catálogo de evidencias. Está casi vacía: la fuente real es `PolariScore/evidencias`.

Dos campos, un nombre. indicador (minúscula) es una cadena descriptiva que viene del Excel; Indicador (mayúscula) es el objeto con hitos y programación creado desde la aplicación. Coexisten y no se sincronizan.

Seguimientos

La ejecución no vive dentro de la acción: vive en un índice plano por identificador de acción. Así se escribe sin tocar el árbol de la política.

PolariScore/seguimientos/IAP-001 = {
  ejecutado: { "2023": 1, "2024": 1, "2025": 1, "2026": 0, "2027": 0, "2028": 0 },
  historialEvaluacion: {
    "04-02-2026":   { ejecutado: {…}, fecha: "2026-02-04T23:11:52.389Z", id_usuario: "…@unitropico_edu_co" },
    "04-02-2026_1": { … }
  }
}

ejecutado se indexa por año calendario, no por posición.
El historial se versiona por día, con sufijo _1, _2… si hay varias evaluaciones el mismo día.
La escritura es por hijo: ampliar el horizonte de una política no borra los años ya registrados.

Evidencias

También indexadas por identificador de acción. Cada evidencia declarada acumula una carga por ciclo:

PolariScore/evidencias/{idAccion}/{idEvidencia} = {
  titulo, formato, peso_max, estado, id_responsable,
  uploads: {
    "{ciclo}": {
      nombre, size, type, url, usuario, fecha_subida,
      estado, estado_actualizado_por, estado_actualizado_en,
      observaciones{}, auditoria_estado{}, auditoria_cambios{}
    }
  }
}

Los identificadores de evidencia conviven en dos formas: EV-001 (los del catálogo cargado por Excel) y claves push de Firebase (las creadas desde la aplicación). Ambas son válidas. Detalle en Evidencias y ciclos.

Documentos de la política

Distintos de las evidencias: son los documentos oficiales de la política, no los soportes de una acción.

PolariScore/politicas/{P-00n}/documentos/{pushId} = {
  titulo, descripcion, nombre_archivo, tipo_mime, peso_bytes,
  storage_path: "PolariScore/politicas/P-001/documentos/{pushId}/{archivo}",
  url, url_flip,          // url_flip: versión hojeable en FlipHTML5, opcional
  cargado_por, fecha_registro
}

Configuración

Nodo	Contenido
`config/notif_emails`	`{ enabled, list: { emailKey: correo }, updatedAt, updatedBy }` — quién recibe los correos de aviso. La clave del correo lleva los caracteres especiales reemplazados por guiones bajos.
`meta/nextPoliticaNumber`	Contador para reservar el siguiente identificador de política.
`fecha_actualizacion`	Marca global de la última actualización del conjunto.

Responsables y datos personales

Las políticas guardan códigos (R136), no personas. El directorio con los datos reales existe en dos sitios: PolariScore/responsables/{Rn} y el directorio compartido responsables/{Rn} de la raíz —que es el que actualiza la carga masiva—.

responsables/R136 = {
  id, nombre_completo, cargo, area,
  correo, correo_personal, documento
}

Trátalo como dato personal. Incluye documento de identidad y correo personal. No debe exponerse en integraciones ni exportaciones abiertas. La API que alimenta esta documentación publica únicamente el conteo de responsables. Ver Permisos.

Dos copias del mismo directorio es una duplicación heredada: las escrituras recientes van a la raíz, mientras que la copia bajo PolariScore/ puede quedar desactualizada. Al resolver un código, prefiere la raíz.

Convenciones que hay que conocer

Posición contra año

anios es por posición; ejecutado es por año. El puente es el año de fecha_politica.

Fechas como clave

Los historiales usan DD-MM-AAAA: el orden alfabético no es cronológico. Hay que parsear para ordenar.

Correos saneados

Como clave, el correo lleva los puntos y símbolos convertidos en guiones bajos.

Ids globales

IAP-00n es único en todo el sistema. Seguimientos y evidencias cuelgan de él sin repetir la política.

Antes de escribir en la base

Haz respaldo del subárbol que vas a tocar.
Guarda anios como arreglo contiguo: un objeto disperso subcuenta el horizonte.
Si amplías el horizonte de una política, escribe ejecutado por hijo para no borrar años existentes.
Verifica que los pesos de los objetivos sigan sumando 1.
Recuerda que totalPolitica no se recalcula solo: hay que abrir la ficha de la política.
Aplica los cambios pensando en las dos versiones: comparten datos, no código.