From 7bb7b509c9e76dafe630b3db4ab1d05e171eb372 Mon Sep 17 00:00:00 2001
From: "victor.fraile" <victor.fraile@mesavault.es>
Date: Wed, 25 Mar 2026 16:01:14 +0000
Subject: [PATCH] =?UTF-8?q?A=C3=B1adir=20climate-drainage-ngs/docs/semanti?=
 =?UTF-8?q?ca-drenaje.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../docs/semantica-drenaje.md                 | 61 +++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 climate-drainage-ngs/docs/semantica-drenaje.md

diff --git a/climate-drainage-ngs/docs/semantica-drenaje.md b/climate-drainage-ngs/docs/semantica-drenaje.md
new file mode 100644
index 0000000..d8401da
--- /dev/null
+++ b/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.
\ No newline at end of file