import type { Entity } from '../shared';
import type { Action } from './action';

/**
 * 实体交互
 *
 * 泛化事件侦听器
 *
 * 【架构定位】：
 *
 * 低代码平台中负责响应任何“状态突变”的唯一入口。
 * 它的名字虽叫 Interaction（人机交互），但在架构底层，它不仅监听物理鼠标键盘，
 * 更监听系统级的数据流转。
 *
 * 【引擎实现指引】：
 *
 * 根据它所挂载的宿主实体不同，引擎应将其映射为不同的事件绑定：
 * 1. 挂载于 Component：映射为 DOM 原生事件或 React 组件暴露的业务事件（如 `onClick`, `onScroll`, `onRowSelect`）。
 * 2. 挂载于 Route/Page：映射为生命周期钩子（如 `onEnter`, `onLoad`）。
 * 3. 挂载于 Query/Mutation/Variable：映射为数据流的状态回调（如 `onSuccess`, `onError`, `onChange`）。
 */
export interface Interaction extends Entity {
  /**
   * 触发时机/事件名称 (Event Name)
   *
   * 引擎会根据此名称去注册对应的监听器。
   */
  event: string;
  /**
   * 触发频率控制 (Debounce & Throttle)
   *
   * 处理高频数据流（如 Input 搜索框的 `onChange` 联动触发后端 Query）的核心防御机制。
   *
   * 引擎实现指引：
   *
   * 如果 enabled 为 true，引擎在派发底层的 `actions` 数组前，
   * 必须先经过 Lodash 或 es-toolkit 的 `debounce` 或 `throttle` 包装器。
   */
  control: {
    enabled: boolean;
    type: 'debounce' | 'throttle';
    delay: number;
  };
  /**
   * 原生事件修饰符 (Event Modifiers)
   *
   * 引擎实现指引：
   *
   * 仅当该 Interaction 是由原生 DOM 事件（如 onClick 冒泡或 Form 默认提交）触发时生效。
   * 如果是 `Query.onSuccess` 这种纯逻辑事件，此配置应被忽略。
   */
  modifiers: {
    preventDefault: boolean;
    stopPropagation: boolean;
  };
  /**
   * 动作执行序列 (Action Chain)
   *
   * 当事件触发（且通过频率控制与修饰符拦截）后，引擎需要按顺序串行（或并行）执行的命令集合。
   *
   * 必须为一个数组，允许一个按钮点击同时触发“保存数据”和“跳转页面”两个动作。
   */
  actions: Action[];
}