30-verticals/climate-drainage-ngs/readme.md

Vertical reusable: Climate Drainage NGS

Qué es

climate-drainage-ngs es la vertical reusable de MESAVAULT para medición y control de drenaje en invernadero hidropónico NGS.

No representa un nodo concreto ni un cliente concreto. Representa la solución reusable de ingeniería que permite:

1. recibir uplinks del nodo en ChirpStack
2. decodificar correctamente el estado digital de PA12
3. persistir histórico y último valor en PostgreSQL
4. exponerlo en Grafana
5. cambiar remotamente perfiles del nodo:
   • TDC
   • 5VT
6. gobernar esa lógica desde una UI web propia
7. dejar el diseño preparado para varios sensores, no para uno solo

Qué sí pertenece a esta vertical

• arquitectura técnica reusable
• semántica de drenaje visible al usuario
• modelo de datos mv_control.*
• microservicio drain-control
• scheduler
• API
• UI de control
• queries base de Grafana
• criterios de operación
• archivos y rutas clave del sistema

Qué no pertenece a esta vertical

No deben vivir aquí como elemento principal:

• el hardware base del LSN50 v2
• el pinout genérico del nodo
• el datasheet del XKC-Y25-V
• el circuito físico de adaptación LSN50 + XKC

Eso pertenece a:

• 20-assets/models/dragino/lsn50-v2/
• 25-kits/lsn50-v2-xkc-y25-v-drainage/

Tampoco vive aquí el despliegue singular de un cliente concreto. Eso irá en 40-clients/ cuando exista singularidad real.

Arquitectura consolidada

La arquitectura correcta consolidada es:

• OVH aloja el frontal público:
  • Traefik
  • Authentik
  • Grafana del cliente
  • routing /control/*
  • salida por Tailscale hacia platform-40
• platform-40 aloja la lógica real:
  • drain_control_api
  • drain_control_scheduler
  • drain01_norm
  • drain01_pg
  • mv_postgres_hot
  • mv_mosquitto
  • cs_chirpstack
• el nodo LSN50 + XKC sigue siendo el extremo físico
• el dashboard del cliente vive en OVH, no en platform-40
• platform-40 es backend, no frontal cliente

Principios de diseño que definen esta vertical

1. Grafana no controla el nodo directamente

Grafana no debe enviar downlinks directamente a ChirpStack.
La lógica de control vive en un microservicio específico con API, scheduler y auditoría.

2. No exponer servicios internos por IP pública

La UI no debe darse al cliente por 192.168.40.100:8088/ui.
Debe publicarse por OVH, detrás de Traefik y Authentik, integrada en Grafana por iframe.

3. No publicar alegremente en 0.0.0.0

Con Tailscale presente, el criterio correcto es bindear explícitamente a 192.168.40.100.

4. La señal bruta no es semántica de negocio

raw_drain_state no debe mostrarse tal cual al usuario.
La vertical debe distinguir entre:

• señal bruta
• muestra válida
• drenaje interpretado
• estado de control
• semántica final visible al usuario

Componentes lógicos principales

Modelo de control

• mv_control.drain_schedule
• mv_control.drain_downlink_audit
• mv_control.asset_device_map

Backend

• drain_control_api
• drain_control_scheduler

UI

• /ui
• /api/drain-window/current
• /api/drain-window/list
• /api/drain-window
• /api/drain-window/force-active
• /api/drain-window/force-auto
• /api/drain-window/audit

Datos de proceso

• mv_hot.drain_readings
• mv_hot.drain_latest

Estado actual

Esta vertical puede considerarse técnicamente válida porque ya quedó demostrado que:

• la arquitectura de la vertical es válida
• el LSN50 + XKC funciona con el circuito definido
• el decoder correcto es byte6 & 0x02
• el downlink LoRaWAN funciona
• set_tdc y set_5vt funcionan por radio
• la micro-API y el scheduler funcionan
• la UI funciona
• PostgreSQL persiste correctamente
• ya no se confunden muestras de reposo con drenaje real

Referencias cruzadas

• kit físico validado: 25-kits/lsn50-v2-xkc-y25-v-drainage/
• activo base del nodo: 20-assets/models/dragino/lsn50-v2/
• plataforma backend: 10-platforms/homelab/platform-40/
• frontal/tenant: 10-platforms/ovh-cloud/
• BookStack: pendiente_de_crear
• Vaultwarden: pendiente_de_crear