API 集成

基于 CONSIM BeApi 的实时数据联动

API 集成概述

智绘 与 CONSIM BeApi 深度集成，让仿真模型能够在执行过程中实时读取外部数据、回写决策结果，并与实际系统保持一致。

引入真实数据

从 ERP、MES、IoT 平台等系统同步关键指标，让仿真逻辑随现状变化而更新。

回写仿真决策

将排程、预测或告警信息推送回外部系统，形成业务闭环。

实时闭环

条件与动作调用均为同步执行，仿真引擎可以依赖外部响应即时决策。

核心组件：
  • API 接口管理：维护 CONSIM 基址及端点，完成健康检查和元数据刷新。
  • API 绑定：将对象/过程图元与条件或动作接口关联，仿真时自动调用。
  • 脚本 API：在脚本中通过 api 对象直接访问 BeApi 或自定义 HTTP 服务。

配置 CONSIM 接口

在创建绑定或编写脚本之前，请先确认前端与后端都指向正确的 CONSIM BeApi 服务。

1. 打开接口管理

  1. 点击菜单栏 “工具” → “API 接口”（触发 window.showApiInterfaceConfigDialog()）。
  2. 或在工具栏“更多”菜单中选择 API 接口。

2. 设置基础信息

  • 使用 “使用LAN IP / 使用127.0.0.1” 开关，可在局域网地址与本地回环之间快速切换。
  • 若部署在其他主机，直接编辑 CONSIM API 基址（如 http://192.168.1.120:3001）。
  • 高级端点通常保持默认值，仅在后端路由调整时修改。
配置项 用途 默认值
CONSIM API 基址 所有接口请求的基础地址 http://本机IP:3001
健康检查 测试服务可用性的 GET 端点 /api/v1/be/health
条件评估 执行条件绑定时调用的 POST 端点 /api/v1/be/conditions/evaluate
动作执行 执行动作绑定时调用的 POST 端点 /api/v1/be/actions/execute
批量条件评估 可选的批量调用端点，存在时自动启用 /api/v1/be/conditions/batch-evaluate
条件/动作列表 为绑定对话框提供下拉选项 /api/v1/be/conditions/available / /api/v1/be/actions/available
单元列表 刷新可选的 unitId /api/v1/be/units
默认单元 ID 当绑定未填写 unitId 时的回退值 可留空或填写默认单元

3. 测试并刷新元数据

  1. 点击 “测试连接”，系统会调用健康检查端点并展示返回状态。
  2. 点击 “刷新外部数据”，依次更新单位、条件、动作和参考点缓存。
  3. 刷新成功后，时间戳会显示在对话框右上角，绑定下拉框即可使用最新数据。

前端配置保存在浏览器本地存储，并通过 WebSocket 同步到服务端的 config/api-config.json，确保仿真引擎与前端配置一致。

API 接口管理对话框

API 接口管理对话框

管理 API 绑定

API 绑定将 OPM 图元与外部条件或动作关联，对应配置保存到项目文件的 apiBindings 字段，并在仿真会话中实时加载。

1. 打开配置窗口

  1. 在画布上选中对象、状态或过程图元。
  2. 右键选择 “配置 API”，或在属性侧边栏点击 “管理 API 绑定”。

2. 条件绑定（对象 / 状态）

  • 选择 条件类型，选项来源于接口管理下载的列表。
  • 设置 单元 ID（unitId），可使用“刷新”按钮同步最新单位。
  • 根据需要配置 比较运算符 与 阈值。
  • 系统会根据条件定义提供智能参数表单，也支持手工添加键值对。
  • 点击 “测试 API”，后端会即时执行条件检查并返回布尔结果。

3. 动作绑定（过程）

  • 在 动作类型 下拉框选择需要触发的动作。
  • 填写顶层参数（如 unitId、priority），并在参数区域补充业务字段。
  • 参数表单同样支持智能提示与自定义扩展。
  • 使用 “测试 API” 验证请求格式及接口连通性。

4. 保存与同步

  • 点击 “保存配置”，绑定写入前端 window.apiBindingManager 并在画布上显示 API 标记。
  • ApiBindingBridge 通过 WebSocket 触发 simulation:sync-api-binding，后端即时更新。
  • 图元若已有脚本绑定，API 配置入口会被禁用；同理，存在 API 绑定时脚本编辑入口会锁定。
