Integraciones¶
Responde: ¿cuáles son las fronteras entre componentes, y qué garantiza cada una?
Una página por frontera real. No hay una página "API" genérica: una frontera se define por quién habla con quién, no por la tecnología que usa.
Si buscás el recorrido completo de un valor de punta a punta, eso es flujo de datos. Esta sección abre cada tramo por separado.
Las fronteras¶
| Frontera | Qué la atraviesa |
|---|---|
| Catálogo de variables | El aasPath: no es una frontera entre dos piezas, es el contrato que atraviesa las cuatro |
| PLC → historian | Lectura Modbus de registros del PLC |
| historian → InfluxDB | Esquema de puntos: measurement, tags y fields |
| Edge → Cloud (ingesta) | Lotes de eventos con idempotencia |
| Cloud → Edge (chequeos) | Consultas de estado del dispositivo |
| Frontend → Cloud | ABM y consultas de métricas, vía el BFF |
El contrato de cada frontera vive en el repositorio que lo define: los esquemas, los nombres de header, los códigos de error y el orden de las cadenas de middleware se enlazan, no se copian. Lo que va acá es lo que ningún repositorio puede contener: qué asume cada extremo del otro, qué pasa cuando no se cumple, y qué decisiones de sistema sostienen esa frontera.
Qué controla cada frontera en CI¶
Ninguna frontera del sistema se verifica de punta a punta entre dos repositorios.
| Frontera | Qué la cubriría | Qué hay hoy |
|---|---|---|
| Catálogo de variables | Comparar los literales del frontend contra el catálogo canónico | ⚠️ hay un job y pasa, pero no bloquea un PR. Ver catálogo de variables |
| PLC → historian | Leer registros de un PLC real o simulado y comparar con lo esperado | nada sobre el PLC: la única prueba de integración usa el simulador |
| historian → InfluxDB | Escribir y leer contra una InfluxDB real | ⚠️ sí, y es la única — pero no mira los tags. Ver abajo |
| Edge → Cloud | Una prueba de integración contra la API real | nada. El CI del Edge corre go test, pero son unitarios: no levanta dependencias |
| Cloud → Edge | Comprobar que el consumidor siga de acuerdo con el contrato expuesto | ⚠️ lo mejor de las seis, a medias: el OpenAPI del Edge se genera del código y el CI falla si hay deriva, pero nada controla al consumidor |
| Frontend → Cloud | Una prueba de integración del BFF contra la API | nada, y por decisión explícita. Ver Frontend → Cloud |
La única integración real no mira lo que importa
El CI del historian levanta una InfluxDB real, corre el componente contra ella y consulta los datos con Flux. Es real, y no la escribió el equipo. Pero su aserción es que haya al menos 2 valores de las 18 variables, y la consulta no pide los tags.
Los tags son lo único con lo que el Edge identifica una variable. Un cambio que los escribiera con otro nombre pasaría ese CI en verde y rompería el sistema completo aguas abajo. Ver historian → InfluxDB.
Por qué el frontend no tiene contratos¶
Un contrato que nadie verifica documenta una garantía que no existe. El frontend no tiene
contratos Pact por decisión registrada en FE-ADR-013: un pact vale cuando lo emite el
consumidor al ejercitar su propio código, y uno escrito a mano solo repite lo que su autor
creía.
Lo que cubriría esta frontera es una prueba de integración del BFF contra la API real. Ver Frontend → Cloud.
Decisiones de sistema que gobiernan estas fronteras¶
| Decisión | Qué frontera gobierna |
|---|---|
SYS-ADR-002 |
Ingesta: protocolo, idempotencia y credencial por dispositivo |
SYS-ADR-004 |
El aasPath como identificador común de las cuatro |
SYS-ADR-005 |
Chequeos Cloud → Edge, sin autenticación |
SYS-ADR-007 |
PLC: solo lectura, nunca escritura |
SYS-ADR-009 |
La forma canónica del aasPath cuando la colección está vacía. Aplicada en el Edge y en el frontend; queda dejar bloqueante el control del frontend |