import type { Entity, JsonValue } from '../shared';
import type { Interaction } from '../interaction';

/**
 * 全局变量
 *
 * 【架构定位】：
 *
 * 1. 它是低代码平台的“响应式状态中枢（Reactive State Hub）”。
 * 2. 它是连接组件（Component）的输入/输出、驱动查询（Query）动态刷新的核心媒介。
 *
 * 【引擎实现指引】：
 *
 * 渲染引擎启动时，必须扫描所有 Variable 节点，提取其 `key` 和初始 `value`，
 * 并在内存中构建一个支持深度订阅的全局 Store（如 Zustand）。
 *
 * 当任何 Action（如 `setVariable`）修改了该 Store 中的值时，
 * 引擎的响应式机制会自动触发所有绑定了该变量的组件重绘或 Query 重新请求。
 */
export interface Variable extends Entity {
  /**
   * 变量的键名，用于在表达式中作为变量名来引用
   *
   * 核心架构边界：
   *
   * 与仅用于 UI 展示的 `label` (如："当前选中用户") 不同，`key` 是供 JIT 编译器在代码块中求值的真实引用名。
   * (例如：在代码式的配置中通过 `context.variables.currentUser` 来访问它)
   *
   * 引擎约束：
   *
   * 1. 必须严格符合 JavaScript 变量命名规范（正则：/^[a-zA-Z_$][a-zA-Z0-9_$]*$/）。
   * 2. 在当前应用 (Application) 的所有 Variables 列表中必须全局唯一。
   * 3. 它是不可变的“主键”级数据，修改它可能导致海量已绑定的组件或查询报错（引用失效）。
   */
  key: string;
  /**
   * 变量的类型，运行时类型守卫
   *
   * 决定了该变量在内存中允许存储的合法数据类型。
   *
   * 引擎在执行 `setVariable` Action 时，必须先根据此字段进行运行时类型校验 (Runtime Type Checking)，
   * 以防止用户将一个对象强行赋给一个声明为 'number' 的变量，从而引发灾难性的级联崩溃。
   */
  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
  /**
   * 是否为可选变量，默认false
   */
  optional: boolean;
  /**
   * 是否允许变量为null，默认false
   */
  nullable: boolean;
  /**
   * 变量保存的值（初始值）
   *
   * 在 Schema 中，它仅仅代表应用首次加载时（或变量被重置时）的一个“静态快照”。
   *
   * 引擎约束：
   *
   * 为确保该初始快照可以被安全地序列化存入数据库，它必须是一个合法的纯净 JSON 结构，
   * 坚决抵制在此处使用 Function, Date 等无法被 `JSON.stringify` 转换的类型。
   */
  value: JsonValue;
  /**
   * 交互
   *
   * 变量级生命周期与状态监听
   *
   * 挂载于状态节点本身的高阶控制流。
   *
   * 引擎实现指引：
   *
   * 这是低代码中最强大的“连锁反应触发器（Chain Reaction Trigger）”。
   * 当变量的值发生突变时触发（如 `event: 'onChange'`）。
   *
   * 典型场景：
   *
   * 1. 表单联动：当 `selectedProvince` 变量改变时，触发 Action 去清空 `selectedCity` 变量。
   * 2. 异常监控：当 `errorCount` 变量突破阈值时，触发 Action 弹出一个警告对话框 (Modal)。
   *
   * 如果该变量无任何监听逻辑，必须为一个显式的空数组 `[]`。
   */
  interactions: Interaction[];
}