0043. Raleos: extender Harvest con estado planificado/ejecutado (no un modelo aparte)

Estado

Aceptada

Contexto

La guía de campo del socio incluye una sección de planificación de raleo (gramaje objetivo, # de bines, fecha tentativa → proyecta lb/ha, total y c/m² de raleo) que hoy no existía en raleos: el módulo solo registraba la pesca ya realizada (pounds, avgWeightG requeridos).

Se evaluaron 3 opciones para modelar el plan (ver _planning/alimentacion-teorica-plan.md):

1. Extender Harvest con un estado (planificado | ejecutado).
2. Guardar el plan como campos sueltos del ciclo, sin tocar raleos (una calculadora persistida, sin vínculo con el harvest real).
3. Una calculadora en vivo, sin persistir nada.

Se eligió la opción 1 pese a ser la más cara (migración de un módulo ya implementado y testeado en 3 repos), porque da un solo historial: el mismo registro nace planificado y se completa al pescar, permitiendo comparar plan vs. real sin un segundo sistema de IDs. Las opciones 2 y 3 hubieran duplicado el concepto de "un raleo" en dos lugares.

Decisión

• Harvest gana status (planificado | ejecutado, default ejecutado) y campos de plan (targetWeightG, bins); pounds/avgWeightG pasan a nullable (obligatorios solo cuando status = ejecutado).
• Un plan no cuenta en summary.totalRaleoLb ni en los derivados de sobrevivencia (harvestedCount/survivalPct quedan null); tampoco cierra el ciclo si es cosecha_final. Ejecutar (PATCH con pounds+avgWeightG, status → ejecutado) sí hace ambas cosas.
• Un ejecutado no puede volver a planificado (ya es un registro real; retroceder perdería el dato de la pesca).
• Migración de datos: como es un cambio de nullability sobre un módulo con datos reales potenciales, el default ejecutado para filas existentes preserva el comportamiento actual sin backfill manual.

Consecuencias

• El módulo raleos pasa a ser también el lugar donde se planifica un raleo, no solo donde se registra. La UI (admin/mobile) gana un flujo "Planificar" (crear con status=planificado) y "Ejecutar" (completar libras/peso reales sobre un plan existente), separado de "Editar" (que solo toca fecha/notas/campos de plan).
• La suite e2e existente de raleos (creada antes de esta tarea) sirvió de red de regresión: pasó sin cambios de expectativas tras la migración, confirmando que el default ejecutado es retrocompatible.
• Reporte "plan vs. real" (comparar lo planificado contra lo ejecutado del mismo registro) queda fuera de esta tarea — es la evolución natural ahora que ambos viven en la misma fila; ver backlog.

Referencias

• Tarea alimentacion-teorica (2026-07-16).
• camaroneras_backend/src/modules/raleos/raleos.service.ts.
• camaroneras_docs/modulos/07-raleos-flow.md.
• ADR-0005 — orden de implementación por módulo, seguido también para esta extensión.
• ADR-0033 — decisión previa de unificar raleo y cosecha_final en una sola entidad Harvest con type; esta ADR le suma el eje ortogonal status (planificado/ejecutado) sobre esa misma entidad.