提示： 若需改回脚本逻辑，请先在 API 配置中点击“移除绑定”，再打开统一脚本编辑器。
API 绑定配置

API 绑定配置

脚本 API 速查

仿真脚本上下文会自动注入 api 对象，提供同步的 BeApi 封装与通用 HTTP 调用能力。

方法 同步性 说明
api.checkCondition(conditionId, params, options) 同步 调用条件评估端点，返回包含 result 的对象；失败时默认 result=false。
api.executeAction(actionType, params, options) 同步 调用动作执行端点，返回 { success, data, error, statusCode }。
api.getSimState(query, options) 同步 获取仿真快照，支持 detail、include 等查询参数。
api.get/post/put/delete(endpoint, ...) 异步 通用 HTTP 请求封装，返回 Promise，需要 await。
api.request(method, endpoint, options) 异步 自定义 HTTP 请求入口，可覆盖头信息、超时等。
api.listEndpoints / getConfig / getHistory / getStats / clearHistory 同步 查询当前 API 配置、调用历史与统计信息，便于调试。

示例：条件检查（同步）

const readiness = api.checkCondition('system_ready', {
    unitId: elementId,
    operator: '>=',
    threshold: 0.95
});

if (!readiness.result) {
    console.warn('系统尚未就绪，阻止流程继续');
    return false;
}
return true;

示例：动作执行

const reserveResult = api.executeAction('reserveProductionResources', {
    unitId: 'line-01',
    orderId: context.orderId,
    materialId: context.material,
    quantity: context.requiredQty
});

if (!reserveResult.success) {
    console.error('资源预留失败:', reserveResult.error);
    blackboard.set('reserveFailed', true);
    return;
}

blackboard.set('reservationId', reserveResult.data?.reservationId || null);

示例：获取仿真快照

const snapshot = api.getSimState({
    detail: 'basic',
    include: ['objects', 'processes'],
    limit: 200
});

if (snapshot.success) {
    console.log('当前对象数量:', snapshot.data?.objects?.length || 0);
}

示例：调用自定义 HTTP 服务

const response = await api.post('/api/v1/analytics/predict', {
    orderId: context.orderId,
    features: context.features
});

if (response.success) {
    blackboard.set('prediction', response.data);
} else {
    console.error('预测接口调用失败:', response.error);
}

运行时行为

  • 仿真启动时，UnifiedSimulationEngine 会初始化 ServerApiBindingManager、ConditionExecutor 与 ActionExecutor，并加载项目里的 apiBindings。
  • 条件绑定以同步方式执行，失败时默认返回 true 防止流程阻塞；operator 与 threshold 会随请求一并传递。
  • 动作绑定也以同步方式执行，执行结果通过 simulation:action-executed 事件广播给所有客户端。
  • 后端根据 config/api-config.json 中的 rateLimiting 设置控制调用频率，避免击穿外部服务。
  • 接口配置保存时，ApiBindingBridge 会同步更新服务器配置，并根据需要自动替换为本机 IP。

调试与排错

  • 健康检查：在“API 接口”对话框点击 测试连接，确认 BeApi 在线且返回 200。
  • 绑定测试：在绑定对话框使用 测试 API 按钮，查看实时返回信息。
  • 脚本日志：通过 api.getHistory(10) 或 api.getStats() 查看最近调用和耗时。
  • 服务器日志：运行服务端时关注终端输出，lib/simulation/communication/websocket-server.js 会记录同步与执行情况。
  • 配置校验：若地址异常，可手动检查 config/api-config.json 中的 baseUrl 是否正确。

安全性最佳实践

凭证管理

  • 避免在脚本中硬编码 Token，可放入 config/api-config.json 或环境变量。
  • 为不同环境使用独立密钥并定期轮换。

传输安全

  • 优先使用 HTTPS 接口，必要时通过网关终止 TLS。
  • 在代理或网关层限制允许访问的主机。

监控与速率

  • 合理配置 retryAttempts 与 rateLimiting，避免外部接口过载。
  • 利用 api.getStats() 定期查看耗时与失败率。

回归验证

  • 接口升级前，在测试环境使用绑定对话框的“测试 API”功能验证输出。
  • 注意保持脚本与绑定互斥，防止执行路径不明确。

下一步

完成接口配置与脚本验证后，可以继续：