Wertzuordnungen: technische Referenz

Diese Seite beschreibt den aktuellen Implementierungsvertrag für Entwicklung und Wartung. Der Leitfaden behandelt die Editorabläufe. Modell und Auflösung sind allgemein; derzeit ist ausschließlich der List-Baustein integriert. Vorlagenspezifische APIs behalten ihre List-Namen und werden ausdrücklich importiert.

Gespeichertes Schema

Maps stehen im optionalen Array ILayoutRoot.valueMaps. Eine Map wird über ihren Namen innerhalb dieses Layouts identifiziert, ohne separate globale Kennung.

type TValueMapOutputType = 'text' | 'number' | 'boolean' | 'asset' | 'textTemplate' | 'htmlTemplate'
type TValueMapTextEditor = 'plain' | 'icon' | 'libraryIcon' | 'color'
type TValueMapOutputValue = string | number | boolean

interface ValueMapShape {
    name: string
    outputs: {
        key: string
        type: TValueMapOutputType
        editor?: TValueMapTextEditor // Nur Textausgaben
    }[]
    rows: {
        match: 'equals' | 'range'
        value?: string // Equals-Vergleichstext
        from?: number // Untere Range-Grenze
        to?: number // Obere Range-Grenze
        fromExclusive?: boolean
        toExclusive?: boolean
        values: Record<string, TValueMapOutputValue>
    }[]
    fallback?: { values: Record<string, TValueMapOutputValue> }
}

Dies ist eine erläuternde Struktur. Importiere die tatsächlichen Typen IValueMap, IValueMapOutput, IValueMapRow und IValueMapValues aus @insynergie/neuroomnet-server-mediacontrol/common/control.

Validierungsaufgaben

Die gemeinsame Schemaregel ValueMaps prüft Struktur und Beziehungen zwischen Definitionen und Regelwerten. Map-Namen/Ausgabeschlüssel müssen nicht leer und in ihrem Geltungsbereich eindeutig sein. Die Schlüssel __proto__, prototype und constructor werden abgelehnt. Werte müssen eigene Eigenschaften eines gewöhnlichen oder Null-Prototyp-Datensatzes, als Ausgaben deklariert und vom exakt geforderten skalaren Typ sein. Zahlenwerte und Grenzen müssen endlich sein. Texteingabehilfen gelten nur für Textausgaben. Null-/Array-/Objektausgaben und das frühere Format mit festen Ausgabefeldern sind ungültig.

Lückenhafte Datensätze sind gültig. Das Schema erzeugt keine fehlenden Schlüssel, wandelt keine Typen um und mischt keine Fallback-Werte ein. Leere oder verdeckte Vergleichsbedingungen erhalten beratende Diagnosen und werden nicht still umsortiert. valueMapDiagnostics stellt die gemeinsame, auch im Editor verwendete Regelanalyse bereit.

Vorlagensyntax wird getrennt geprüft: getValueMapTemplateErrors(layout) parst jeden gespeicherten Text-/HTML-Vorlagenwert in Regeln/Fallback und liefert Fehler mit Feldpfaden. Gewöhnliche Textwerte werden nicht als Vorlagen geparst. Server-Speichern und Import-/Editorgrenzen wenden die jeweiligen Prüfungen an. Syntaktisch gültiger Quelltext kann beim Rendern trotzdem scheitern, etwa durch einen unbekannten Helfer.

Rohwertauflösungs-API

Import aus @insynergie/neuroomnet-server-mediacontrol/common/control/valueMapResolve. Dieses Modul hat keine Handlebars-Abhängigkeit. Aufrufer übergeben ein Map-Objekt, kein Map-Namensverzeichnis.

Funktion	Ergebnis
matchesValueMapRow(row, input)	Ob die Bedingung zur Eingabe passt.
resolveValueMap(map, input)	Erste passende Regel oder Fallback; sonst undefined.
resolveValueMapOutput(map, input, key)	{ row, output, value } für eine deklarierte eigene Ausgabe des gewählten Ergebnisses; sonst undefined.
getValueMapOutput(map, input, key)	Roher Zeichenketten-/Zahlen-/Wahrheitswert oder undefined.

Eine nicht definierte Map liefert kein Ergebnis. Unsichere/nicht deklarierte Schlüssel und fehlende eigene Werte liefern undefined. Ein fehlender Wert einer passenden Regel löst keinen weiteren Regel-/Fallback-Abruf aus. Keine Funktion führt Quelltext aus, erzeugt HTML/Metadaten oder schreibt Variablen.

import type { IValueMap } from '@insynergie/neuroomnet-server-mediacontrol/common/control'
import { getValueMapOutput } from '@insynergie/neuroomnet-server-mediacontrol/common/control/valueMapResolve'

const map: IValueMap = {
    name: 'Availability',
    outputs: [{ key: 'available', type: 'boolean' }],
    rows: [{ match: 'equals', value: 'offline', values: { available: false } }],
}
const available = getValueMapOutput(map, 'offline', 'available')
// available === false; nicht durch einen Wahrheitswert-Ersatz überschreiben.

