SOMS/YunDa.Application/YunDa.SOMS.Application/DataMonitoring/SecondaryCircuitInspection/Documentation/SecondaryCircuitInspectionCalculationGuide.md

二次回路巡检计算算法详细说明文档

概述

本文档详细说明了二次回路巡检系统中各种计算算法的实现原理、参数配置和前端实现指南。

目录

1. 表达式计算系统
2. JavaScript代码执行
3. 时间窗口计算器
4. 巡检算法类型
5. 前端实现指南
6. API接口说明

---

表达式计算系统

1. 表达式语法

支持标准的JavaScript表达式语法，变量格式为 {地址_类型}：

// 基本比较
{16835_0} > 100

// 复合条件
{16835_0} > 50 && {16835_1} < 200

// 数学运算
abs({16835_0} - {16835_1}) > 10

// 逻辑运算
{16128_0} == 1 || {16129_0} == 1

2. 变量代码格式

• 遥测数据: {地址_0} - 例如 {16835_0} 表示地址16835的遥测值
• 遥信数据: {地址_1} - 例如 {16128_1} 表示地址16128的遥信状态

3. 支持的运算符

运算符类型	运算符	说明	示例
算术运算	+, -, *, /	基本数学运算	{16835_0} + {16836_0}
比较运算	>, <, >=, <=, ==, !=	数值比较	{16835_0} > 100
逻辑运算	&&, ||, !	逻辑与、或、非	{16835_0} > 50 && {16836_0} < 200
数学函数	abs(), max(), min()	数学函数	abs({16835_0} - {16836_0})

---

JavaScript代码执行

1. 数据格式

JavaScript代码可以访问全局变量 data，格式如下：

// data 数组格式
[
  {"16168_0": {"value": 10.5, "time": 1758778427624}},
  {"16168_0": {"value": 11.22, "time": 1758778427674}},
  {"16128_1": {"value": 1, "time": 1758778427624}},
  // ... 更多数据点
]

2. 标准返回格式

JavaScript代码应返回包含以下属性的对象：

{
  "Flag": true,  // 布尔值，表示计算结果是否正常
  "ResultDescription": "计算结果描述"  // 字符串，描述计算结果
}

3. JavaScript代码示例

示例1：简单阈值检查

function checkThreshold() {
    let abnormalCount = 0;
    
    for (let item of data) {
        for (let key in item) {
            if (item[key].value > 100) {
                abnormalCount++;
            }
        }
    }
    
    return {
        Flag: abnormalCount === 0,
        ResultDescription: abnormalCount === 0 ? 
            "所有数据点正常" : 
            `发现${abnormalCount}个异常数据点`
    };
}

checkThreshold();

示例2：电压一致性检查

function checkVoltageConsistency() {
    let voltageValues = [];
    
    // 收集所有电压值
    for (let item of data) {
        for (let key in item) {
            if (key.endsWith('_0')) { // 遥测数据
                voltageValues.push(item[key].value);
            }
        }
    }
    
    if (voltageValues.length < 2) {
        return {
            Flag: false,
            ResultDescription: "电压数据点不足，无法进行一致性检查"
        };
    }
    
    // 计算电压偏差
    let maxVoltage = Math.max(...voltageValues);
    let minVoltage = Math.min(...voltageValues);
    let deviation = maxVoltage - minVoltage;
    
    return {
        Flag: deviation <= 5.0,
        ResultDescription: `电压偏差: ${deviation.toFixed(2)}V, ${deviation <= 5.0 ? '正常' : '异常'}`
    };
}

checkVoltageConsistency();

示例3：时间序列分析

