Saltar a contenido

SYS-ADR-004 — aasPath como identificador semántico común
Estado Aceptada
Decisión 2026-08, con la implementación del reenvío del Edge
Registrada 2026-09-30
Relacionadas SYS-ADR-001, SYS-ADR-002, SYS-ADR-008
Completada por SYS-ADR-009, que fija la forma canónica cuando la colección está vacía

Contexto

Una variable de la máquina atraviesa cuatro repositorios. En cada frontera necesita un nombre, y sin un identificador común cada componente inventaría el suyo: el dashboard tendría que conocer direcciones de registros Modbus, o el Edge tendría que traducir a un vocabulario propio del frontend.

El estándar Asset Administration Shell ya aporta un vocabulario —submodelo, colección, propiedad— que el historian usa para su modelo semántico. La pregunta era si adoptarlo como identificador de sistema.

Decisión

Sí. El aasPath es el identificador de una variable en todo el sistema aguas arriba de InfluxDB.

Lo compone el Edge a partir de los tags de cada punto de InfluxDB, uniendo con barras los segmentos que el catálogo declara:

aasPath = aas_submodel + "/" + [aas_collection + "/"] + aas_property

La colección es opcional: cuando el catálogo no la declara, el segmento no aparece. Esa forma la fija SYS-ADR-009.

Se propaga sin transformarse: el Edge lo escribe en el evento, entra en el cálculo del eventId, el Cloud lo persiste en payload.aasPath, lo indexa, y lo consulta por igualdad exacta cuando el dashboard pide una métrica.

La fuente de verdad del catálogo es un solo archivo: src/historian/aas_mapping.yaml, del repositorio del historian, montado de solo lectura en el contenedor del historian y en el del Edge. El Edge lo identifica por el sha256 del archivo, no por un número de versión.

Alternativas consideradas

Alternativa Por qué no
Un identificador numérico o un UUID por variable Ilegible, y obligaría a mantener una tabla de correspondencia en cada repositorio
El nombre del tag Modbus Atado al cableado físico: renombrar o recablear rompería el dashboard
Consultar el servidor AAS en tiempo de ejecución Evaluado y descartado: agrega una dependencia de arranque a un servicio que es un override opcional. Ver SYS-ADR-008
Identificador AAS completo del estándar (IRI) Más fiel al estándar y mucho más verboso en cada widget y cada consulta

Consecuencias

A favor:

  • El dashboard habla el vocabulario del dominio industrial, no el del cableado.
  • Un solo archivo gobierna la semántica de los cuatro repositorios.
  • Agregar una variable es agregar una entrada al catálogo y reiniciar los dos contenedores de la Pi.

En contra:

  • Los aasPath del frontend son literales escritos a mano. Un control de CI los compara contra el catálogo, pero todavía no bloquea un PR, así que renombrar una propiedad puede romper widgets en silencio.
  • El catálogo no tiene número de versión ni dueño declarado, y vive en el repositorio de un autor externo al equipo.
  • El cambio de catálogo exige reinicio coordinado de los dos contenedores, y hay una trampa documentada: reconstruir con el compose no recrea los contenedores cuando solo cambió el archivo montado.

La colección vacía

El historian no emite el tag de colección para el submodel Alarmas: esas propiedades cuelgan directo del submodelo, y su aasPath canónico tiene dos segmentos — Alarmas/paradaEmergencia—. Cuál de las dos formas vale, y qué le pasa a las mediciones guardadas bajo la otra, lo decide SYS-ADR-009.

Un job de CI del frontend compara cada literal aasPath del registry contra el catálogo. La regla de composición la deriva del productor y la lee del YAML canónico, no del runtime/catalog.json derivado ni del catálogo observado que devuelve el Cloud, que solo refleja lo que ya fluyó. Falta dejar el job bloqueante, que es el paso 3 de SYS-ADR-009. Ver catálogo de variables.

Evidencia