Der Vergleich verwendet Equals über die Zeichenkettendarstellung und endliche Range-Zahlenumwandlung wie unter Regelvergleich beschrieben. Ein zukünftiger Verbraucher sollte diese Funktionen statt einer zweiten Interpretation verwenden.

Vorlagen-Rendering-API

Ausdrücklicher Import aus @insynergie/neuroomnet-server-mediacontrol/common/control/listTemplate. Der allgemeine Control-Sammelimport lädt den Renderer nicht. Eine isolierte Handlebars-Instanz verhindert, dass Helferregistrierungen andere Handlebars-Nutzer verändern.

interface RenderOptionsShape {
    assetUrl?(reference: string): string | undefined
    poolIconUrl?(key: string): string | undefined
    valueMaps?: Record<string, IValueMap>
}
interface RenderResultShape {
    html: string
    rowClasses: string[]
    diagnostics: {
        code: 'syntax' | 'render' | 'missing-reference' | 'type' | 'cycle' | 'depth' | 'row'
        message: string
        map?: string
        key?: string
        line?: number
        column?: number
    }[]
}

Die tatsächlich exportierten Schnittstellen heißen IListItemRenderOptions, IRenderedListItem und IRenderDiagnostic. renderListItemResult(template, item, options?) liefert das strukturierte Ergebnis. renderListItem(...) liefert als Zeichenkettenfassade nur HTML; verwende das strukturierte Ergebnis für Zeilenmetadaten und Diagnosen.

getTemplateSyntaxError(source) prüft Syntax ohne Ausführung. getListItemTemplateError(source) unterstützt die Prüfung des Eintragseditors durch Rendern gegen einen leeren Kontext und kann auch unbekannte Helfer erkennen. getValueMapTemplateErrors(layout) prüft gespeicherte Fragmentsyntax mit Feldpfaden.

Rendering-Zusagen

• map liefert typisierte Rohwerte/Quelltext und trägt keine Metadaten bei.
• renderMap akzeptiert ausschließlich Text-/HTML-Vorlagendefinitionen, erhält Aufrufkontext/Wurzel und stellt lokale Eingabe/Ausgaben bereit.
• HTML-Quelltext behält selbst verfasstes Markup; gewöhnliche Daten werden maskiert. Textergebnisse bleiben Zeichenketten und werden beim normalen äußeren Einfügen einmal maskiert. Dreifache Klammern umgehen dies bewusst.
• Jeder verschachtelte Aufruf besitzt einen isolierten Rahmen. Nach Rückkehr gelten wieder die Elterndaten. Asset-/Bibliotheksauflösung und Schleifendaten bleiben erhalten.
• Aktive Tupel aus Map-Objekt, ausgewähltem Regelobjekt und Ausgabeschlüssel erkennen Zyklen. Höchstens 32 aktive Fragmentrahmen sind erlaubt; weiteres Verschachteln scheitert lokal. Aufeinanderfolgende Wiederverwendung ist gültig.
• Ein Ausführungsfehler ergibt leeren Fragmentinhalt und verwirft dessen begonnene Klassen, mit Diagnose. Erfolgreicher umgebender Inhalt/Klassen bleibt erhalten. Es wird kein Fallback erneut versucht.
• Textmodus-Ergebnisse tragen niemals Zeilenklassen bei, auch nicht über verschachteltes HTML. HTML-Metadaten werden nur aus erfolgreichen Rahmen vereinigt.
• Ein Ausführungsfehler der äußeren Vorlage ergibt leeres HTML und leere Klassen. Rendering verändert keine verfassten Maps und schreibt keine Laufzeitvariablen.

Die Quelltext-/Moduskompilierung verwendet einen auf 100 Einträge begrenzten Cache. Jedes Rendern erzeugt eigene Metadaten-/Diagnoserahmen; zwischengespeicherte Kompilierung teilt keinen Eintragszustand. Verbraucher sollten Helferergebnisse entsprechend ihrem Typ verwenden statt Zeichenketten automatisch rekursiv auszuführen.

Referenz- und Umbenennungs-APIs

Import aus @insynergie/neuroomnet-server-mediacontrol/common/control/templateReferences. Der Parser lädt Handlebars ausdrücklich. Aktuelle Standardanbieter entdecken List-Elementvorlagen und alle gespeicherten Map-Vorlagenausgaben einschließlich Fallback.

