Skip to content

Additional data команд

Параметры команды действия («какое значение выставить», «какое состояние включить») — additional data. Декларации schema-first: тип объекта объявляет в model/schema.ts рядом со схемой настроек события, команды, zod-схемы values каждой команды и UI-мету полей; редактор и контроллер-синхронизация читают эти декларации, а не хардкодят команды.

Декларации типа ​

ts
/** UI-мета поля команды: чем рендерить, какие опции и границы. */
export interface IReactionFieldMeta {
  /** виджет редактора (dropdown/number/time/interval/виджеты таймеров) */
  widget: AdditionalDataType;
  /** локализованный заголовок поля */
  label: string;
  /** опции dropdown: Map/Record значение→лейбл (источник для UI и протокола контроллера) */
  options?: Map<string | number, string> | Record<string, string>;
  /**
   * источник опций dropdown — данные цели, а не статичная карта:
   * "targetStates" = состояния mode-объекта (settings.States, id→имя).
   * Взаимоисключающе с options; resolveFieldProps адаптера читает
   * дескриптор при построении полей.
   */
  optionsSource?: "targetStates";
  /**
   * граница может зависеть от настроек цели (например, Max ≥ Min из настроек);
   * any здесь присущ: мета живёт в общем интерфейсе, а поля настроек у каждого типа свои
   */
  min?: number | ((targetSettings: any) => number);
  max?: number | ((targetSettings: any) => number);
  /** максимум знаков после запятой для number-виджета */
  maxFractionDigits?: number;
  class?: string;
  /** конфигурация виджета-объекта таймера (props поля целиком) */
  timerSetup?: TTimerSetupConfig;
}

/** Мета полей команды: ключи обязаны совпадать с ключами схемы values. */
export type TReactionFieldMetas<TSchema extends z.ZodTypeAny> = Record<
  keyof z.infer<TSchema>,
  IReactionFieldMeta
>;

/**
 * Как тип объекта описывает параметры своих команд для редактора логики.
 * Живёт в model/schema.ts типа (рядом с zod-схемой настроек) и отдаётся
 * редактору через IObjectReactable.actionDeclarations.
 */
export interface IActionDeclarations<TActions extends string = string> {
  /** Zod-схема значений каждой команды: по ней значения из БД проверяются
   *  при загрузке. Команды описываются через satisfies Record<ActionTypeX, ...> —
   *  пропущенная команда не скомпилируется. */
  valuesSchemas: Partial<Record<TActions, z.ZodTypeAny>>;
  /** Как рендерить каждое поле команды: виджет, лейбл, опции, границы. */
  fieldMeta: Partial<Record<TActions, Record<string, IReactionFieldMeta>>>;
  /** Начальные значения команды. Фабрика, а не объект: дефолты зависят
   *  от настроек целевого объекта. */
  defaults: Partial<Record<TActions, (targetSettings: any) => object>>;
  /** CSS-класс контейнера полей команды в редакторе. */
  containerClass?: string;
}

Дефолты — фабрики от настроек цели: например, CMD_CHANGE_VALUE у mode-object берёт состояние с индексом settings.Value цели, а не константу.

Адаптерный конвейер ​

Между декларациями и редактором стоит адаптер. Цель действия разрешается в два вида: editorObject (что показывать — для групп делегированный вид члена) и semanticObject (чей семантикой живут значения).

ts
/**
 * Разрешённая цель действия: одна запись БД, два вида.
 * Для групп — editorObject несёт делегированные перечисления первого члена
 * (редактор показывает команды члена), а semanticObject — реальный объект,
 * чьи настройки/семантика используются в рантайме.
 */
export type ResolvedActionTargetObject = {
  /** объект для UI schema/additionalData list; для групп — делегированный вид */
  editorObject: ReactableTargetObject | TDelegatedGroupView;
  /** реальный target object для runtime semantics */
  semanticObject: ReactableTargetObject;
};
ts
/**
 * Адаптер связи экшена: перевод между тремя видами значений — editor-state
 * (что видит редактор), storedDB (actionData.values в БД) и runtime payload
 * (объект на контроллер). Generic-фабрика строит его из деклараций типа;
 * специализированные — для доменных кейсов.
 */
export interface ActionLinkAdapter extends ILinkAdapter<
  ActionAdditionalDataEditorState,
  Record<string, unknown>,
  Record<string, string | number> | undefined
> {
  /** экшеновое расширение: пересчёт проекций при смене полей команды */
  createEditorState(
    storedDB?: Record<string, unknown>,
    options?: { changedFieldIds?: string[] },
  ): ActionAdditionalDataEditorState;
}

