npm package: @heqinghua/logic-engine-core
Description: 规则引擎核心模块（执行、插件、事件调用）
Latest version: 1.0.0

# @heqinghua/logic-engine-core

插件化流程引擎核心包，提供流程定义、执行和管理的核心能力。

## 简介

`@heqinghua/logic-engine-core` 是插件化流程引擎的核心模块，负责协调各节点插件的执行、维护执行上下文和流程状态。它实现了基于插件的可扩展架构，将具体节点的执行逻辑委托给对应的插件处理。

## 核心功能

- **插件化流程执行引擎**：协调各节点插件的执行和流程控制
- **插件管理系统**：负责节点插件的注册、查找和管理
- **内置节点类型**：提供常用的流程节点类型实现
- **流程状态跟踪**：记录节点执行历史和状态变更
- **上下文管理**：维护流程执行的上下文变量和数据
- **React 集成**：提供 React Hook 用于在组件中使用流程引擎

## 目录结构

```
src/
├── constants.ts         # 核心常量定义
├── hooks/               # React Hooks
│   └── useFlowEngine.ts # 流程引擎 Hook
├── index.ts             # 模块导出
├── plugins/             # 节点插件
│   ├── ActionNodePlugin/      # 动作节点插件
│   ├── BaseNodePlugin.ts      # 节点插件基类
│   ├── BranchNodePlugin/      # 分支节点插件
│   ├── EndNodePlugin/         # 结束节点插件
│   ├── IterationNodePlugin/   # 迭代节点插件
│   ├── MergeNodePlugin/       # 合并节点插件
│   ├── NodePlugin.d.ts        # 节点插件接口定义
│   ├── ParallelNodePlugin/    # 并行节点插件
│   ├── TriggerNodePlugin/     # 触发节点插件
│   └── index.ts               # 插件导出
├── types.ts             # 核心类型定义
└── utils/               # 工具类
    ├── FlowMonitor.ts          # 流程监控器
    ├── FlowValidator.ts        # 流程验证器
    ├── PluginExecutionEngine.ts # 插件执行引擎
    └── PluginManager.ts        # 插件管理器
```

## 核心组件

### PluginExecutionEngine

流程执行的核心控制器，负责协调各节点插件的执行、维护执行上下文和流程状态。

主要功能：
- 初始化流程定义和上下文
- 执行流程和单个节点
- 管理执行历史和状态
- 评估规则和方法
- 处理事件监听

```typescript
import { PluginExecutionEngine } from '@heqinghua/logic-engine-core';

const engine = new PluginExecutionEngine();
engine.initialize(flowData, context);
const result = await engine.executeFlow();
```

### PluginManager

插件管理器，负责节点插件的注册、查找和管理，支持单例模式。

主要功能：
- 注册和获取节点插件
- 自动注册内置节点插件
- 执行节点和获取下一个节点ID

```typescript
import { PluginManager, PluginManagerInstance } from '@heqinghua/logic-engine-core';

// 使用单例实例
const manager = PluginManagerInstance();

// 或直接使用类
const manager = new PluginManager();
```

### BaseNodePlugin

节点插件基类，实现了 NodePlugin 接口的通用逻辑，为各种具体节点类型提供统一的基础实现。

主要功能：
- 提供节点执行的默认实现
- 处理条件评估和事件执行
- 管理节点状态和执行历史
- 确定下一个要执行的节点

### useFlowEngine

React Hook，封装流程引擎的初始化、执行和状态管理逻辑。

主要功能：
- 初始化流程引擎和上下文
- 提供流程执行方法
- 管理执行状态和历史
- 更新变量和上下文

```typescript
import { useFlowEngine } from '@heqinghua/logic-engine-core';

const { engine, executeFlow, executionResult, executionHistory, isExecuting } = useFlowEngine({
  flowData,
  initialVariables
});
```

## 内置节点类型

引擎内置了以下节点类型：

1. **TriggerNode**：流程触发节点，流程的起始点
2. **ActionNode**：动作节点，执行具体的业务逻辑
3. **BranchNode**：分支节点，根据条件选择执行路径
4. **ParallelNode**：并行节点，并行执行多条路径
5. **IterationNode**：迭代节点，循环执行指定操作
6. **MergeNode**：合并节点，合并多条执行路径
7. **EndNode**：结束节点，标志流程结束

## 使用示例

### 初始化和执行流程

```typescript
import { PluginExecutionEngine, getBuiltInPluginInstances } from '@heqinghua/logic-engine-core';

// 创建引擎实例
const engine = new PluginExecutionEngine();

// 初始化流程定义和上下文
const flowData = {
  flow: { id: 'test-flow', name: '测试流程' },
  nodes: [/* 节点定义 */],
  edges: [/* 边定义 */]
};

const context = {
  variables: { /* 初始变量 */ }
};

engine.initialize(flowData, context);

// 执行流程
const result = await engine.executeFlow();
console.log('执行结果:', result);
```

### 在 React 组件中使用

```jsx
import React from 'react';
import { useFlowEngine } from '@heqinghua/logic-engine-core';

function FlowComponent({ flowData }) {
  const { executeFlow, executionResult, executionHistory, isExecuting } = useFlowEngine({
    flowData,
    initialVariables: { name: 'test' }
  });

  return (
    <div>
      <button onClick={executeFlow} disabled={isExecuting}>
        {isExecuting ? '执行中...' : '执行流程'}
      </button>
      {executionResult && (
        <div>结果: {executionResult.status ? '成功' : '失败'}</div>
      )}
    </div>
  );
}
```

### 自定义节点插件

```typescript
import { BaseNodePlugin } from '@heqinghua/logic-engine-core';

export class CustomNodePlugin extends BaseNodePlugin {
  public pluginNodeType = "CustomNode";
  public pluginNodeTypeName = '自定义节点';

  async executeNode(node, engine, historyItem) {
    // 自定义执行逻辑
    return true;
  }

  async getNextNodeId(edges, engine, historyItem) {
    // 自定义下一个节点选择逻辑
    return super.getNextNodeId(edges, engine, historyItem);
  }
}
```

## API 参考

### 核心类

- **PluginExecutionEngine**
  - `initialize(flow: FlowData, context: ExecutionContext)`: 初始化引擎
  - `executeFlow(nodeId = 'trigger')`: 执行整个流程
  - `executeNode(nodeId: string)`: 执行单个节点
  - `getExecutionHistory()`: 获取执行历史
  - `updateContext(context: ExecutionContext)`: 更新上下文

- **PluginManager**
  - `registerPlugin(plugin: NodePlugin)`: 注册节点插件
  - `getPlugin(pluginNodeType: PluginNodeType)`: 获取节点插件
  - `hasPlugin(pluginNodeType: PluginNodeType)`: 检查是否存在插件

### React Hooks

- **useFlowEngine(options: UseFlowEngineOptions)**
  - 返回: `{ engine, executeFlow, executionResult, executionHistory, isExecuting, updateVariables }`

### 类型定义

- **FlowData**: 流程定义数据结构
- **Node**: 节点定义
- **Edge**: 边定义
- **ExecutionContext**: 执行上下文
- **ExecutionHistory**: 执行历史记录

## 安装

```bash
# 使用 npm
npm install @heqinghua/logic-engine-core

# 使用 yarn
yarn add @heqinghua/logic-engine-core

# 使用 pnpm
pnpm add @heqinghua/logic-engine-core
```

## 依赖

- `@heqinghua/logic-engine-common`: 通用工具和类型
- `json-rules-engine`: 规则评估引擎
- `react`: React 集成（可选）

## 许可证

MIT