Añadir climate-drainage-ngs/docs/semantica-drenaje.md

climate-drainage-ngs/docs/semantica-drenaje.md

@@ -0,0 +1,61 @@
+# Semántica de drenaje
+
+## Problema
+
+La señal bruta no puede mostrarse al usuario final como si fuera una verdad directa de negocio.
+
+`raw_drain_state` por sí solo no basta.
+
+## Regla base
+
+La vertical debe distinguir entre:
+
+- señal bruta
+- muestra válida / no válida
+- estado de drenaje interpretado
+- estado de control
+- semántica final visible al usuario
+
+## Motivo
+
+Una entrada digital no significa automáticamente “medición válida”.
+
+Depende de si el sensor estaba alimentado o no.
+
+## Caso de reposo
+
+Cuando el nodo está en reposo con:
+
+- `5VT = 0`
+
+la lectura no debe interpretarse como drenaje.
+
+La semántica correcta en ese caso es:
+
+- `NO_SAMPLE`
+
+## Caso activo
+
+Cuando el sistema está en `ACTIVE` y el sensor está alimentado, la lectura sí puede interpretarse como muestra válida.
+
+## Regla operativa consolidada
+
+- `ACTIVE` -> la lectura es válida
+- `SLEEP + 5VT=0` -> no hay muestra válida
+- reposo sin alimentación != drenaje
+
+## Qué no debe verse en pantalla
+
+El usuario no debe ver ingeniería interna cruda como único dato principal.
+
+No debe tomarse `raw_drain_state` como panel final.
+
+## Qué debe verse
+
+El usuario debe ver estados prácticos y robustos.
+
+El objetivo de la vertical no es enseñar bits, sino soportar una operación comprensible y útil.
+
+## Consecuencia práctica en Grafana
+
+Las queries y paneles finales deben basarse en semántica útil (`semantic_state`) y no en el bit bruto aislado.