npm package: @heqinghua/logic-engine-common
Description: 插件流程引擎公共库
Latest version: 1.0.0

# @heqinghua/logic-engine-common

插件化流程引擎的通用工具包，提供类型定义、常量、管理器和工具函数等共享功能。

## 简介

`@heqinghua/logic-engine-common` 是插件化流程引擎的基础通用包，为整个引擎提供共享的类型定义、常量、管理器类和工具函数。它是 core 和 ui 包的基础依赖，确保整个系统的类型一致性和功能共享。

## 核心功能

- **类型定义**：提供流程引擎所需的核心类型和接口
- **常量管理**：定义节点类型、状态、边类型等关键常量
- **组件管理器**：管理组件实例和全局方法的注册与调用
- **上下文管理器**：处理流程执行的变量和状态
- **操作符库**：提供规则引擎的各种比较和验证操作符
- **错误处理**：统一的错误类和错误处理机制
- **React Hooks**：提供便捷的 React 集成功能

## 目录结构

```
src/
├── constants/       # 常量定义
│   └── index.ts
├── errors/          # 错误处理
│   ├── FlowError.ts  # 流程错误类
│   ├── index.md      # 错误文档
│   └── index.ts
├── hooks/           # React Hooks
│   ├── index.md
│   ├── index.ts
│   ├── useComponentManager.ts  # 组件管理器 Hooks
│   └── useContextManager.ts    # 上下文管理器 Hooks
├── index.md
├── index.ts         # 模块导出
├── managers/        # 管理器类
│   ├── ComponentManager.ts     # 组件管理器
│   ├── ContextManager.ts       # 上下文管理器
│   ├── index.md
│   └── index.ts
├── operators/       # 操作符实现
│   ├── index.md
│   ├── index.ts
│   ├── operators.ts      # 操作符定义
│   └── operators_util.ts # 操作符工具函数
└── types/           # 类型定义
    └── index.ts
```

## 核心模块

### 类型定义 (types)

提供流程引擎所需的所有核心类型定义，包括节点、边、流程数据、执行上下文等。

```typescript
import type { Node, Edge, FlowData, ExecutionContext, PluginNodeType } from '@heqinghua/logic-engine-common';

const flowData: FlowData = {
  flow: { id: 'test-flow', name: '测试流程' },
  nodes: [/* 节点定义 */],
  edges: [/* 边定义 */],
  context: { variables: {} },
  global_config: {}
};
```

### 常量 (constants)

定义流程引擎中使用的关键常量，如节点类型、状态枚举等。

```typescript
import { BuiltInPluginNodeTypes, NodeStatus, EdgeType, ParallelStrategy, IterationMode } from '@heqinghua/logic-engine-common';

// 使用节点类型常量
const nodeType = BuiltInPluginNodeTypes.Action;

// 使用状态枚举
const successStatus = NodeStatus.SUCCESS;
```

### 组件管理器 (ComponentManager)

提供组件实例和全局方法的注册、查询和调用功能。

**主要功能**：
- 注册和管理组件实例
- 注册和调用全局方法
- 支持事件监听
- 提供实例和方法查询

```typescript
import { ComponentManager, ComponentManagerInstance } from '@heqinghua/logic-engine-common';

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

// 注册组件实例
manager.registerInstance('myComponent', componentRef);

// 注册全局方法
manager.registerGlobalMethod('myMethod', (arg1, arg2) => {
  return arg1 + arg2;
}, '计算两个数的和');

// 调用全局方法
const result = await manager.callGlobalMethod('myMethod', 1, 2);
```

### 上下文管理器 (ContextManager)

负责变量存储和状态管理，提供上下文的读写和监听功能。

**主要功能**：
- 初始化和管理上下文变量
- 提供变量的读写操作
- 支持上下文变更监听

