Evaluación operativa (API)

Además de la categoría (nodo), la confianza y las acciones derivadas, la respuesta de catalogación puede incluir una evaluación operativa orientada a triaje y reporting.

Dos «versiones» que no deben confundirse

Qué	Qué significa aquí
Endpoint v1 o v2	La ruta (`/api/v1/…` o `/api/v2/…`) y el resto del JSON de respuesta. La v2 añade campos extra (p. ej. `apiVersion`, `vectorAugmented`, `semanticMatches`).
`evaluacionOperativa.version`	La versión del esquema del bloque `evaluacionOperativa` (riesgo operativo, impacto, etc.). Hoy es siempre `'v1'` en código, tanto si llamas a v1 como a v2 del endpoint.

En resumen: cambiar de endpoint v1 a v2 no cambia la forma de evaluacionOperativa; solo incorporas más datos en la respuesta global. Si en el futuro el bloque pasa a esquema 'v2', se documentará aquí el diff de campos.

Campos del objeto `evaluacionOperativa` (esquema actual, `version: 'v1'`)

Campo	Valores	Notas
riesgoOperativo	`Bajo` \| `Medio` \| `Alto`	Combina el peor nivel de los riesgos enlazados (R.xx: bajo/medio/alto/crítico) con la urgencia de la ficha del vault.
impactoServicio	`Bajo` \| `Medio` \| `Alto`	Derivado principalmente de la urgencia del nodo (`alta` → Alto, `media` → Medio, `baja` → Bajo).
criticidadActivo	`Baja` \| `Media` \| `Alta`	Según `fm_type`: `hard` / `mixto` → Alta; `soft` → Media.
tipoActuacion	`Correctiva` \| `Preventiva` \| `Correctiva y preventiva`	Heurística: incidencias duras con urgencia ≥ media o riesgo alto suelen marcar Correctiva y preventiva (intervención + revisión).
prioridadSugerida	`Baja` \| `Media` \| `Alta`	Prioriza cuando la urgencia es alta o hay riesgos catalogados altos/críticos.

El objeto incluye version: 'v1' y resumenCriterio: una línea técnica con urgencia, fm_type, máximo nivel de riesgo y recuento de riesgos (auditoría).

Dónde aparece

POST/GET /api/catalogar-incidencia: propiedad raíz evaluacionOperativa y copia en humanReadable.evaluacionOperativa. Si no hay nodo (bestNodeId nulo), es null.
POST /api/v1/catalogar-incidencia: evaluacionOperativa en el JSON minimal.
POST /api/v2/catalogar-incidencia: evaluacionOperativa también se devuelve en el JSON compact, junto con campos v2 (vectorAugmented, semanticMatches).

Contratos OpenAPI para Actions:

En ambos, evaluacionOperativa mantiene estructura v1 mientras no se publique una versión nueva del objeto.

Autenticación (v1 y v2)

Para endpoints públicos de catalogación:

Header obligatorio: x-api-key cuando hay auth activa.
Se valida contra CATALOGACION_API_KEY y/o claves gestionadas en DB (catalogacion_api_keys).
Sin clave válida, la API responde 401.

Implementación

Lógica en src/lib/evaluacion-operativa.ts. Es complementaria al SLA y a la redacción de la ficha en el vault; no sustituye el criterio del administrador ni del técnico.

Para evolucionar criterios (p. ej. matriz por familia F01/F10), subir versión a v2 y documentar el diff aquí.

Ejemplo ilustrativo

Un nodo con urgencia media, fm_type hard y riesgos con nivel ALTO en catálogo puede producir (según reglas v1):

Riesgo operativo: Medio
Impacto servicio: Medio
Criticidad activo: Alta
Tipo actuación: Correctiva y preventiva
Prioridad sugerida: Alta

Los valores exactos dependen de la combinación concreta de urgencia y niveles R.xx.