HIF / Документация / Архитектура

Модель взаимодействия HIF

1. Назначение

Модель взаимодействия переводит Конституцию в архитектурные понятия. Она не предписывает конкретный framework или язык программирования.

Нормативная цепочка:

намерение человека
→ семантическая команда
→ проверка предусловий и полномочий
→ переход состояния
→ событие и история
→ представление результата

DOM event, pointer gesture или keyboard shortcut не является продуктовой командой. Это только один из способов выразить намерение.

2. Базовые сущности

2.1. Actor

Участник, способный инициировать действие:

человек;
система;
другой пользователь;
внешний сервис;
автоматизация;
AI agent.

Actor имеет идентичность, роль, права и контекст.

2.2. Object

Сущность предметной области с устойчивой идентичностью:

файл;
проект;
окно;
приложение;
сборка;
релиз;
пользователь;
устройство;
документ.

Object не равен своему представлению.

2.3. View

Представление одного или нескольких объектов:

строка;
карточка;
окно;
вкладка;
значок;
страница;
notification;
voice response.

Несколько View MAY ссылаться на один Object. Закрытие View не определяет удаление Object.

2.4. Command

Намеренное действие с определённым контрактом:

type Command = {
  id: string;
  actor: ActorRef;
  target: ObjectRef;
  parameters: unknown;
  preconditions: readonly Condition[];
  requiredPermissions: readonly Permission[];
  effect: Effect;
  reversibility: "reversible" | "compensatable" | "irreversible";
  risk: "low" | "moderate" | "high" | "critical";
};

Конкретная реализация MAY отличаться, но смысловые поля должны быть доступны архитектуре и проверкам.

2.5. Event

Факт, произошедший в системе. Command выражает намерение, Event фиксирует результат.

release.publish requested
release.publish accepted
release.published

Command MAY завершиться отказом и породить event отказа.

2.6. State

Набор фактов, актуальных в определённый момент. State не должен выводиться из случайной комбинации CSS-классов.

2.7. Policy

Правило, определяющее допустимость действия:

permission;
data retention;
movement;
removal;
approval;
validation;
environment capability.

2.8. Context

Условия использования:

устройство и viewport;
способы ввода;
network и performance;
locale;
настройки доступности;
роль и полномочия;
текущая задача;
физическая и социальная среда.

3. Состояния компонента

Минимальный набор различимых осей:

availability: enabled | disabled | unavailable
interaction: idle | hover | focused | active
selection: unselected | selected | mixed
disclosure: collapsed | expanded
operation: ready | pending | success | error | cancelled
validation: unknown | valid | invalid | warning
visibility: visible | hidden | offscreen

Оси не должны склеиваться без доменного основания. Например:

focused не означает selected;
disabled не означает hidden;
error не означает invalid user input;
pending не означает success.

4. Жизненный цикл команды

4.1. Формирование

Интерфейс собирает намерение, target и параметры. Значимые параметры должны быть обозримы до выполнения.

4.2. Проверка

Система проверяет:

существование target;
актуальность state;
права;
валидность параметров;
конфликт;
необходимость approval;
доступность зависимости.

4.3. Принятие

После принятия интерфейс немедленно показывает, что действие зарегистрировано. Это не обязательно означает завершение.

4.4. Выполнение

Для длительной операции показываются status, progress, возможность отмены и последствия ухода со страницы.

4.5. Завершение

Результат связывается с исходной задачей и target. Система различает success, partial success, cancelled и failed.

4.6. Восстановление

При ошибке сохраняется всё, что можно безопасно сохранить, и предлагается следующий допустимый command.

5. Input bindings

Продукт определяет semantic commands независимо от ввода:

pointer click ─────┐
Enter ─────────────┼── object.open
voice "open" ──────┤
automation API ────┘

Профиль среды задаёт bindings:

pointer;
keyboard;
touch;
pen;
switch control;
voice;
remote control;
automation.

Bindings могут различаться. Effect и требования безопасности остаются одинаковыми.

