import type { Entity, Condition, DynamicExpression, JsonValue } from '../shared';

/**
 * 执行动作的目标实体
 *
 * 泛化 RPC 命令动作 (Generalized RPC Command Action)
 *
 * 【架构定位】：
 *
 * 这是整个交互体系的巅峰设计。
 * 我们坚决拒绝将 Action 枚举化为 `ShowToast`, `Navigate`, `SetVariable` 等海量具体类型。
 * 相反，我们采用极其抽象的“一切皆实体（Entity），一切皆方法（Method）”模型。
 *
 * 架构优势：
 *
 * 这种极致抽象保持了 Schema 结构的极简与统一。未来设计器新增几百种组件或系统能力时，
 * Schema 结构一行代码都不用改；渲染引擎只需要一个通用的“方法派发器（Method Dispatcher）”即可支撑无限的扩展能力。
 */
export interface Action extends Entity {
  /**
   * 命令目标 (Target Entity)
   *
   * 告诉引擎：这个命令是发给谁的？
   *
   * 目标类型举例：
   * - `type: 'component'`: 调用画布上的组件（如让图表刷新，或动态修改其 layout）。
   * - `type: 'variable'`: 调用全局变量（如修改当前用户的值）。
   * - `type: 'query'`: 调用全局查询（如手动触发一次 `execute()` 发起网络请求）。
   * - `type: 'system'`: 极其关键！调用引擎提供的全局系统服务（如 `id: 'router'` 进行跳转，或 `id: 'message'` 弹出 Toast）。
   */
  target: {
    type: string;
    id: string;
  };
  /**
   * 目标方法名 (Method Name)
   *
   * 目标实体向外暴露的、可供执行的函数名。
   *
   * 例：组件暴露的 `updateLayout`，系统路由服务暴露的 `navigateTo`。
   */
  method: string;
  /**
   * 执行动作的条件
   *
   * 动作级拦截器 (Action Execution Condition)
   *
   * 在执行此单一动作前的高阶逻辑判断。
   *
   * 若存在此字段且求值为 false，引擎将静默跳过此动作的执行，继续执行下一个动作。
   */
  condition?: Condition;
  /**
   * 方法调用入参 (Method Parameters Payload)
   *
   * 传递给 `method` 的额外数据。
   *
   * 采用“双模设计 (Dual-Mode)”：
   * 既支持固定的 JSON 字典（fixed），也支持极其强大的代码逃生舱（code），
   * 允许在触发动作的一瞬间，通过 JS 代码动态拼装入参（如提取事件源 event 的值）。
   */
  params?: ActionParams;
}

export type ActionParams = ActionParamsByFixed | ActionParamsByCode;

/**
 * 静态表单参数模式
 *
 * 适用于大部分常规场景（如打开弹窗时传个死参数）。
 * payload 里的值在设计时即已确定。
 */
export interface ActionParamsByFixed {
  type: 'fixed';
  payload: Record<string, JsonValue>;
}

/**
 * 动态代码参数模式 (代码逃生舱)
 *
 * 业务场景：
 * 当你需要“点击表格的某一行，提取这一行的数据 ID，传给下一个页面或 Mutation”时。
 * 你必须在此时动态执行一段 JS 函数，从上下文中提取事件源的数据，返回一个 params 对象。
 */
export interface ActionParamsByCode extends DynamicExpression {}