```typescript
import { ContextManager } from '@heqinghua/logic-engine-common';

const contextManager = new ContextManager();

// 初始化上下文
contextManager.initialize({ variables: { count: 0 } });

// 更新变量
contextManager.updateVariables({ count: 1, name: 'test' });

// 获取变量
const variables = contextManager.getVariables();

// 监听上下文变更
contextManager.addListener((context) => {
  console.log('上下文已更新:', context);
});
```

### 操作符库 (operators)

提供规则引擎的各种比较和验证操作符，用于动态规则评估。

**主要功能**：
- 提供丰富的比较操作符（eq, ne, gt, lt 等）
- 支持字符串操作符（like, start_with, end_with 等）
- 支持数组操作符（in, not_in, is_oneof 等）
- 提供深度比较和正则匹配功能

```typescript
import { operators, deepEqual } from '@heqinghua/logic-engine-common';

// 使用操作符进行比较
const isEqual = operators.eq(5, [5]);
const isLike = operators.like('hello world', ['world']);

// 使用深度比较
const objectsEqual = deepEqual({ a: 1, b: { c: 2 } }, { a: 1, b: { c: 2 } });
```

### 错误处理 (errors)

提供统一的错误类和错误处理机制，便于错误追踪和管理。

**主要功能**：
- 定义统一的流程执行错误类
- 提供各种错误类型和代码
- 支持错误监听和处理
- 提供用户友好的错误信息

```typescript
import { FlowExecutionError, errorHandler } from '@heqinghua/logic-engine-common';

// 创建错误实例
const error = new FlowExecutionError(
  '节点执行失败',
  'NODE_EXECUTION_FAILED',
  'HIGH',
  { nodeId: 'node-1' }
);

// 使用错误处理器
const handledError = errorHandler.handleError(error);

// 监听错误
const removeListener = errorHandler.addErrorListener((error) => {
  console.error('捕获到错误:', error);
});
```

### React Hooks

提供便捷的 React 集成功能，简化在 React 组件中使用管理器的流程。

**主要 Hooks**：
- `useComponentManager`: 获取组件管理器实例
- `useRegisterInstance`: 注册组件实例
- `useRegisterGlobalMethod`: 注册全局方法
- `useInstanceMethod`: 获取实例方法
- `useCallGlobalMethod`: 调用全局方法

```jsx
import React, { useRef } from 'react';
import { useRegisterInstance, useCallGlobalMethod } from '@heqinghua/logic-engine-common';

function MyComponent() {
  const componentRef = useRef(null);
  const callMyMethod = useCallGlobalMethod('myMethod');
  
  // 注册组件实例
  useRegisterInstance('myComponent', componentRef);
  
  const handleClick = async () => {
    const result = await callMyMethod(1, 2);
    console.log('方法执行结果:', result);
  };
  
  return (
    <div ref={componentRef}>
      <button onClick={handleClick}>调用方法</button>
    </div>
  );
}
```

## API 参考

### 类型

- **Node**: 流程节点类型定义
- **Edge**: 流程边类型定义
- **FlowData**: 流程数据结构
- **ExecutionContext**: 执行上下文
- **PluginNodeType**: 插件节点类型

### 常量

- **BuiltInPluginNodeTypes**: 内置插件节点类型常量
- **NodeStatus**: 节点状态枚举
- **EdgeType**: 边类型枚举
- **ParallelStrategy**: 并行策略枚举
- **IterationMode**: 迭代模式枚举

### 类

- **ComponentManager**: 组件实例管理器
- **ContextManager**: 上下文管理器
- **FlowExecutionError**: 流程执行错误类
- **ErrorHandler**: 错误处理器

### 工具函数

- **deepEqual**: 深度比较两个值是否相等
- **extractRealValue**: 提取值的实际内容
- **normalizeToArray**: 将值标准化为数组形式
- **operators**: 规则引擎操作符集合

## 安装

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

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

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

## 依赖

- `lodash`: 提供实用的工具函数
- `@xyflow/react`: 流程图库（用于节点和边的基础类型定义）
- `json-rules-engine`: 规则引擎（用于类型定义）
- `react`: React 集成（可选）

## 许可证

MIT