6. Focus

Focus — системный ресурс, показывающий, какой элемент получает keyboard или assistive-technology input.

6.1. Правила

В каждый момент существует не более одной основной точки focus в одном контексте.
Focus должен быть видимым.
Порядок должен соответствовать структуре и задаче.
Открытие dialog переносит focus внутрь.
Закрытие возвращает focus инициатору или безопасной точке.
Disabled control не должен создавать ловушку.
Composite widget управляет внутренним focus по согласованной grammar.

6.2. Focus и selection

Selection описывает выбранный объект. Focus описывает получателя ввода. Они могут совпадать, но не являются одной сущностью.

7. Навигационные модели

HIF допускает несколько моделей:

линейная;
иерархическая;
пространственная;
search-first;
command-first;
workspace;
document history;
graph;
conversational.

Продукт MUST определить:

текущую позицию;
родительский или исходный контекст;
механизм перехода;
механизм возврата;
поведение deep link;
сохранение state при возврате.

Смешение моделей допустимо, если границы различимы.

8. Layers и modes

Типовые слои:

content
navigation
floating surface
overlay
system
modal
critical

Каждый слой определяет:

z-order;
focus ownership;
способ dismissal;
scroll ownership;
влияние на нижние слои;
влияние на доступность.

Mode SHOULD использоваться только тогда, когда одинаковый input действительно меняет значение на ограниченный период. Активный mode должен быть заметен и иметь способ выхода.

9. Undo и компенсация

9.1. Reversible

Система способна вернуть прежнее state без потери смысла.

9.2. Compensatable

Нельзя отменить факт, но можно выполнить компенсирующее действие. Например, опубликованный релиз нельзя «не публиковать задним числом», но можно отозвать.

9.3. Irreversible

Восстановление невозможно или не гарантируется. Такой command требует:

ясного target;
масштаба последствия;
объяснения необратимости;
усиленной проверки при высоком риске.

Подтверждение не должно использоваться для каждого действия: постоянные диалоги приучают подтверждать автоматически.

10. Время обратной связи

Временные диапазоны являются рабочими ориентирами, а не универсальным законом:

до примерно 100 ms реакция воспринимается как непосредственная;
до примерно 1 s требуется ясное подтверждение, но поток обычно сохраняется;
при более долгой операции требуется состояние выполнения;
длительные операции SHOULD позволять продолжить другую работу.

Система не должна имитировать завершение ради ощущения скорости.

11. Ошибки

Ошибка описывается структурно:

type InteractionError = {
  kind:
    | "invalid-input"
    | "permission"
    | "conflict"
    | "dependency"
    | "system"
    | "policy";
  target?: ObjectRef;
  recoverable: boolean;
  nextCommands: readonly CommandRef[];
  technicalReference?: string;
};

Пользовательская формулировка и технические детали разделяются. Технический reference должен позволять поддержку и аудит, не раскрывая секреты.

12. Automation и AI

Agentic interaction использует ту же командную модель.

request
→ proposed plan
→ scoped permissions
→ preview
→ approval where required
→ command execution
→ observable events
→ result and recovery

AI output не является command, пока он не прошёл проверку схемы, полномочий и политики.

Интерфейс MUST различать:

текстовую рекомендацию;
подготовленный draft;
предложенный plan;
выполняемое действие;
подтверждённый результат.

13. Сотрудничество

Для multi-user interface определяются:

actor каждого изменения;
актуальность state;
optimistic/pessimistic locking;
конфликт и merge;
presence;
history;
права просмотра и изменения;
приватные и общие представления.

Presence не должна создавать ложное ощущение просмотра данных другим пользователем, если система показывает только доступность или подключение.

14. Трассировка

Каждая существенная функция SHOULD иметь цепочку:

user goal
→ task
→ object
→ command
→ state transition
→ event
→ view
→ automated test
→ evaluation task

Разрыв цепочки означает, что функция либо не имеет продуктового основания, либо не может быть надёжно проверена.