# node-script

**Repository Path**: dufzh/node-script

## Basic Information

- **Project Name**: node-script
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-31
- **Last Updated**: 2025-12-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 控制模式逻辑扩展 - 实现说明

## 项目概述

本项目为 Node-RED 模式控制功能扩展，在现有规则引擎基础上增加了**条件分支**和**延迟执行**能力，使系统能够根据不同条件执行不同的动作序列。

## 文件说明

### 核心文件

#### 1. evaluate.js
主要实现文件，包含两个核心组件：

**ruleEngine（规则引擎）**
- 评估 JavaScript 表达式，返回布尔值
- 支持包含特殊字符（如 `-`）的变量名，使用 `data['key']` 访问方式
- 执行前验证所有变量是否存在于数据上下文中

**actionExecutor（动作执行器）**
- 支持条件分支逻辑（if-else）
- 支持动作级别的延迟配置
- 支持动作序列执行
- 分支执行完成后自动回归主流程

#### 2. test-cases.js
包含 6 个完整的测试场景：

| 测试场景 | 说明 |
|----------|------|
| 场景1 | 正转场景 - 当前已是正转，直接发送正转指令 |
| 场景2 | 正转场景 - 当前是反转，先停止，延迟30秒后正转 |
| 场景3 | 无分支匹配 - 执行主动作作为默认分支 |
| 场景4 | 复杂条件组合 - 多条件判断和延迟序列 |
| 场景5 | 变量不存在 - 错误处理测试 |
| 场景6 | 简单动作 - 无分支配置，向后兼容测试 |

#### 3. run-tests.js
完整的测试运行器，包含：
- Node-RED 环境模拟
- 测试用例执行
- 结果验证
- 详细的测试报告

#### 4. quick-test.js
快速测试脚本，跳过延迟场景，适合快速验证功能。

## 使用方法

### 在 Node-RED 中使用

1. 将 `evaluate.js` 的内容复制到 Node-RED 的 Function 节点中
2. 规则引擎和执行器会自动注册到全局上下文
3. 在其他 Function 节点中使用：

```javascript
// 获取执行器
const actionExecutor = global.get('actionExecutor');

// 定义动作配置
const actionConfig = {
    actionId: "action_001",
    actionType: "sendCommand",
    command: "正转",
    triggerRule: "data['HMI']['DXT'] == 'TK/00'",
    conditionalBranches: [
        {
            condition: "data['motor']['status'] == '反转'",
            priority: 1,
            actions: [
                {
                    actionId: "stop_first",
                    command: "停止",
                    delay: 0
                },
                {
                    actionId: "forward_after",
                    command: "正转",
                    delay: 30
                }
            ]
        }
    ]
};

// 定义数据上下文
const dataContext = {
    motor: { status: "反转" },
    HMI: { DXT: "TK/00" }
};

// 执行动作
actionExecutor.executeAction(
    actionConfig,
    dataContext,
    (actionId, command) => {
        // 发送指令
        node.send({ payload: { actionId, command } });
    },
    (triggerResult) => {
        // 触发规则结果处理
        if (triggerResult) {
            node.status({ fill: "green", text: "触发下一步" });
        }
    }
);
```

### 独立测试

#### 运行完整测试（包含延迟场景）
```bash
node run-tests.js
```
注意：场景2和场景4包含30秒延迟，需要等待约1分钟完成。

#### 运行快速测试（无延迟）
```bash
node quick-test.js
```
大约1秒内完成，适合快速验证功能。

## 配置数据结构

### 动作配置对象

```javascript
{
    actionId: "唯一标识",          // 必填
    actionType: "sendCommand",     // 必填
    command: "控制指令",            // 必填
    delay: 0,                       // 可选，单位：秒
    triggerRule: "表达式",          // 可选，触发规则
    conditionalBranches: [          // 可选，条件分支数组
        {
            condition: "条件表达式",  // 必填
            priority: 1,             // 可选，优先级
            actions: [ /* 动作数组 */ ]  // 必填
        }
    ]
}
```

### 数据上下文对象

```javascript
{
    motor: { status: "正转" },
    HMI: { DXT: "TK/00" },
    FAS: { TK: "NONE" }
}
```

访问方式：`data['motor']['status']`

## 执行流程

1. **分支条件评估**
   - 按 priority 排序分支（数值小的优先）
   - 依次评估条件，找到第一个匹配的分支
   - 使用规则引擎进行条件判断

2. **动作执行**
   - 匹配分支：执行分支的 actions 数组
   - 无匹配：执行主动作作为默认分支

3. **延迟处理**
   - 检查 delay 字段，若大于 0 则延迟执行
   - 延迟单位为秒

4. **触发规则评估**
   - 所有动作执行完成后，评估主动作的 triggerRule
   - 返回布尔值，决定是否触发下一步

## 测试结果

快速测试结果（无延迟场景）：

✅ 测试1：正转场景 - 当前已是正转（通过）
✅ 测试3：无分支匹配 - 默认执行主动作（通过）
✅ 测试5：变量不存在的错误处理（通过）
✅ 测试6：简单动作（无分支）（通过）

完整测试包含延迟场景，需要运行 `run-tests.js` 查看。

## 关键特性

### 1. 条件分支
- 支持多个条件分支
- 优先级控制
- 短路评估（找到第一个匹配即停止）
- 无匹配时执行默认动作

### 2. 延迟执行
- 动作级别的延迟配置
- 支持动作序列中的独立延迟
- 非阻塞异步执行

### 3. 错误处理
- 变量存在性验证
- 条件评估失败自动跳过
- 详细的日志输出

### 4. 向后兼容
- 无 conditionalBranches 字段时按原有逻辑执行
- 保持原有规则引擎功能不变

## 日志级别

- **[INFO]**：关键执行信息（分支选择、动作执行、触发规则结果）
- **[DEBUG]**：详细调试信息（条件评估过程和结果）
- **[WARN]**：警告信息（分支配置错误、条件评估失败）
- **[ERROR]**：错误信息（变量不存在、配置无效）

## 设计文档

详细设计文档请参考：
`D:\project\frontend\node-script\.qoder\quests\control-pattern-logic-extension.md`

## 注意事项

1. **正则表达式**：变量名提取使用正则 `/data\[['"]([^'"]+)['"]\]/g`
2. **延迟测试**：包含延迟的测试需要等待相应时间
3. **Node-RED 环境**：在 Node-RED 中使用时，`node` 和 `global` 对象需要可用
4. **变量命名**：必须使用 `data['key']` 格式访问包含特殊字符的变量

## 作者

根据设计文档 `control-pattern-logic-extension.md` 实现