Flujo Parámetros KPI (motor de scoring)

Base URL: /api/v1. Backend: camaroneras_backend (submódulo reportes/kpi-thresholds) ✅. Admin: camaroneras_admin (feature reportes, página KpiThresholdsPage) ✅. Mobile: no aplica. Décimo módulo; extiende 08 · Reporte semanal con la capa de scoring/priorización de WL Aqua Intelligence v4 (Winston Loaiza): dado el consolidado que ya arma el reporte semanal, calcula 5 semáforos por criterio, un índice de salud (0-100), una prioridad operativa y una recomendación textual, sobre una tabla de umbrales configurable por organización.

Requests y responses 2xx: el shape de la respuesta exitosa está en la API Reference, generada desde el spec OpenAPI. Acá quedan las reglas de negocio, el flujo de cliente y las fórmulas — este submódulo no tiene respuestas de error propias más allá de las genéricas (401/403/400 de validación).

📐 Las fórmulas viven en WL Aqua Intelligence v4 — fórmulas de scoring y KPIs (fuente única): tramos, cortes, penalizaciones, origen de cada dato de entrada y su nivel de confianza. Acá quedan el modelo, el contrato y el flujo de cliente.

Ver ADR-0057 por el detalle de las decisiones no obvias: por qué los umbrales viven en BD y no en código, el trato de "sin dato" y por qué la recomendación (única columna del Excel sin fórmula) se genera igual por reglas.

Modelo

KpiThresholdSet (uno por organización, @unique organizationId) — cortes de prioridad + KpiCriterionThreshold[] (uno de los 5 criterios: fca, supervivencia, crecimiento_diario, crecimiento_3_semanas, carga) — cada uno con penalizaciones (Verde/Amarillo/Rojo/Crítico) y KpiThresholdBracket[] (tramos de peso).

Los tramos NO son iguales entre criterios: FCA tiene 4 (≤10/≤15/≤20/>20 g), supervivencia 5 (≤5/≤10/≤15/≤20/>20 g). Los criterios "planos" (crecimiento diario, crecimiento 3 semanas, carga) se modelan como un solo tramo con maxWeightG = 9999 (sentinel de "sin tope") — así el motor de scoring (kpi-scoring.ts) recorre los 5 criterios con el mismo código, sin una rama aparte para los que no varían por peso.

Semilla por organización

Los umbrales se siembran con los valores exactos de la hoja Parámetros KPI del Excel v4 al crear la organización — mismo punto que las curvas de alimentación (FeedingCurvesService.seedDefaultCurvesForOrg), en ambos caminos de alta: AuthService.onboarding (alta propia) y PlatformOrganizationsService.create (alta desde plataforma). Una organización creada antes de este módulo no tiene set: el primer GET /kpi-thresholds lo siembra al vuelo con los mismos defaults (KpiThresholdsService.getForOrg), sin romper el reporte semanal de organizaciones ya existentes.

Los 5 criterios

Criterio	Valor que evalúa	Dirección	Tramos	Llega a "Crítico"
FCA	fcr	menor es mejor	por peso (4)	sí — único criterio con 4 niveles
Supervivencia (real, la del aguaje)	survivalPct	mayor es mejor	por peso (5)	no
Crecimiento diario	crecimientoDiaG	mayor es mejor	plano	no
Crecimiento 3 semanas	crecimiento3SemanasG	mayor es mejor	plano	no
Carga (lb/ha total, incluye raleo)	lbPorHaTotal	menor es mejor	plano	no

Cortes, penalizaciones, el índice de salud, la regla de prioridad y el catálogo de la recomendación están en la referencia de fórmulas, junto con el origen de cada dato de entrada y qué está verificado contra el xlsx y qué es decisión propia.

Lo que conviene tener presente al leer el contrato de este módulo:

• "Sin dato": si el valor de entrada es null, el criterio marca sin_dato y penaliza 0 — en los 5 criterios, no solo FCA y crec. 3 semanas como en la hoja original (ver ADR-0057). Un 0 en crecimiento 3 semanas también cuenta como sin dato.
• La dirección de los criterios no es configurable: es semántica del dominio. Solo se editan tramos, cortes y penalizaciones.

Columnas nuevas en WeeklyReportRowDto

GET /reports/weekly (ver 08 · Reporte semanal) agrega, por fila: estadoFca, estadoSupervivencia, estadoCrecimientoDiario, estadoCrecimiento3Sem, estadoCarga ("verde" | "amarillo" | "rojo" | "critico" | "sin_dato"), indiceSalud (número), prioridad ("urgente" | "alta" | "media" | "normal") y recomendacion (string). Una piscina sin ciclo activo evalúa sus 5 criterios sobre valores null → 5× sin_dato, índice 100, prioridad normal.

RBAC

• Módulo parametros-kpi (label "Parámetros KPI (scoring)") en el catálogo, clients ["web"].
• Defaults: solo Administrador tiene ver + editar — Técnico y Bodeguero no ven este módulo (a diferencia de reportes, que sí les da ver).

Endpoints (protegidos: AccessJwtGuard + PermissionGuard; tenant del JWT)

GET /kpi-thresholds — (parametros-kpi:ver)

Umbrales vigentes de la organización (los 5 criterios aplanados a nivel superior + cortes de prioridad). Si la organización no tiene set sembrado (creada antes de este módulo), lo siembra al vuelo con los defaults del Excel v4 antes de responder.

PATCH /kpi-thresholds — (parametros-kpi:editar)

Edición parcial: solo se tocan los criterios y/o cortes de prioridad presentes en el body. Editar un criterio reemplaza todos sus tramos (igual que PATCH /feeding-curves/:id con los puntos de la curva) — no hay merge parcial de tramos individuales.

---

Flujo admin (camaroneras_admin, feature reportes)

• Ruta: /parametros-kpi — protegida (ProtectedRoute module="parametros-kpi" action="ver"). Sin sesión → /login; sin permiso → bloqueada y sin ítem de nav (a diferencia de /reportes, Técnico y Bodeguero no ven este ítem).
• Página KpiThresholdsPage: una sección por criterio (tabla de tramos editable + penalizaciones) + una sección de cortes de prioridad. Sin permiso editar, los campos quedan deshabilitados (solo lectura) y no se muestra el botón "Guardar cambios".
• Guardado: un solo botón guarda el formulario completo en un PATCH (los 5 criterios + cortes de prioridad), no ediciones incrementales por campo.
• Tabla de /reportes: agrega columnas "Estados KPI" (5 badges, uno por criterio — variantes de Badge mapeadas semánticamente: verde→default, amarillo→secondary, rojo/crítico→destructive, sin_dato→outline, sin colores hardcodeados), "Índice", "Prioridad" (mismo mapeo de variantes) y "Recomendación" (texto).

---

Backlog / a futuro

• Confirmar con Winston el catálogo definitivo de frases de la recomendación (ver ADR-0057) — hoy es la reconstrucción por reglas, validada 47/47 contra el archivo.
• Ver _planning/_backlog/backlog.md → "WL Aqua Intelligence v4" para las tareas que dependen de este módulo (dashboard-ejecutivo-v4: índice promedio, conteo de prioritarias, ranking de Prioridades).