@digitalsee-ai/rcs 0.0.15 → 1.0.1

package/dist/components/digitalsee/workflow/api/dip.types.d.ts

@@ -0,0 +1,996 @@
+import { VisibleWhen } from '../../../dynamic-form';
+/**
+ * 画布坐标位置
+ *
+ * 对应后端 {@link Position} record，用于记录节点在工作流画布上的位置。
+ * 后端默认值为 `Position.origin()` 即 `(0, 0)`。
+ */
+export interface DipPosition {
+    /** X 轴坐标（像素） */
+    x: number;
+    /** Y 轴坐标（像素） */
+    y: number;
+}
+/**
+ * 节点执行模式。
+ *
+ * 这些值会原样写入 DIP 后端的 NodeInstanceSettings.executeMode，前端表单、
+ * 保存数据和运行时都应引用这个枚举，避免散落字符串导致协议值写错。
+ */
+export declare enum DipExecuteMode {
+    /** 将所有输入合并后执行一次（默认） */
+    ONCE = "ONCE",
+    /** 对每条输入数据分别执行一次 */
+    EACH = "EACH"
+}
+/**
+ * 节点错误处理策略。
+ *
+ * CONTINUE_ERROR_OUTPUT 是前端显示 error 输出锚点的唯一条件；切回
+ * STOP_WORKFLOW 时，设置面板会断开该节点 error 锚点上的连线。
+ */
+export declare enum DipNodeOnErrorStrategy {
+    /** 节点失败时停止工作流（默认） */
+    STOP_WORKFLOW = "STOP_WORKFLOW",
+    /** 节点失败时从 error 输出口继续错误处理流程 */
+    CONTINUE_ERROR_OUTPUT = "CONTINUE_ERROR_OUTPUT"
+}
+/**
+ * 节点实例运行时设置
+ *
+ * 对应后端 {@link NodeInstanceSettings} record，控制节点的重试、超时、
+ * 失败策略等运行时行为。
+ */
+export interface DipNodeInstanceSettings {
+    /** 失败后重试次数，默认 0（不重试） */
+    retryCount?: number;
+    /** 重试间隔（毫秒），默认 1000 */
+    retryInterval?: number;
+    /** 执行超时时间（秒），0 表示无限制，默认 0 */
+    timeout?: number;
+    /** 节点错误处理策略，默认 STOP_WORKFLOW */
+    onError?: DipNodeOnErrorStrategy;
+    /** 执行模式：ONCE 合并所有输入执行一次 / EACH 逐条输入分别执行 */
+    executeMode?: DipExecuteMode;
+}
+/**
+ * 工作流中的节点实例
+ *
+ * 对应后端 {@link NodeInstance} record，表示工作流画布上的一个具体节点。
+ * 每个节点通过 `nodeKey` 关联到 {@link DipNodeSchema}，通过 `credentialInstanceId`
+ * 关联到 {@link DipCredentialInstanceEntity}。
+ *
+ * 后端默认值：`params` 为空 Map，`settings` 为 `NodeInstanceSettings.defaults()`，
+ * `position` 为 `Position.origin()`。
+ *
+ * @example
+ * ```ts
+ * const node: DipNodeInstance = {
+ *   id: 'node-1',
+ *   name: 'Send Slack Message',
+ *   nodeKey: 'slack.sendMessage',
+ *   nodeVersion: 1,
+ *   position: { x: 200, y: 100 },
+ *   params: { channel: '#general', text: 'Hello' },
+ * }
+ * ```
+ */
+export interface DipNodeInstance {
+    /** 节点实例唯一标识（UUID） */
+    id: string;
+    /** 节点显示名称，用户可自定义 */
+    name: string;
+    /**
+     * 节点类型标识符，DIP 体系中的全局唯一 key
+     *
+     * 格式通常为 `"provider.action"`，如 `"slack.sendMessage"`、`"http.request"`。
+     * 对应 {@link DipNodeSummary.key} / {@link DipNodeSchema.key}。
+     *
+     * 注意：此字段与 ReactFlow 的节点渲染类型（如 `"ActionNode"`）不同，
+     * ReactFlow 类型通过 `params._uiNodeType` 持久化。
+     */
+    nodeKey: string;
+    /** 节点 Schema 版本号，用于匹配对应版本的 {@link DipNodeSchema} */
+    nodeVersion: number;
+    /** 节点在画布上的坐标位置 */
+    position: DipPosition;
+    /**
+     * 节点参数键值对，对应 {@link DipNodeSchema.input_fields} 中定义的字段。
+     * key 为 {@link DipFieldSchema.key}，value 为用户填写的值。
+     */
+    params: Record<string, unknown>;
+    /** 关联的凭据实例 ID，引用 {@link DipCredentialInstanceEntity.id} */
+    credentialInstanceId?: string;
+    /** 节点运行时设置（重试、超时等） */
+    settings?: DipNodeInstanceSettings;
+}
+/**
+ * 节点间的数据连线
+ *
+ * 对应后端 {@link Connection} record，表示工作流中两个节点之间的数据流向。
+ * 默认端口名为 `"main"`（后端常量 `Connection.DEFAULT_OUTPUT` / `Connection.DEFAULT_INPUT`）。
+ * 后端提供 `Connection.simple(sourceNodeId, targetNodeId)` 快捷方法创建默认端口连线。
+ */
+export interface DipConnection {
+    /** 源节点实例 ID */
+    sourceNodeId: string;
+    /**
+     * 源节点输出端口名
+     *
+     * 默认为 `"main"`；条件节点可能有 `"true"` / `"false"` 等分支端口，
+     * Switch 节点可能有多个自定义输出端口。
+     * @see {@link DipPortSchema.name}
+     */
+    sourceOutput: string;
+    /** 目标节点实例 ID */
+    targetNodeId: string;
+    /**
+     * 目标节点输入端口名
+     *
+     * 通常为 `"main"`，大多数节点只有一个输入端口。
+     * @see {@link DipPortSchema.name}
+     */
+    targetInput: string;
+}
+/**
+ * 工作流错误处理策略
+ *
+ * 对应后端 {@link ErrorStrategy} enum，控制工作流执行遇到错误时的全局行为。
+ *
+ * - `'STOP_WORKFLOW'` — 立即停止整个工作流执行（默认）
+ * - `'CONTINUE'` — 跳过失败节点，继续执行后续节点
+ */
+export type DipErrorStrategy = 'STOP_WORKFLOW' | 'CONTINUE';
+/**
+ * 工作流全局设置
+ *
+ * 对应后端 {@link WorkflowSettings} record，控制工作流级别的执行策略。
+ * 后端默认值通过 `WorkflowSettings.defaults()` 提供：
+ * `(maxExecutionTimeMs=0, errorStrategy=STOP_WORKFLOW, timezone="UTC", saveExecutionData=true, errorWorkflowId=null)`
+ */
+export interface DipWorkflowSettings {
+    /** 工作流最大执行时间（毫秒），0 表示无限制，默认 0 */
+    maxExecutionTimeMs?: number;
+    /** 错误处理策略，默认 STOP_WORKFLOW */
+    errorStrategy?: DipErrorStrategy;
+    /** 时区标识（IANA 格式），用于 Cron 触发器的时间计算，默认 "UTC" */
+    timezone?: string;
+    /** 是否保存执行数据（输入/输出），默认 true */
+    saveExecutionData?: boolean;
+    /** 执行失败时自动触发的错误处理工作流 ID */
+    errorWorkflowId?: string;
+}
+/**
+ * 触发器类型标识
+ *
+ * 对应后端 {@link TriggerConfig} sealed interface 的 `type()` 方法返回值。
+ *
+ * - `'manual'` — 手动触发（{@link DipManualTrigger}）
+ * - `'cron'` — 定时触发（{@link DipCronTrigger}）
+ * - `'webhook'` — Webhook 触发（{@link DipWebhookTrigger}）
+ */
+export type DipTriggerType = 'manual' | 'cron' | 'webhook';
+/**
+ * 手动触发器配置
+ *
+ * 对应后端 {@link ManualTrigger} record，无额外配置字段。
+ * 工作流需通过 API 调用 `/api/executions/trigger/{workflowId}` 手动触发执行。
+ */
+export interface DipManualTrigger {
+    type: 'manual';
+}
+/**
+ * 定时触发器配置
+ *
+ * 对应后端 {@link CronTrigger} record，基于 Cron 表达式定时触发工作流。
+ * 后端在 `timezone` 为空时默认使用 `"UTC"`。
+ */
+export interface DipCronTrigger {
+    type: 'cron';
+    /** 标准 Cron 表达式，如 `"0 0/5 * * * ?"` 表示每 5 分钟执行一次 */
+    expression: string;
+    /** 时区标识（IANA 格式），默认 "UTC" */
+    timezone?: string;
+}
+/**
+ * Webhook 响应模式
+ *
+ * 对应后端 {@link WebhookTrigger.ResponseMode} enum，控制 Webhook 触发后的 HTTP 响应时机。
+ *
+ * - `'IMMEDIATE'` — 立即返回响应，工作流异步执行（默认）
+ * - `'LAST_NODE'` — 等待工作流执行完成，返回最后一个节点的输出
+ * - `'CUSTOM'` — 使用自定义响应数据
+ */
+export type DipWebhookResponseMode = 'IMMEDIATE' | 'LAST_NODE' | 'CUSTOM';
+/**
+ * Webhook 触发器配置
+ *
+ * 对应后端 {@link WebhookTrigger} record，通过 HTTP 请求触发工作流执行。
+ * 后端默认值：`httpMethod="POST"`, `responseMode=IMMEDIATE`。
+ */
+export interface DipWebhookTrigger {
+    type: 'webhook';
+    /** Webhook 路径，拼接到平台 Webhook 基础 URL 后面 */
+    path: string;
+    /** 接受的 HTTP 方法，默认 "POST" */
+    httpMethod: 'GET' | 'POST';
+    /** 响应模式，控制何时返回 HTTP 响应，默认 IMMEDIATE */
+    responseMode?: DipWebhookResponseMode;
+    /** 自定义响应数据（仅 responseMode 为 CUSTOM 时生效） */
+    responseData?: string;
+    /** 是否要求认证，启用后需提供 authHeaderName 和 authHeaderValue */
+    authRequired?: boolean;
+    /** 认证请求头名称，如 `"X-API-Key"` */
+    authHeaderName?: string;
+    /** 认证请求头期望值 */
+    authHeaderValue?: string;
+}
+/**
+ * 触发器配置联合类型
+ *
+ * 对应后端 {@link TriggerConfig} sealed interface，使用 `type` 字段作为判别标识。
+ * @see {@link DipManualTrigger} | {@link DipCronTrigger} | {@link DipWebhookTrigger}
+ */
+export type DipTriggerConfig = DipManualTrigger | DipCronTrigger | DipWebhookTrigger;
+/**
+ * 工作流完整实体（GET 响应）
+ *
+ * 对应后端 {@link WorkflowDefinitionEntity}，包含工作流的完整定义及元数据。
+ * 由 `GET /api/workflows/{id}` 返回，包含服务端生成的 `id`、`version`、时间戳等字段。
+ */
+export interface DipWorkflowDefinitionEntity {
+    /** 工作流唯一标识（UUID，服务端生成） */
+    id: string;
+    /** 工作流名称 */
+    name: string;
+    /** 版本号，每次更新自动递增 */
+    version: number;
+    /** 是否已激活（激活后触发器生效） */
+    active: boolean;
+    /** 工作流中的所有节点实例 */
+    nodes: DipNodeInstance[];
+    /** 节点间的所有连线 */
+    connections: DipConnection[];
+    /** 工作流全局设置 */
+    settings?: DipWorkflowSettings;
+    /** 触发器配置 */
+    triggerConfig?: DipTriggerConfig;
+    /** 创建时间（ISO 8601 格式） */
+    createdAt?: string;
+    /** 最后更新时间（ISO 8601 格式） */
+    updatedAt?: string;
+}
+/**
+ * 工作流定义（PUT/POST 请求体）
+ *
+ * 对应后端 {@link WorkflowDefinition} record 的部分字段，用于创建或更新工作流。
+ * 所有字段均为可选，支持部分更新。
+ */
+export interface DipWorkflowDefinition {
+    /** 工作流 ID（更新时必填） */
+    id?: string;
+    /** 工作流名称 */
+    name?: string;
+    /** 版本号（乐观锁，更新时应传入当前版本） */
+    version?: number;
+    /** 是否激活 */
+    active?: boolean;
+    /** 节点实例列表 */
+    nodes?: DipNodeInstance[];
+    /** 连线列表 */
+    connections?: DipConnection[];
+    /** 工作流全局设置 */
+    settings?: DipWorkflowSettings;
+    /** 触发器配置 */
+    triggerConfig?: DipTriggerConfig;
+}
+/**
+ * 字段类型枚举
+ *
+ * 对应后端 {@link FieldType} enum，决定字段在 UI 上的渲染方式。
+ *
+ * | 值 | 说明 | UI 组件 |
+ * |---|---|---|
+ * | `STRING` | 单行文本 | Input |
+ * | `TEXTAREA` | 多行文本 | TextArea |
+ * | `PASSWORD` | 密码/敏感信息 | Password Input |
+ * | `HIDDEN` | 隐藏字段（不渲染） | — |
+ * | `NUMBER` | 数值 | InputNumber |
+ * | `BOOLEAN` | 布尔开关 | Switch |
+ * | `SELECT` | 下拉选择 | Select |
+ * | `DATETIME` | 日期时间 | DatePicker |
+ * | `OBJECT` | 嵌套对象 | 递归渲染子字段 |
+ * | `ARRAY` | 数组/列表 | 动态增减表单项 |
+ * | `KEYVALUE` | 键值对列表 | Key-Value 编辑器 |
+ */
+export type DipFieldType = 'STRING' | 'TEXTAREA' | 'PASSWORD' | 'HIDDEN' | 'NUMBER' | 'BOOLEAN' | 'SELECT' | 'DATETIME' | 'OBJECT' | 'ARRAY' | 'KEYVALUE';
+/**
+ * 数组元素类型
+ *
+ * 对应后端 {@link ItemType} enum，当 {@link DipFieldSchema.type} 为 `ARRAY` 时，
+ * 指定数组中每个元素的数据类型。
+ */
+export type DipItemType = 'STRING' | 'NUMBER' | 'BOOLEAN' | 'OBJECT';
+/**
+ * 日期选择器模式
+ *
+ * 对应后端 {@link PickerMode} enum，当 {@link DipFieldSchema.type} 为 `DATETIME` 时，
+ * 控制日期选择器的粒度。
+ *
+ * - `'DATE'` — 仅选择日期
+ * - `'TIME'` — 仅选择时间
+ * - `'DATETIME'` — 同时选择日期和时间
+ */
+export type DipPickerMode = 'DATE' | 'TIME' | 'DATETIME';
+/**
+ * 下拉选项
+ *
+ * 对应后端 {@link SelectOption} record，当 {@link DipFieldSchema.type} 为 `SELECT` 时，
+ * 定义可选项列表。
+ */
+export interface DipSelectOption {
+    /** 选项显示文本 */
+    label: string;
+    /** 选项值（提交到后端的实际值） */
+    value: string;
+}
+/**
+ * 字段条件显示规则
+ *
+ * 对应后端 {@link DisplayCondition} record，控制字段在 UI 上的条件可见性。
+ * 当指定的依赖字段满足条件时，当前字段才会显示。
+ *
+ * @example
+ * ```ts
+ * // 当 authType 字段值为 "oauth2" 时显示
+ * { field: 'authType', operator: 'eq', value: 'oauth2' }
+ *
+ * // 当 retryCount 大于 0 时显示
+ * { field: 'retryCount', operator: 'gt', value: 0 }
+ * ```
+ */
+export interface DipDisplayCondition {
+    /** 依赖的字段 key，引用同级 {@link DipFieldSchema.key} */
+    field: string;
+    /**
+     * 比较操作符
+     *
+     * 支持的操作符：
+     * - `eq` — 等于
+     * - `ne` — 不等于
+     * - `in` — 包含在数组中
+     * - `notIn` — 不包含在数组中
+     * - `gt` / `lt` / `gte` / `lte` — 数值比较
+     */
+    operator: string;
+    /** 比较值，单值或数组（配合 `in` / `notIn` 操作符使用） */
+    value: unknown;
+}
+/**
+ * 字段校验规则
+ *
+ * 对应后端 {@link FieldValidation} record，定义字段值的约束条件。
+ * 前端应将这些规则转换为对应的 Ant Design Form 校验规则。
+ */
+export interface DipFieldValidation {
+    /** 最小数值（NUMBER 类型） */
+    min?: number;
+    /** 最大数值（NUMBER 类型） */
+    max?: number;
+    /** 正则表达式模式（STRING / TEXTAREA 类型） */
+    pattern?: string;
+    /** 最小字符长度（STRING / TEXTAREA 类型） */
+    minLength?: number;
+    /** 最大字符长度（STRING / TEXTAREA 类型） */
+    maxLength?: number;
+}
+/**
+ * 字段 Schema 定义
+ *
+ * 对应后端 {@link FieldSchema} record，是 DIP Schema 体系的核心类型。
+ * 描述节点输入字段或凭据字段的完整定义，包括类型、校验、条件显示等。
+ * 前端根据此 Schema 动态渲染表单控件。
+ *
+ * 不同 {@link DipFieldType} 使用不同的可选字段：
+ * - `SELECT` → `options`
+ * - `ARRAY` → `item_type`, `item_schema`, `item_label`, `min_items`, `max_items`
+ * - `OBJECT` → `properties`
+ * - `KEYVALUE` → `key_placeholder`, `value_placeholder`
+ * - `DATETIME` → `picker_mode`
+ */
+export interface DipFieldSchema {
+    /** 字段唯一标识，对应节点 params 中的 key */
+    key: string;
+    /** 字段显示标签 */
+    label?: string;
+    /** 字段类型，决定 UI 渲染方式 */
+    type: DipFieldType;
+    /** 是否必填 */
+    required?: boolean;
+    /** 是否禁用（只读） */
+    disabled?: boolean;
+    /** 输入框占位提示文本 */
+    placeholder?: string;
+    /** 帮助说明文本，通常显示在字段下方或 Tooltip 中 */
+    help_text?: string;
+    /** 默认值，类型应与 {@link type} 匹配 */
+    default_value?: unknown;
+    /** 示例值，用于辅助用户理解期望的输入格式 */
+    example?: string;
+    /** 下拉选项列表（仅 type 为 SELECT 时使用） */
+    options?: DipSelectOption[];
+    /** 数组元素类型（仅 type 为 ARRAY 时使用） */
+    item_type?: DipItemType;
+    /** 数组元素为 OBJECT 时的子字段 Schema（递归定义） */
+    item_schema?: DipFieldSchema[];
+    /** 数组项的显示标签模板 */
+    item_label?: string;
+    /** 数组最少元素数量 */
+    min_items?: number;
+    /** 数组最多元素数量 */
+    max_items?: number;
+    /** 嵌套对象的子字段列表（仅 type 为 OBJECT 时使用，递归定义） */
+    properties?: DipFieldSchema[];
+    /** Key 输入框占位文本（仅 type 为 KEYVALUE 时使用） */
+    key_placeholder?: string;
+    /** Value 输入框占位文本（仅 type 为 KEYVALUE 时使用） */
+    value_placeholder?: string;
+    /** 日期选择器模式（仅 type 为 DATETIME 时使用） */
+    picker_mode?: DipPickerMode;
+    /** 条件显示规则，满足条件时字段才可见 */
+    visible_when?: VisibleWhen;
+    /** 是否支持变量插值（如 `{{node1.output.field}}`） */
+    supports_variables?: boolean;
+    /** 字段值校验规则 */
+    validation?: DipFieldValidation;
+}
+/**
+ * 端口 Schema 定义
+ *
+ * 对应后端 {@link PortSchema} record，描述节点的输入/输出端口。
+ * 后端提供默认常量：`PortSchema.MAIN_INPUT`、`PortSchema.MAIN_OUTPUT`，
+ * 以及 `DEFAULT_INPUTS` / `DEFAULT_OUTPUTS` 列表（均为单个 "main" 端口）。
+ */
+export interface DipPortSchema {
+    /**
+     * 端口标识符
+     *
+     * 用于 {@link DipConnection} 中的 `sourceOutput` / `targetInput` 匹配。
+     * 常见值：`"main"`（默认）、`"true"` / `"false"`（条件节点）。
+     */
+    name: string;
+    /** UI 显示名称，如 "输入"、"True 分支"、"默认输出" */
+    displayName?: string;
+}
+/**
+ * 节点输出字段 Schema
+ *
+ * 对应后端 {@link OutputFieldSchema} record，描述节点执行后输出数据的结构。
+ * 用于下游节点的变量引用提示和数据映射。
+ */
+export interface DipOutputFieldSchema {
+    /** 输出字段标识符 */
+    key: string;
+    /** 字段显示标签 */
+    label?: string;
+    /** 字段数据类型（如 "string"、"number"、"object"） */
+    type: string;
+    /** 字段说明 */
+    description?: string;
+}
+/**
+ * 凭据需求声明
+ *
+ * 对应后端 {@link CredentialRequirement} record，声明节点所需的凭据类型。
+ * 节点可以声明多个凭据需求，用户在配置节点时需选择对应的凭据实例。
+ */
+export interface DipCredentialRequirement {
+    /** 凭据 Schema key，引用 {@link DipCredentialSchema.key} */
+    key: string;
+    /** 是否必须配置凭据 */
+    required: boolean;
+}
+/**
+ * 节点 Schema 完整定义
+ *
+ * 对应后端 {@link NodeSchema} record，是节点类型的完整描述。
+ * 包含节点的输入/输出端口、输入字段、输出字段、凭据需求等信息。
+ * 由 `GET /api/nodes/{nodeKey}` 返回。
+ *
+ * 后端默认值：`inputs` 和 `outputs` 各包含一个 `"main"` 端口，
+ * `credentials` 为空列表。
+ */
+export interface DipNodeSchema {
+    /** 节点类型全局唯一标识，如 `"slack.sendMessage"` */
+    key: string;
+    /** Schema 版本号 */
+    version: number;
+    /** 节点显示名称 */
+    name: string;
+    /** 节点功能描述 */
+    description?: string;
+    /** 输入端口列表，默认为单个 "main" 端口 */
+    inputs?: DipPortSchema[];
+    /** 输出端口列表，默认为单个 "main" 端口 */
+    outputs?: DipPortSchema[];
+    /** 输入字段 Schema 列表，定义节点的配置表单 */
+    input_fields?: DipFieldSchema[];
+    /** 输出字段 Schema 列表，描述节点执行后的输出数据结构 */
+    output_fields?: DipOutputFieldSchema[];
+    /** 示例输出数据，用于预览和调试 */
+    sample?: Record<string, unknown>;
+    /** 节点所需的凭据声明列表 */
+    credentials?: DipCredentialRequirement[];
+}
+/**
+ * 凭据认证类型
+ *
+ * 对应后端 {@link CredentialType} enum，标识凭据的认证方式。
+ *
+ * - `'API_KEY'` — API 密钥认证
+ * - `'TOKEN_EXCHANGE'` — Token 交换认证（如 OAuth1）
+ * - `'OAUTH2'` — OAuth 2.0 认证
+ * - `'BASIC'` — HTTP Basic 认证（用户名/密码）
+ * - `'CUSTOM'` — 自定义认证方式
+ */
+export type DipCredentialType = 'API_KEY' | 'TOKEN_EXCHANGE' | 'OAUTH2' | 'BASIC' | 'CUSTOM';
+/**
+ * 凭据 Schema 定义
+ *
+ * 对应后端 {@link CredentialSchema} record，描述凭据类型的完整配置。
+ * 由 `GET /api/credentials/{credentialKey}` 返回。
+ * 前端根据 `fields` 动态渲染凭据配置表单。
+ */
+export interface DipCredentialSchema {
+    /** 凭据类型全局唯一标识 */
+    key: string;
+    /** Schema 版本号 */
+    version: number;
+    /** 凭据类型显示名称 */
+    name: string;
+    /** 凭据类型描述 */
+    description?: string;
+    /** 认证方式 */
+    type: DipCredentialType;
+    /** 凭据配置字段列表，复用 {@link DipFieldSchema} 定义 */
+    fields?: DipFieldSchema[];
+    /**
+     * 连接标签模板
+     *
+     * 支持 `{{field}}` 占位符，用于在 UI 上显示凭据实例的简短标识。
+     * 例如 `"{{email}}"` 会替换为用户填写的 email 字段值。
+     */
+    connectionLabel?: string;
+}
+/**
+ * 凭据实例实体
+ *
+ * 对应后端 {@link CredentialInstanceEntity}，存储用户创建的具体凭据配置。
+ * 由 `GET /api/credential-instances` 返回。
+ * 注意：`data` 字段在 GET 请求中不返回明文，仅在创建时提交。
+ */
+export interface DipCredentialInstanceEntity {
+    /** 凭据实例唯一标识（UUID） */
+    id: string;
+    /** 凭据实例名称（用户自定义） */
+    name: string;
+    /** 关联的凭据 Schema key，引用 {@link DipCredentialSchema.key} */
+    credentialKey: string;
+    /** 关联的凭据 Schema 版本号 */
+    credentialVersion: number;
+    /** 加密后的凭据数据 JSON（GET 响应中不包含明文） */
+    data?: string;
+    /** 创建时间（ISO 8601 格式） */
+    createdAt?: string;
+    /** 最后更新时间（ISO 8601 格式） */
+    updatedAt?: string;
+}
+/**
+ * 节点摘要信息（列表用）
+ *
+ * 对应后端 {@link NodeSummary} record，由 `GET /api/nodes` 返回。
+ * 每个节点类型只返回最高版本的摘要，用于节点选择面板展示。
+ */
+export interface DipNodeSummary {
+    /** 节点类型全局唯一标识，如 `"slack.sendMessage"` */
+    key: string;
+    /** 最高版本号 */
+    version: number;
+    /** 节点显示名称 */
+    name: string;
+    /** 节点功能描述 */
+    description?: string;
+}
+/**
+ * 凭据摘要信息
+ *
+ * 对应后端 {@link CredentialSummary} record，用于凭据列表展示。
+ */
+export interface DipCredentialSummary {
+    /** 凭据类型唯一标识 */
+    key: string;
+    /** 最高版本号 */
+    version: number;
+    /** 凭据类型显示名称 */
+    name: string;
+    /** 凭据类型描述 */
+    description?: string;
+}
+/**
+ * 插件摘要信息
+ *
+ * 对应后端 {@link PluginSummary} record，由 `GET /api/plugins` 返回。
+ * 描述已加载插件的元数据，包括其提供的节点和凭据数量。
+ */
+export interface DipPluginSummary {
+    /** 插件内部名称（唯一标识） */
+    name: string;
+    /** 插件显示名称 */
+    displayName?: string;
+    /** 插件版本号 */
+    version: string;
+    /** 插件功能描述 */
+    description?: string;
+    /** 插件分类，如 "communication"、"database" */
+    category?: string;
+    /** 标签列表，用于搜索和筛选 */
+    tags?: string[];
+    /** 是否为官方插件 */
+    official?: boolean;
+    /** 插件提供的节点类型数量 */
+    nodeCount: number;
+    /** 插件提供的凭据类型数量 */
+    credentialCount: number;
+}
+/**
+ * 工作流执行状态
+ *
+ * 对应后端 {@link ExecutionStatus} enum，表示工作流整体执行的生命周期状态。
+ *
+ * 状态流转：`CREATED` → `RUNNING` → `COMPLETED` / `FAILED` / `CANCELLED`
+ */
+export type DipExecutionStatus = 'CREATED' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
+/**
+ * 节点执行状态
+ *
+ * 对应后端 {@link NodeExecutionStatus} enum，表示单个节点在工作流执行中的状态。
+ *
+ * 状态流转：`PENDING` → `RUNNING` → `COMPLETED` / `FAILED` / `SKIPPED`
+ *
+ * - `SKIPPED` — 节点因条件不满足或上游失败（且配置了 continueOnFail）而被跳过
+ */
+export type DipNodeExecutionStatus = 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'SKIPPED';
+/**
+ * 工作流执行记录
+ *
+ * 对应后端 {@link WorkflowExecutionEntity}，记录一次工作流执行的完整信息。
+ * 由 `GET /api/executions/{executionId}` 或 `GET /api/executions/workflow/{workflowId}` 返回。
+ */
+export interface DipWorkflowExecutionEntity {
+    /** 执行记录唯一标识（UUID） */
+    id: string;
+    /** 关联的工作流 ID */
+    workflowId: string;
+    /** 执行时的工作流版本号 */
+    workflowVersion: number;
+    /** 执行状态 */
+    status: DipExecutionStatus;
+    /** 触发类型标识（如 "manual"、"cron"、"webhook"） */
+    triggerType?: string;
+    /** 触发时传入的数据 */
+    triggerData?: Record<string, unknown>;
+    /** 执行开始时间（ISO 8601 格式） */
+    startTime?: string;
+    /** 执行结束时间（ISO 8601 格式） */
+    endTime?: string;
+    /** 执行失败时的错误信息 */
+    errorMessage?: string;
+    /** 记录创建时间（ISO 8601 格式） */
+    createdAt?: string;
+}
+/**
+ * 节点执行记录
+ *
+ * 对应后端 {@link NodeExecutionEntity}，记录工作流执行中单个节点的执行详情。
+ * 由 `GET /api/executions/{executionId}/nodes` 返回。
+ */
+export interface DipNodeExecutionEntity {
+    /** 节点执行记录唯一标识（UUID） */
+    id: string;
+    /** 所属工作流执行记录 ID，引用 {@link DipWorkflowExecutionEntity.id} */
+    executionId: string;
+    /** 节点实例 ID，引用 {@link DipNodeInstance.id} */
+    nodeInstanceId: string;
+    /** 节点类型标识，引用 {@link DipNodeSchema.key} */
+    nodeKey: string;
+    /** 执行时的节点 Schema 版本号 */
+    nodeVersion: number;
+    /** 节点执行状态 */
+    status: DipNodeExecutionStatus;
+    /** 节点接收到的输入数据列表（每条输入为一个 Map） */
+    inputData?: Record<string, unknown>[];
+    /** 节点执行后的输出数据列表（每条输出为一个 Map） */
+    outputData?: Record<string, unknown>[];
+    /** 执行失败时的错误信息 */
+    errorMessage?: string;
+    /** 已重试次数 */
+    retryCount?: number;
+    /** 节点执行开始时间（ISO 8601 格式） */
+    startTime?: string;
+    /** 节点执行结束时间（ISO 8601 格式） */
+    endTime?: string;
+}
+/**
+ * 凭据连接测试结果
+ *
+ * 对应后端 {@link CredentialTestResult}，由 `POST /api/credential-instances/{id}/test` 返回。
+ * 后端提供工厂方法：`CredentialTestResult.ok()` / `CredentialTestResult.fail(message)`。
+ */
+export interface DipCredentialTestResult {
+    /** 测试是否成功 */
+    success: boolean;
+    /** 测试结果消息（失败时包含错误详情） */
+    message?: string;
+}
+/**
+ * 导出的节点实例（环境无关）
+ *
+ * 对应后端 {@link ExportedNode}，与 {@link DipNodeInstance} 类似，
+ * 但 `credentialInstanceId` 被替换为 `credentialRef`（引用导出数据中的凭据 key）。
+ */
+export interface DipExportedNode {
+    /** 节点实例 ID */
+    id: string;
+    /** 节点显示名称 */
+    name: string;
+    /** 节点类型标识 */
+    nodeKey: string;
+    /** 节点 Schema 版本号 */
+    nodeVersion: number;
+    /** 节点在画布上的坐标位置 */
+    position: DipPosition;
+    /** 节点参数键值对 */
+    params: Record<string, unknown>;
+    /** 凭据引用 key（指向 {@link DipWorkflowExportData.credentialRefs}） */
+    credentialRef?: string;
+    /** 节点运行时设置 */
+    settings?: DipNodeInstanceSettings;
+}
+/**
+ * 导出的工作流定义（环境无关）
+ *
+ * 对应后端 {@link ExportedWorkflow}，与 {@link DipWorkflowDefinition} 类似，
+ * 但节点使用 {@link DipExportedNode}（凭据引用而非实例 ID）。
+ */
+export interface DipExportedWorkflow {
+    /** 工作流名称 */
+    name: string;
+    /** 版本号 */
+    version: number;
+    /** 节点列表（使用凭据引用） */
+    nodes: DipExportedNode[];
+    /** 连线列表 */
+    connections: DipConnection[];
+    /** 工作流全局设置 */
+    settings?: DipWorkflowSettings;
+    /** 触发器配置 */
+    trigger?: DipTriggerConfig;
+}
+/**
+ * 凭据引用信息
+ *
+ * 对应后端 {@link CredentialRef}，描述导出数据中引用的凭据类型。
+ */
+export interface DipCredentialRef {
+    /** 凭据类型标识 */
+    credentialKey: string;
+    /** 凭据 Schema 版本号 */
+    credentialVersion: number;
+    /** 凭据类型显示名称 */
+    displayName?: string;
+}
+/**
+ * 节点依赖需求
+ *
+ * 对应后端 {@link NodeRequirement}，声明工作流依赖的节点类型及版本。
+ */
+export interface DipNodeRequirement {
+    /** 节点类型标识 */
+    key: string;
+    /** 节点 Schema 版本号 */
+    version: number;
+}
+/**
+ * 工作流依赖需求
+ *
+ * 对应后端 {@link Requirements}，汇总工作流的所有依赖项。
+ */
+export interface DipRequirements {
+    /** 最低平台版本要求 */
+    minPlatformVersion?: string;
+    /** 所需节点类型列表 */
+    requiredNodes?: DipNodeRequirement[];
+    /** 所需凭据类型列表 */
+    requiredCredentials?: DipCredentialRequirement[];
+}
+/**
+ * 工作流导出数据
+ *
+ * 对应后端 {@link WorkflowExportData}，由 `GET /api/workflows/{id}/export` 返回。
+ * 包含工作流定义及其依赖的凭据信息，可跨环境导入。
+ */
+export interface DipWorkflowExportData {
+    /** 导出格式版本号 */
+    formatVersion: string;
+    /** 导出时间（ISO 8601 格式） */
+    exportedAt: string;
+    /** 工作流定义（环境无关） */
+    workflow: DipExportedWorkflow;
+    /** 凭据引用映射表（key → 凭据信息） */
+    credentialRefs: Record<string, DipCredentialRef>;
+    /** 工作流依赖需求 */
+    requirements: DipRequirements;
+}
+/**
+ * 可用的凭据实例（导入时选择用）
+ *
+ * 对应后端 {@link AvailableInstance}，列出目标环境中可用的凭据实例。
+ */
+export interface DipAvailableInstance {
+    /** 凭据实例 ID */
+    id: string;
+    /** 凭据实例名称 */
+    name: string;
+    /** 创建时间 */
+    createdAt: string;
+}
+/**
+ * 凭据映射关系
+ *
+ * 对应后端 {@link CredentialMapping}，描述导入时需要映射的凭据。
+ */
+export interface DipCredentialMapping {
+    /** 导出数据中的凭据引用 key */
+    ref: string;
+    /** 凭据类型标识 */
+    credentialKey: string;
+    /** 凭据 Schema 版本号 */
+    credentialVersion: number;
+    /** 凭据类型显示名称 */
+    displayName?: string;
+    /** 目标环境中可用的凭据实例列表 */
+    availableInstances: DipAvailableInstance[];
+}
+/**
+ * 缺失的依赖项
+ *
+ * 对应后端 {@link MissingDependencies}，列出导入时缺失的节点或凭据类型。
+ */
+export interface DipMissingDependencies {
+    /** 缺失的节点类型列表（格式：`"nodeKey@version"`） */
+    nodes?: string[];
+    /** 缺失的凭据类型列表（格式：`"credentialKey@version"`） */
+    credentials?: string[];
+}
+/**
+ * 工作流摘要信息
+ *
+ * 对应后端 {@link WorkflowSummary}，用于导入验证结果展示。
+ */
+export interface DipWorkflowSummary {
+    /** 工作流名称 */
+    name: string;
+    /** 版本号 */
+    version: number;
+    /** 节点数量 */
+    nodeCount: number;
+}
+/**
+ * 导入验证结果
+ *
+ * 对应后端 {@link ImportValidationResult}，由 `POST /api/workflows/import/validate` 返回。
+ * 包含工作流摘要、凭据映射需求、缺失依赖等信息。
+ */
+export interface DipImportValidationResult {
+    /** 验证是否通过 */
+    valid: boolean;
+    /** 工作流摘要信息 */
+    workflow: DipWorkflowSummary;
+    /** 需要映射的凭据列表 */
+    credentialMappings: DipCredentialMapping[];
+    /** 缺失的依赖项 */
+    missingDependencies?: DipMissingDependencies;
+    /** 验证错误信息列表 */
+    errors?: string[];
+}
+/**
+ * 导入执行请求
+ *
+ * 对应后端 {@link ImportExecuteRequest}，提交给 `POST /api/workflows/import/execute`。
+ */
+export interface DipImportExecuteRequest {
+    /** 导出的工作流 JSON 数据 */
+    workflowJson: DipWorkflowExportData;
+    /** 凭据映射关系（导出凭据 ref → 本地凭据实例 ID） */
+    credentialMappings: Record<string, string>;
+}
+/**
+ * 分页结果（工作流定义）
+ *
+ * 对应后端 {@link PageWorkflowDefinitionEntity}，由 `GET /api/workflows/page` 返回。
+ */
+export interface DipPageWorkflowDefinitionEntity {
+    /** 当前页数据 */
+    records: DipWorkflowDefinitionEntity[];
+    /** 总记录数 */
+    total: number;
+    /** 每页大小 */
+    size: number;
+    /** 当前页码（从 1 开始） */
+    current: number;
+    /** 总页数 */
+    pages: number;
+}
+/**
+ * 节点测试请求（无状态设计）
+ *
+ * 对应后端 {@link NodeTestRequest} record，提交给 `POST /api/nodes/test`。
+ * 前端负责管理测试历史和上下文，后端完全无状态，支持集群部署。
+ *
+ * @see docs/reference/node-test-api.md
+ */
+export interface DipNodeTestRequest {
+    /** 节点类型标识（必填），如 `"http_request"` */
+    nodeKey: string;
+    /** 节点版本，0 或不传表示最新版本 */
+    nodeVersion?: number;
+    /** 节点名称（必填），用于表达式中的 `$node["名称"]` 引用 */
+    nodeName: string;
+    /** 节点参数，支持 `{{ }}` 表达式 */
+    params?: Record<string, unknown>;
+    /** 模拟输入数据（上游节点输出） */
+    inputData?: Record<string, unknown>[];
+    /** 凭据实例 ID（可选） */
+    credentialInstanceId?: string;
+    /**
+     * 其他节点的输出，用于表达式引用
+     * key 为节点名称，value 为该节点的输出数据列表
+     */
+    contextNodes?: Record<string, Record<string, unknown>[]>;
+    /** 超时秒数，默认 30 秒 */
+    timeoutSeconds?: number;
+}
+/**
+ * 节点测试结果
+ *
+ * 对应后端 {@link NodeTestResult} record，由 `POST /api/nodes/test` 返回。
+ */
+export interface DipNodeTestResult {
+    /** 是否执行成功 */
+    success: boolean;
+    /** 失败时的错误信息 */
+    error: string | null;
+    /** 按端口分组的输出数据（成功时）；失败时为 null */
+    outputData: Record<string, Record<string, unknown>[]> | null;
+    /** 表达式解析后的实际参数（方便调试） */
+    resolvedParams: Record<string, unknown> | null;
+    /** 执行耗时（毫秒） */
+    executionTimeMs: number;
+}
+/**
+ * 分页结果（工作流执行记录）
+ *
+ * 对应后端 {@link PageWorkflowExecutionEntity}，由 `GET /api/executions/workflow/{workflowId}/page` 返回。
+ */
+export interface DipPageWorkflowExecutionEntity {
+    /** 当前页数据 */
+    records: DipWorkflowExecutionEntity[];
+    /** 总记录数 */
+    total: number;
+    /** 每页大小 */
+    size: number;
+    /** 当前页码（从 1 开始） */
+    current: number;
+    /** 总页数 */
+    pages: number;
+}