function analyzeTimeSeries() {
    let timeSeriesData = {};
    
    // 按变量代码分组数据
    for (let item of data) {
        for (let key in item) {
            if (!timeSeriesData[key]) {
                timeSeriesData[key] = [];
            }
            timeSeriesData[key].push({
                value: item[key].value,
                time: item[key].time
            });
        }
    }
    
    let results = [];
    
    // 分析每个变量的趋势
    for (let variable in timeSeriesData) {
        let values = timeSeriesData[variable];
        if (values.length >= 2) {
            let trend = values[values.length - 1].value - values[0].value;
            results.push({
                variable: variable,
                trend: trend,
                isStable: Math.abs(trend) < 1.0
            });
        }
    }
    
    let unstableCount = results.filter(r => !r.isStable).length;
    
    return {
        Flag: unstableCount === 0,
        ResultDescription: unstableCount === 0 ? 
            "所有变量趋势稳定" : 
            `${unstableCount}个变量趋势不稳定`
    };
}

analyzeTimeSeries();

---

时间窗口计算器

1. 基本功能

时间窗口计算器提供以下功能：

• 实时数据获取: 获取指定时间窗口内的遥测/遥信数据
• 时间序列生成: 生成带时间戳的历史数据序列
• JavaScript表达式计算: 支持自定义JavaScript表达式计算
• 数据格式转换: 自动转换为前端需要的JSON格式

2. API方法

CalculateTimeWindowDataAsync

// 获取JSON格式的时间窗口数据
Task<string> CalculateTimeWindowDataAsync(
    Guid inspectionItemId,
    int timeWindowSeconds = 60,
    CancellationToken cancellationToken = default)

CalculateTimeSeriesDataAsync

// 获取时间序列数据
Task<List<Dictionary<string, object>>> CalculateTimeSeriesDataAsync(
    Guid inspectionItemId,
    int timeWindowSeconds = 60,
    int sampleIntervalSeconds = 5,
    CancellationToken cancellationToken = default)

3. 返回数据格式

{
  "16835_0": 52.5,
  "16835_1": 75.3,
  "16128_1": 1
}

---

巡检算法类型

1. 电压采集一致性判断 (VoltageCollectionConsistency)

算法原理: 检查多个电压采集点的数值一致性

参数配置:

• VoltageDeviationThreshold: 电压偏差阈值（kV）
• TimeWindowSeconds: 时间窗口（秒）

计算逻辑:

// 示例表达式
abs({16835_0} - {16836_0}) <= 1.0

2. 电流采集一致性判断 (CurrentCollectionConsistency)

算法原理: 检查电流采集的一致性和合理性

参数配置:

• CurrentDeviationThresholdPercent: 电流偏差阈值百分比（%）
• TimeWindowSeconds: 时间窗口（秒）

计算逻辑:

// 示例表达式
abs(({16837_0} - {16838_0}) / {16837_0}) * 100 <= 5.0

3. 位置信号采集校验 (PositionSignalVerification)

算法原理: 校验开关位置信号的正确性

参数配置:

• TimeWindowSeconds: 时间窗口（秒）

计算逻辑:

// 示例表达式：检查分合闸位置信号互斥
!({16128_1} == 1 && {16129_1} == 1)

4. 交流回路极性校验 (ACCircuitPolarityVerification)

算法原理: 验证交流回路的极性正确性

参数配置:

• PhaseAngleDifferenceThreshold: 相角差阈值（度）
• TimeWindowSeconds: 时间窗口（秒）

计算逻辑:

// 示例表达式：检查相角差
abs({16840_0} - {16841_0}) <= 10.0

5. 通信质量分析 (CommunicationQualityAnalysis)

算法原理: 分析通信链路的质量和可靠性

参数配置:

• TimeWindowSeconds: 时间窗口（秒）

计算逻辑: 基于数据可用性和通信延时进行综合评估

---

前端实现指南

1. 表达式编辑器

推荐使用Monaco Editor或CodeMirror实现表达式编辑器：

// Monaco Editor配置示例
const editorConfig = {
    language: 'javascript',
    theme: 'vs-dark',
    automaticLayout: true,
    minimap: { enabled: false },
    scrollBeyondLastLine: false,
    wordWrap: 'on'
};

2. 变量代码提示

实现变量代码的智能提示功能：

