Flujo Muestreos — Biometría y sobrevivencia

Base URL: /api/v1. Backend: camaroneras_backend (módulo muestreos). Admin/mobile: pendientes (tareas muestreos-admin, muestreos-mobile). Tercer módulo de negocio; depende de ciclos. Fórmulas reales de los derivados en referencia/sabana-calculos.md.

Requests y responses 2xx: bodies (tipos, opcionales, enums) y el shape de las respuestas exitosas están en la API Reference, generada desde el spec OpenAPI. Acá quedan solo las respuestas de error (4xx/5xx) y las reglas de negocio/flujo.

Modelo

Cycle ──< Sampling      (muestreo de biometría: peso promedio; frecuente)
      ──< Population     (evaluación de sobrevivencia %; por aguaje)

• Sampling: date, avgWeightG (g), notes. Los derivados se calculan en el service.
• Population: date, survivalPct (0–100), notes.
• Mismo módulo RBAC (muestreos) para ambas entidades.

Derivados (calculados por muestreo; ver sabana-calculos.md)

• incremento = peso − peso del muestreo previo (null en el primero).
• crecimientoPorDia = peso ÷ días de engorde.
• crecDesdeInicioSemanal = (peso − peso inicial de siembra) ÷ (días/7).
• promIncremento = promedio de incrementos de los muestreos en la ventana de 4 semanas.
• diasEngorde = fecha del muestreo − fecha de siembra del ciclo.
• biomasa/lb-ha — solo si hay una Población del mismo día que el muestreo (si no, null):
  • biomasaLb = peso × (survivalPct/100 × cantidad sembrada) ÷ 454.
  • lbHa = biomasaLb ÷ hectáreas de la piscina (sin raleo por ahora).

RBAC

• Módulo muestreos en el catálogo, clients ["web","mobile"].
• Defaults: Administrador todo; Técnico ver/crear/editar; Bodeguero ver.
• Backfill automático a roles por defecto existentes al arrancar.

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

Muestreos

GET /cycles/:cycleId/samplings — (muestreos:ver)

Lista los muestreos del ciclo con sus derivados (ordenados por fecha).

Nota: survivalPct, biomasaLb y lbHa son null si no hay una población del mismo día.

POST /cycles/:cycleId/samplings — (muestreos:crear)

Registra un muestreo de biometría. Devuelve la lista completa con derivados recalculados.

// response 404 (ciclo no existe / de otra org)
{ "error": "...", "message": "Ciclo no encontrado", "statusCode": 404 }

PATCH /samplings/:id — (muestreos:editar)

Edita un muestreo (campos parciales).

DELETE /samplings/:id — (muestreos:eliminar)

---

Poblaciones (sobrevivencia por aguaje)

GET /cycles/:cycleId/populations — (muestreos:ver)

Lista las evaluaciones de sobrevivencia del ciclo (ordenadas por fecha desc).

POST /cycles/:cycleId/populations — (muestreos:crear)

Registra una evaluación de sobrevivencia (por aguaje). Alimenta la biomasa de los muestreos del mismo día.

// response 400 (survivalPct fuera de 0–100)
{ "error": "...", "message": "survivalPct must not be greater than 100", "statusCode": 400 }

PATCH /populations/:id — (muestreos:editar)

DELETE /populations/:id — (muestreos:eliminar)