0061. Las fórmulas de valores calculados viven en referencia/, no en los *-flow.md

Estado

Aceptada

Contexto

Los cinco derivados del Excel v4 (motor-kpis-scoring, sabana-columnas-derivadas, ciclo-temporada, dashboard-ejecutivo-v4, sobrevivencia-estimada-vs-real) se cerraron entre el 2026-08-04 y el 2026-08-05, cada uno documentando sus fórmulas en el *-flow.md del módulo que las expone. El resultado era correcto pero disperso: los tramos y penalizaciones estaban en 10-parametros-kpi-flow.md, los agregados en 09-dashboard-produccion-flow.md, y el archivo fuente (WL_Aqua_Intelligence_v4_data_actualizada.xlsx) no se mencionaba en referencia/ — donde ya vivían las otras dos referencias de fórmulas del proyecto (sabana-calculos.md, guia-campo-ab.md).

Faltaba además, de forma sistemática, el origen de los datos de entrada: se documentaba la fórmula, pero no de qué tabla Prisma sale cada insumo ni con qué criterio se selecciona (por ejemplo, que raleoLb suma solo type = 'raleo' y status = 'ejecutado').

La auditoría de los 11 módulos que motivó esta decisión encontró tres defectos que la dispersión ayudaba a esconder:

• El FCR tiene dos definiciones en el sistema: en alimentacion el denominador es la biomasa del último muestreo sin raleo; en la sábana/dashboard es biomasa + raleo. Cada *-flow.md documentaba la suya correctamente y ninguno decía que diferían.
• 09-dashboard-produccion-flow.md afirmaba que densidadHa se suma "solo sobre piscinas con ciclo", cuando el código usa las filas con larvaeCount — y el comentario del código aclara explícitamente que no son lo mismo.
• Cuatro punteros a _docs/referencia/... sobrevivieron a la migración a camaroneras_docs porque estaban escritos como código en vez de links markdown, así que el gate docs:build (que solo falla ante links rotos) no los detectó.

Decisión

Las fórmulas de valores calculados viven en referencia/, en un archivo por fuente de negocio. Los *-flow.md documentan contrato, RBAC y flujo de cliente, y enlazan.

• Se crea referencia/wl-aqua-v4-kpi-formulas.md como fuente única de la capa de scoring del Excel v4. Los módulos 09, 10 y 11 pierden sus bloques de fórmula y apuntan ahí.
• Cada valor documentado lleva fórmula + origen del dato de entrada (tabla Prisma y criterio de selección) + dónde se calcula (archivo del backend).
• El documento declara el nivel de confianza de cada regla: fórmula literal del socio, valor literal de la hoja, reconstrucción validada contra las 47 filas, o decisión propia de implementación. No se mezcla lo verificado con lo inferido.
• El .xlsx no se copia al repo de docs: es un artefacto de planificación (_planning/_referencia/), se cita por ruta — igual que la sábana de Google Sheets.

Consecuencias

A favor:

• Un valor calculado se rastrea hasta su fórmula y sus insumos sin leer código.
• Las inconsistencias entre módulos (como las dos definiciones de FCR) se vuelven visibles al quedar las fórmulas una al lado de la otra, en vez de en dos archivos distintos.
• La distinción explícita entre "fórmula del socio" y "decisión nuestra" evita repetir el error que ya ocurrió una vez: la primera lectura del xlsx se hizo con data_only=True (solo valores) y llevó a inferir mal la regla de prioridad, que parecía función pura del índice y en realidad suma conteos de semáforos.

En contra / a vigilar:

• Centralizar reduce la duplicación pero no elimina la deriva: si alguien cambia kpi-scoring.ts sin tocar la referencia, la doc miente con más autoridad que antes. Por eso cada tabla indica el archivo donde vive el cálculo.
• Leer el contrato de un módulo ahora requiere un salto extra a referencia/ para ver los números. Se acepta: el *-flow.md conserva lo que se necesita para consumir el endpoint (qué campos hay, sobre qué filas se calculan), y el detalle numérico es justamente lo que no debería estar duplicado.
• El gate de docs no detecta rutas stale escritas como texto plano. Queda anotado en el backlog evaluar un lint que prohíba la cadena _docs/ fuera del README puntero.

Referencias

• referencia/wl-aqua-v4-kpi-formulas.md — el documento resultante.
• ADR-0057, ADR-0059, ADR-0060 — las decisiones de implementación cuyas fórmulas centraliza.
• _planning/_backlog/backlog.md → "Derivados de doc-formulas-wl-aqua-v4" — los hallazgos de la auditoría que exceden documentar.