// 变量代码提示数据
const variableHints = [
    { label: '{16835_0}', detail: '电压A相 (遥测)', insertText: '{16835_0}' },
    { label: '{16836_0}', detail: '电压B相 (遥测)', insertText: '{16836_0}' },
    { label: '{16128_1}', detail: '分闸位置 (遥信)', insertText: '{16128_1}' },
    // ... 更多提示
];

3. 表达式验证

前端应实现表达式语法验证：

async function validateExpression(expression) {
    try {
        const response = await fetch('/api/secondary-circuit/validate-expression', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ expression })
        });
        
        const result = await response.json();
        return result;
    } catch (error) {
        return { isValid: false, errors: [error.message] };
    }
}

4. 实时数据预览

提供实时数据预览功能：

async function previewCalculation(inspectionItemId, expression) {
    try {
        const response = await fetch('/api/secondary-circuit/test-expression', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ 
                inspectionItemId,
                expression,
                timeWindowSeconds: 60
            })
        });
        
        const result = await response.json();
        return result;
    } catch (error) {
        console.error('预览计算失败:', error);
        return null;
    }
}

---

API接口说明

1. 表达式验证接口

URL: POST /api/secondary-circuit/validate-expression

请求参数:

{
  "expression": "{16835_0} > 100 && {16836_0} < 200"
}

响应格式:

{
  "flag": true,
  "message": "表达式语法正确",
  "resultData": {
    "isValid": true,
    "errors": [],
    "warnings": [],
    "variableCodes": ["16835_0", "16836_0"]
  }
}

2. 表达式测试接口

URL: POST /api/secondary-circuit/test-expression

请求参数:

{
  "expression": "{16835_0} > 100",
  "timeWindowSeconds": 60
}

响应格式:

{
  "flag": true,
  "message": "表达式计算成功",
  "resultData": {
    "isSuccess": true,
    "result": true,
    "executionTimeMs": 15,
    "variableValues": {
      "16835_0": 105.5
    },
    "evaluationDetails": [
      "提取到 1 个变量: 16835_0",
      "替换后的表达式: 105.5 > 100",
      "计算结果: true"
    ]
  }
}

3. 时间窗口数据获取接口

URL: GET /api/secondary-circuit/time-window-data/{inspectionItemId}

查询参数:

• timeWindowSeconds: 时间窗口（秒），默认60
• format: 返回格式，可选 json 或 timeseries

响应格式:

{
  "flag": true,
  "message": "获取成功",
  "resultData": "{\"16835_0\": 52.5, \"16835_1\": 75.3}"
}

---

最佳实践

1. 表达式设计原则

• 简洁明了: 表达式应该易于理解和维护
• 性能考虑: 避免过于复杂的计算逻辑
• 错误处理: 考虑数据缺失或异常情况
• 文档说明: 为复杂表达式添加注释说明

2. JavaScript代码规范

• 函数封装: 将复杂逻辑封装为函数
• 错误处理: 添加适当的错误检查
• 性能优化: 避免不必要的循环和计算
• 返回格式: 严格按照标准格式返回结果

3. 前端集成建议

• 用户体验: 提供友好的编辑和调试界面
• 实时反馈: 实现表达式语法检查和结果预览
• 帮助文档: 集成在线帮助和示例代码
• 版本管理: 支持表达式的版本控制和回滚

---

常见问题解答

Q1: 如何处理数据缺失的情况？

A: 系统会自动将缺失的数据设置为默认值（遥测为0，遥信为false），建议在表达式中添加数据有效性检查。

Q2: JavaScript代码的执行时间限制是多少？

A: 默认限制为30秒，超时会自动终止执行并返回错误信息。

Q3: 支持哪些JavaScript内置函数？

A: 支持标准的Math对象函数，如Math.abs()、Math.max()、Math.min()等，以及基本的数组和字符串操作。

Q4: 如何调试复杂的JavaScript代码？

A: 可以使用console.log()输出调试信息，这些信息会包含在返回结果的详情中。

---

本文档版本: 1.0
最后更新: 2024年