Glosario¶

Términos que aparecen en el código, en los contratos y en la documentación del sistema. Cuando un término tiene una fuente de verdad en el código, se indica.

Dominio industrial y AAS¶

AAS — Asset Administration Shell

Representación digital normalizada de un activo industrial (IEC 63278-1:2023, IDTA-01002). Describe el activo como un conjunto de submodelos con propiedades semánticas. En este sistema, el modelo AAS de la embolsadora lo mantiene el historian.

Submodelo (submodel)

Agrupación de propiedades dentro de un AAS. En la embolsadora: Operativos, Alarmas.

Colección (collection)

Agrupación intermedia dentro de un submodelo. Ejemplos: Pesada, Produccion.

aasPath

Identificador semántico de una variable, con forma Submodelo/Colección/Propiedad
(p. ej. Operativos/Pesada/peso) o Submodelo/Propiedad cuando no hay colección
(Alarmas/paradaEmergencia). Es el contrato transversal más frágil del sistema: atraviesa
los cuatro repos y hoy no tiene validación automática. Ver
integraciones/catalogo-variables.md.: Fuente de verdad: proyecto-embolsadora/src/historian/aas_mapping.yaml.

Catálogo canónico

proyecto-embolsadora/runtime/catalog.json y catalog.md, generados desde aas_mapping.yaml. Es la lista de variables que el sistema puede producir.

Catálogo observado

Lo que devuelve GET /api/v1/dashboards/metrics/catalog del Cloud: los aasPath que ya fueron vistos para una máquina. No sirve para validar, porque solo refleja lo que ya fluyó: tras renombrar una propiedad sigue mostrando el nombre viejo.

FA³ST

Servidor AAS de código abierto (Eclipse FA³ST) que corre en la Raspberry Pi y sirve el modelo AAS por HTTP en el puerto 8081. Hoy no tiene consumidores en el sistema.

Historian

El middleware Python de proyecto-embolsadora: lee el PLC por Modbus, escribe en InfluxDB y actualiza el modelo AAS. Pertenece a una tesis de maestría distinta del Proyecto Final.

Modbus TCP

Protocolo industrial con el que el historian lee los registros del PLC. Solo lectura: el sistema no escribe nunca hacia el PLC.

PLC

Controlador lógico programable de la máquina embolsadora. Su programación está fuera del alcance del proyecto. Hoy el stack local usa un mock (MODBUS_HOST=mock).

Arquitectura del sistema¶

BFF — Backend for Frontend

Capa de rutas del lado servidor en Next.js (src/app/api/**) que el navegador consume. El
navegador nunca llama directo a la Cloud API: el BFF inyecta el Authorization: Bearer y
el X-Tenant-ID.: Fuente de verdad: embolsadora-frontend/src/lib/backend-fetch.ts.

Edge Pi Service

El servicio Go de embolsadora-edge que corre en la Raspberry Pi. Expone endpoints de estado hacia el Cloud y reenvía eventos desde InfluxDB hacia el Cloud.

Superficie ABM

/api/v1/** de la Cloud API. Autenticación JWT + RBAC + tenant. Gestión de usuarios, tenants, roles, dispositivos.

Superficie de ingesta (consumers)

/api/v1/consumers/** de la Cloud API. Autenticación por API key, sin JWT y sin header de tenant. Es la que consume el Edge. Su contrato de respuesta y sus códigos de error son un contrato congelado.

Tenant

Cliente del sistema (una empresa que opera embolsadoras). Todo dato de negocio está particionado por tenant. MRG tiene un tenant de plataforma con capacidad cross-tenant.

Cross-tenant

Capacidad de ciertos roles de plataforma (MRG) de operar sobre datos de cualquier tenant.

Resiliencia e ingesta¶

Outbox: Tabla SQLite local en la Pi donde el Edge encola los eventos antes de enviarlos al Cloud. Permite seguir capturando datos si se cae el enlace. Buffer de al menos 24 horas.
Watermark: Marca de tiempo del último punto de InfluxDB ya procesado por el Edge. Permite reanudar sin duplicar ni perder datos tras un reinicio.
SAFETY_LAG: Retardo que el Edge aplica al leer InfluxDB, para no leer puntos que todavía están llegando.
Idempotencia: Garantía de que reenviar el mismo lote no duplica datos. Se implementa con un header Idempotency-Key por lote y un eventId único por evento, con índice único en MongoDB.
Dead-letter: Destino de los eventos que agotaron sus reintentos. El Edge emite además un evento de tipo alarm idempotente para que el problema sea visible.
Fail-open: Comportamiento de degradación en el que un componente caído no bloquea la operación. En este sistema, Redis: si no responde, el rate limiting deja de aplicarse pero la API sigue funcionando.
Degradación aislada: Que la caída de un componente afecte solo a su funcionalidad. MongoDB caído degrada la ingesta y los dashboards, pero el login y el ABM siguen funcionando.
schemaVersion: Versión del formato de cada evento de ingesta. Permite cambios incompatibles con período de convivencia, necesario porque las Raspberry Pi se actualizan después que el Cloud.

Seguridad¶

JWKS: Conjunto de claves públicas que publica Supabase y que la Cloud API usa para verificar la firma de los JWT. El verificador admite solo ES256 y RS256, y el proyecto firma con ES256. Si JWKS no responde, la API devuelve 503.
Auto-provisioning: Alta automática del usuario en la base local la primera vez que llega con un JWT válido. Es idempotente (ON CONFLICT (supabase_user_id)).
RBAC dinámico: Los permisos de cada rol se leen de la base de datos, no de un mapa fijo en el código, lo que permite roles personalizados por tenant.
API key de dispositivo: Credencial por edge device con la que el Edge se autentica contra la superficie de ingesta. Se guarda hasheada en Postgres y en texto plano solo en la Pi.

Proceso y documentación¶

ADR — Architecture Decision Record: Registro de una decisión difícil de revertir. Formato MADR, un archivo por decisión, inmutable. Prefijo SYS- para decisiones de sistema (en este repo) y FE-, CLOUD-, EDGE-, HIST- para decisiones de componente (en cada repo).
Diátaxis: Marco que divide la documentación según la necesidad del lector: tutorial, how-to, referencia y explicación.
arc42: Plantilla de 12 secciones para documentar arquitectura. Acá se usa en versión liviana.
C4: Modelo de diagramas de arquitectura en cuatro niveles: contexto, contenedores, componentes y código. Se usan los niveles 1 y 2 para el sistema y el 3 solo donde aporta.
Drift check: Verificación en CI de que un artefacto generado (p. ej. el OpenAPI) sigue correspondiendo al código. El Edge ya lo tiene; es el modelo a replicar.
Harness documental: El conjunto mínimo y obligatorio de artefactos de documentación que todo repo de componente debe tener: su README, sus ADR, sus especificaciones y su bitácora de alcance.

Organizaciones¶

M.R.G. Equipamientos S.R.L.: La empresa fabricante de las máquinas embolsadoras, destinataria de la transferencia tecnológica.
UTN FRSF: Universidad Tecnológica Nacional, Facultad Regional Santa Fe.
TECPRO 2024: Programa de transferencia tecnológica en cuyo marco se desarrolla el proyecto (Proyecto N.º 125).