import type { Entity, Condition } from '../shared';
import type { Interaction } from '../interaction';
import type { QueryConfig } from './query-config';

/**
 * 数据查询配置
 *
 * 【架构定位】：
 *
 * 1. 它是低代码数据流“三层漏斗”模型的中间层（核心业务层）。
 * 2. 遵循 CQRS 架构，专职处理幂等的“读操作（Read）”。
 * 3. 它是连接底层 DataSource（协议层）与顶层 Component（视图层）的桥梁。
 *
 * 【引擎实现指引】：
 *
 * 渲染引擎应将其映射为一个强大的状态机（如 TanStack Query 的 `useQuery` 实例）。
 *
 * 它不应将 `isLoading`, `data`, `error` 等运行时快照存入此 Schema，
 * 而是由引擎在全局内存（QueryClient）中动态维护这些衍生状态，供组件声明式地订阅。
 */
export interface Query extends Entity {
  /**
   * 执行条件
   *
   * 决定了该查询是否允许被发送（无论是因为页面加载、轮询还是组件订阅）。
   *
   * 核心场景（串行依赖）：
   *
   * 当 Query B 需要用到 Query A 的返回结果作为参数时，
   * 可在此配置 `enabled: { type: 'code', code: 'return !!context.queries.QueryA.data' }`。
   * 引擎会挂起 Query B，直到 Query A 成功返回并填充了数据，Query B 才会被自动放行。
   *
   * 如果不填，默认允许执行。
   */
  enabled?: Condition;
  /**
   * 页面加载时自动执行
   *
   * 性能优化的杀手锏。
   *
   * 如果为 true，引擎在路由命中（或应用启动）的极早期阶段，
   * 在 UI 组件树还未开始渲染时，就提前向服务器发起请求。
   * 这样当底层图表组件渲染完毕并尝试订阅此 Query 时，数据可能已经“热乎”地躺在缓存里了，
   * 从而彻底消灭组件的初始白屏 Loading 时间。
   */
  prefetch: boolean;
  /**
   * 定时轮询策略
   *
   * 数字大屏（Dashboard）的灵魂特性。赋予数据流实时刷新的能力。
   */
  polling: {
    /**
     * 是否开启轮询
     */
    enabled: boolean;
    /**
     * 轮询间隔时间（单位：毫秒 ms）
     *
     * 引擎实现指引：在页面不可见（浏览器标签页隐藏）时，引擎应智能暂停轮询以节省性能。
     */
    interval: number;
  };
  /**
   * 过滤器管道
   *
   * 极其关键的数据转换层（Transform Layer）。
   * 包含了一系列被引用的全局 Filter ID。
   *
   * 引擎实现指引：
   *
   * 当底层 API 返回原始 JSON 后，在存入 Query 内存缓存池（或喂给组件）之前，
   * 必须将原始数据像接水管一样，串行流过这些 Filter 函数。
   * data = filter3(filter2(filter1(rawData)))
   *
   * 优势：让组件拿到的永远是极其纯净、格式规整的业务数据（如 `[{ x, y }]` 数组），
   * 实现了“一份原始接口数据，清洗出多种衍生视图”的极致复用。
   */
  filterIds: string[];
  /**
   * 交互
   *
   * 请求生命周期与副作用控制流
   *
   * 挂载于查询状态突变时的高阶事件侦听器。
   *
   * 引擎实现指引：
   *
   * 1. `onSuccess` (请求成功)：常用于触发数据获取后的连锁反应（如更新某个全局 Variable，或弹出“数据同步成功”的 Toast）。
   * 2. `onError` (请求失败)：常用于统一拦截错误，触发异常上报或显示全局 Error Modal。
   *
   * 这将原本散落在组件里的异步回调地狱，完美收拢到了数据请求自身的配置中。
   * 若无副作用，必须为一个显式的空数组 `[]`。
   */
  interactions: Interaction[];
  /**
   * 具体的请求协议配置
   *
   * 采用极其强大的“多态联合类型（Polymorphism Union Type）”。
   *
   * 它决定了这究竟是一个静态的 Mock 数据（Static），
   * 还是一个通过 HTTP 调用的 REST 请求（Rest），
   * 抑或是一个直连数据库执行的 SQL 语句（Database）。
   *
   * 引擎通过读取 `config.type` 决定派发给哪个底层的 DataSource 客户端去执行。
   */
  config: QueryConfig;
}