ADR-05 · Los indicadores se calculan en la base

Estado: aceptada · Impacto: alto

Contexto

Los ocho indicadores se consultan desde el tablero web, desde el resumen móvil y desde los reportes exportables.

Decisión

Cada indicador se calcula en una sola función SQL. La API los expone y los clientes los pintan, pero ninguno de los dos vuelve a dividir nada.

Por qué

Si el cálculo vive en la aplicación, tarde o temprano habrá dos rutas que lo calculan distinto — el tablero y el reporte, o la web y el móvil. Y cuando dos pantallas del mismo sistema dan cifras diferentes para el mismo periodo, no importa cuál tiene razón: el sistema pierde credibilidad entero.

Con la lógica en la base sólo hay una respuesta posible.

Detalle que importa

Cada función devuelve valor, numerador, denominador y tamaño de muestra, no sólo el porcentaje. Eso permite dos cosas:

1. Mostrar «95 de 120» junto al 79,1 %, que es mucho más informativo.
2. Reagregar periodos sin caer en el error de promediar porcentajes, que es el fallo más común al construir un tablero por semanas o por meses.

Qué NO vive en la base

Autorización, orquestación, integraciones y todo lo que hable con el exterior. La base calcula sobre hechos registrados; no toma decisiones ni llama a nadie.

Verificación cruzada

La función de evaluación contra meta existe dos veces: en Rust (crm-core) y en TypeScript (@crm/design-tokens/helpers). Es deliberado — el front necesita evaluar en render optimista — y ambas tienen que dar el mismo resultado. Si divergen, es un bug.

Relacionado: Los ocho indicadores · Base de datos