Адаптер additional data команды. Запись в actionDataAdapters цели — знак междоменной связи: фабрика строит поля из чужих данных (состояния/поля цели, записи реестров). Нет записи — связи нет: базовый движок строит поля из собственных деклараций типа (fieldMeta/defaults).

Схема поля и projection ​

Адаптер строит из деклараций поля — схемы редактора (не stored data). Вычисляемые части поля (значение, опции, границы) описываются projection-ом; словарь проекций — доменно-нейтральный, вынесен на отдельную страницу, его же используют драйвер-линки.

ts
/**
 * Schema одного поля нового additional-data editor-а.
 *
 * Важно: это не stored data. Schema живет в adapter layer и описывает,
 * как из `actionData.values` собрать editor-state, какие projections применить,
 * и какой widget показать.
 */
export type ActionFieldDefinition = {
  /** id поля в editor-state; для полей без ключа (виджеты-объекты таймеров) — синтетический `__field_N` */
  id: string;
  valueType: ActionFieldValueType;
  widget: ActionFieldWidget;
  label: string;
  /** начальное значение, когда в actionData.values поля ещё нет */
  defaultValue: unknown;
  /** конфигурация виджета: опции dropdown, границы number или конфигурация виджета таймера */
  props?: TAdditionalFieldData;
  class?: string;
  persistence: FieldPersistence;
  /**
   * Projection описывает не только значение поля, но и editor metadata.
   *
   * `value` - вычисляет само значение поля.
   * Например, PID/SHIM CMD_CHANGE_FIELD подставляет value из выбранного target setting.
   *
   * `options` - вычисляет список вариантов для dropdown.
   * Например, ModeObject CMD_CHANGE_VALUE строит options из target.settings.States.
   *
   * `constraints` - вычисляет ограничения ввода: min/max/step и похожие props.
   * Например, numeric action field может брать min/max из scale settings target object.
   *
   * Эти части разделены, потому что могут зависеть от разных источников
   * и пересчитываться по разным правилам.
   */
  projection?: {
    value?: ActionFieldProjection;
    options?: ActionFieldProjection;
    constraints?: ActionFieldProjection;
  };
};
ts
/** Вычисление значения проекции: объект-владелец + values полей редактора. */
export type TProjectionResolver<TSource> = (
  source: TSource,
  values: Record<string, unknown>,
) => unknown;

/**
 * Поле может не хранить значение, а вычислять его у владельца: так работают
 * опции дропдауна состояний, предзаполнение «изменить на» или адрес в запросе
 * на контроллер. FieldProjection — правило этого вычисления. TSource — тип
 * объекта-владельца; его привязывает потребитель правила (логика экшенов
 * передаёт объект-цель команды).
 */
export type FieldProjection<TSource> = {
  /**
   * Вычисление: получает объект-владельца (TSource) и текущие значения полей
   * редактора; где внутри владельца искать и в каком виде отдать — дело самой
   * функции.
   */
  resolver: TProjectionResolver<TSource>;
  /**
   * При инициализации значение читается один раз и дальше само не меняется.
   * Если оно должно обновляться и после — перечисляем поля команды, при смене
   * которых перечитывать. Смены остальных полей пересчёт не запускают:
   * в частности, ввод руками в само проекционное поле не затирается.
   *
   * @example
   * Команда «изменение поля» PID: [Параметр ▾] [Значение]. Правило «Значения»:
   * { resolver: parameterValue, dependsOn: ["field"] }, где parameterValue
   * читает у цели settings[выбранный параметр]. Открыли команду — подставилось
   * текущее значение выбранного параметра. Переключили «Параметр» —
   * подставилось значение нового. Вписали число руками — живёт, ничем
   * не затирается.
   */
  dependsOn?: string[];
};

Три вида значений ​

Editor-values — что видит и правит редактор (по одному значению на поле, включая virtual). Stored — actionData.values в БД. Runtime — плоский объект ActionCmdData, уходящий на контроллер (toRuntimePayload адаптера). Перевод editor → stored:

Editor-values → stored values (actionData.values): literal-поля пишутся по своему valueKey, reference — stable id, virtual — не пишутся вовсе. Команда с root-полем (виджет-таймер) — исключение: stored values становятся самим объектом виджета, без обёртки в ключ поля.

Специализированные адаптеры ​

Generic-конвейер покрывает декларативные команды; когда runtime-формат или семантика значений расходится с editor-values, команда получает специализированный адаптер. Существующие:

  • change-field — CMD_CHANGE_FIELD у PID и SHIM: value-projection из настроек цели;
  • start-dim — CMD_START_DIM: числовое Value на контроллер без AddData-массива;
  • change-value — CMD_CHANGE_VALUE: ссылочная модель состояний.

Mentioned In ​