Vertrag/API	Aufgabe
IValueMapConsumerLocation	kind: 'element' | 'map', Index, optionaler Name, Eigenschaft und optionale numerische Regel/'fallback'.
IValueMapConsumer	Ort plus optionaler Vorlagenquelltext/contextMap oder strukturierte Referenz {name, key}.
TValueMapConsumerProvider	Funktion von einem Layout zu Verbraucherdatensätzen.
collectValueMapReferences(layout, providers?)	Geparste Referenzen mit Verbraucher, bekanntem mapName/outputKey, Status und optionaler Zeile.
filterValueMapReferences(references, mapName, key?)	Bekannte Ziele und ungeklärte mögliche Treffer, ohne ein Ziel zu erraten.
valueMapUsages(layout, map, key?)	Verbraucherbeschreibungen für Löschhinweise.
renameValueMap(layout, map, name)	Ändert Map-Name und nachweisbare aktuelle Referenzen; liefert Warnungen.
renameValueMapOutput(layout, map, index, key)	Ändert Definition/gespeicherte Werte/nachweisbare Referenzen; liefert Warnungen.

Referenzstatus sind literal, dynamic und invalid. Literal bezeichnet geparste konstante Namen/Schlüssel, garantiert aber nicht, dass die Definition noch existiert. Gleichartige Wiederholungen innerhalb eines Verbrauchers werden dedupliziert. Dynamische/nicht parsebare Referenzen bleiben mögliche Verwendungen in Filtern.

Übergib zur erweiterten Erfassung [...valueMapConsumerProviders, additionalProvider] an den Collector; das exportierte Standardanbieterarray ist schreibgeschützt. Ein Anbieter kann eine zukünftige strukturierte Referenz beschreiben, ohne Collector oder Verwendungsmodell zu ändern. Dies bereitet die Referenzerfassung vor, ergänzt aber kein Bindungsschema, Rendering oder sichere Umbenennung für ein neues Element. Eine zukünftige Integration muss diese Aufgaben bewusst implementieren und prüfen.

Wörtliche Umbenennungen verwenden geparste Quelltextpositionen statt globaler Zeichenkettenersetzung. Sie folgen map-/renderMap-Aufrufen und bei der eigenen Map @outputs-Pfaden sowie wörtlichen lookup-Schlüsseln. Dynamische Referenzen, fehlerhafter Quelltext und mehrdeutige doppelte Namen/Schlüssel bleiben zur Prüfung bestehen, statt willkürlich einer Map zugeordnet zu werden.

Asset-Lebenszyklus-APIs

Import aus @insynergie/neuroomnet-server-mediacontrol/common/control/layoutAssets.

API	Verhalten
documentLayouts(document)	Findet direktes json, template.json und in Seitenpanels eingebettete Bausteinvorlagenlayouts, auch als JSON-Zeichenkette.
transformDocumentLayouts(document, transform)	Transformiert diese Layouts auf einer strukturierten Kopie; Zeichenketten-/Objektdarstellung und andere Felder bleiben erhalten.
collectDocumentAssetIds(document)	Sortierte eindeutige nicht leere Bild-/Draggable-IDs und typisierte Asset-Werte aller Regeln/Fallbacks.
clearDocumentAssetReferences(document)	Kopiert, leert diese strukturierten Referenzen und entfernt den privaten obersten Verwendungsindex für den Export.

Gespeicherter Vorlagenquelltext, gewöhnliche Textausgaben und Laufzeiteintragsdaten sind bewusst von der Erfassung ausgenommen. Server-Speichern/Startnachpflege leitet _assetIds aus gespeicherten strukturierten Referenzen ab. Dieser Index ist private Persistenzinformation und kein vom Autor geliefertes Protokoll-/Exportfeld. Löschen prüft gespeicherte Verwendungen und lehnt verwendete IDs ab. Eine entfernte Referenz muss gespeichert werden, um das Asset freizugeben.

Export erhält Schemadefinitionen und Quelltext, leert aber typisierte Asset-IDs, Bildlisten und Draggable-Datei-IDs in allen enthaltenen Layouts. False, 0 und leerer Text bleiben erhalten. Import prüft vor Änderung der Arbeitskopie; Medienzuweisungen sind zielsystemspezifisch.

Grenzen zukünftiger Erweiterungen

Die vorhandene Vorbereitung besteht aus allgemeinen typisierten Maps, abhängigkeitsfreier Auflösung, gemeinsamer Validierung/Diagnostik, Asset-Durchlauf und einem Referenzmodell mit Anbietern. Es gibt kein ungenutztes universelles Eigenschaftsbindungsmodell, keinen globalen Map-Katalog, keine Überschreibungsebene, keine Schreibzielabstraktion und keine Bindungsoberfläche anderer Elemente.

Ein zukünftiges Element kann Zahl-/Wahrheitswert-/Text-/Asset-Ausgaben direkt auflösen, ohne HTML-Vorlagen oder Listenklassen zu übernehmen. Es muss sein Eingabe-/Referenzschema, zulässige Ausgabetypen, Verhalten bei fehlenden Werten, Reaktion auf Änderungen und elementspezifische Anwendung des Ergebnisses definieren. Außerdem muss es gegebenenfalls Referenz-/Umbenennungs-/Löschhinweise sowie Export/Asset-Verwaltung integrieren. row und listItem-* bleiben List-Darstellungsdetails und sind keine Anforderungen des allgemeinen Map-Modells.