# 测量函数

## 目录

1. [电阻测量函数](#电阻测量函数)
2. [电压测量函数](#电压测量函数)
3. [电流测量函数](#电流测量函数)
4. [频率测量函数](#频率测量函数)
5. [数字输入函数](#数字输入函数)
6. [绝缘测试函数](#绝缘测试函数)
7. [数据采集函数](#数据采集函数)

---

## 电阻测量函数

### 1. RESISTANCE_4WIRE - 4 线制电阻测量

**功能描述**：高精度 4 线制电阻测量，返回 7 个测量值。

**适用场景**：精密电阻测量，RTD 温度传感器检测。

**返回值数量**：7 个

- R1/2, R1/3, R1/4
- R2/3, R2/4, R3/4
- R/4wires

**YAML 配置示例**：

```yaml
testActions:
  measureResistance4Wire:
    id: measureResistance4Wire
    name: 4线制电阻测量
    mode: auto
    functionType: RESISTANCE_4WIRE
    channel: input1
    functionParameters: {}
    dataFields:
      - tableRef: '#/tables/resistanceTable'
        cells:
          - row: sensor1
            column: r12
          - row: sensor1
            column: r13
          - row: sensor1
            column: r14
          - row: sensor1
            column: r23
          - row: sensor1
            column: r24
          - row: sensor1
            column: r34
          - row: sensor1
            column: r4wires
```

**注意事项**：

- 必须指定 `channel` (input1 或 input2)
- `functionParameters` 为空对象 `{}`
- `dataFields` 必须包含 7 个单元格，顺序固定

---

### 2. RESISTANCE_3WIRE - 3 线制电阻测量

**功能描述**：3 线制电阻测量，返回 3 个测量值。

**适用场景**：3 线制 RTD 温度传感器检测。

**返回值数量**：3 个

- R2/3, R2/4, R3/4

**YAML 配置示例**：

```yaml
testActions:
  measureResistance3Wire:
    id: measureResistance3Wire
    name: 3线制电阻测量
    mode: auto
    functionType: RESISTANCE_3WIRE
    channel: input1
    functionParameters: {}
    dataFields:
      - tableRef: '#/tables/resistanceTable'
        cells:
          - row: sensor1
            column: r23
          - row: sensor1
            column: r24
          - row: sensor1
            column: r34
```

**注意事项**：

- 必须指定 `channel`
- `functionParameters` 为空对象 `{}`
- `dataFields` 必须包含 3 个单元格，顺序固定

---

### 3. RESISTANCE_2WIRE - 2 线制电阻测量

**功能描述**：2 线制电阻测量，返回 1 个测量值。

**适用场景**：简单电阻测量，2 线制传感器。

**返回值数量**：1 个

- R1/2

**YAML 配置示例**：

```yaml
testActions:
  measureResistance2Wire:
    id: measureResistance2Wire
    name: 2线制电阻测量
    mode: auto
    functionType: RESISTANCE_2WIRE
    channel: input1
    functionParameters: {}
    dataFields:
      - tableRef: '#/tables/resistanceTable'
        cells:
          - row: sensor1
            column: resistance
```

**注意事项**：

- 必须指定 `channel`
- `functionParameters` 为空对象 `{}`
- `dataFields` 包含 1 个单元格

---

## 电压测量函数

### 4. VOLTAGE_AC - 交流电压测量

**功能描述**：交流电压测量，返回 RMS 电压、峰值电压和频率。

**适用场景**：交流电源检测，信号分析。

**返回值数量**：3 个

- RMS 电压 (有效值)
- 峰值电压
- 频率

**YAML 配置示例**：

```yaml
testActions:
  measureACVoltage:
    id: measureACVoltage
    name: 交流电压测量
    mode: auto
    functionType: VOLTAGE_AC
    channel: input1
    functionParameters: {}
    dataFields:
      - tableRef: '#/tables/voltageTable'
        cells:
          - row: measurement1
            column: rmsVoltage
          - row: measurement1
            column: peakVoltage
          - row: measurement1
            column: frequency
```

**注意事项**：

- 必须指定 `channel`
- `functionParameters` 为空对象 `{}`
- `dataFields` 必须包含 3 个单元格，顺序固定

---

### 5. VOLTAGE_V - 直流电压测量 (伏特)

**功能描述**：直流电压测量，单位为伏特(V)。

**适用场景**：直流电源检测，信号电压测量。

**返回值数量**：1 个

- 电压值 (V)

**YAML 配置示例**：

```yaml
testActions:
  measureDCVoltage:
    id: measureDCVoltage
    name: 直流电压测量
    mode: auto
    functionType: VOLTAGE_V
    channel: input1
    functionParameters: {}
    dataFields:
      - tableRef: '#/tables/voltageTable'
        cells:
          - row: measurement1
            column: voltage
```

**注意事项**：

- 必须指定 `channel`
- `functionParameters` 为空对象 `{}`
- `dataFields` 包含 1 个单元格

---

### 6. VOLTAGE_MV - 直流电压测量 (毫伏)

**功能描述**：直流电压测量，单位为毫伏(mV)。

**适用场景**：微小信号测量，传感器输出检测。

**返回值数量**：1 个

- 电压值 (mV)

**YAML 配置示例**：

```yaml
testActions:
  measureMillivolt:
    id: measureMillivolt
    name: 毫伏电压测量
    mode: auto
    functionType: VOLTAGE_MV
    channel: input1
    functionParameters: {}
    dataFields:
      - tableRef: '#/tables/voltageTable'
        cells:
          - row: measurement1
            column: millivolt
```

**注意事项**：

- 必须指定 `channel`
- `functionParameters` 为空对象 `{}`
- `dataFields` 包含 1 个单元格

---

## 电流测量函数

### 7. CURRENT_MA - 直流电流测量 (毫安)

**功能描述**：直流电流测量，单位为毫安(mA)。

**适用场景**：回路电流检测，4-20mA 信号测量。

**返回值数量**：1 个

- 电流值 (mA)

**YAML 配置示例**：

```yaml
testActions:
  measureCurrent:
    id: measureCurrent
    name: 电流测量
    mode: auto
    functionType: CURRENT_MA
    channel: input1
    functionParameters: {}
    dataFields:
      - tableRef: '#/tables/currentTable'
        cells:
          - row: measurement1
            column: current
```

**注意事项**：

- 必须指定 `channel`
- `functionParameters` 为空对象 `{}`
- `dataFields` 包含 1 个单元格

---

## 频率测量函数

### 8. FREQUENCY - 频率测量

**功能描述**：信号频率测量，单位为 Hz。

**适用场景**：交流信号频率检测，脉冲频率测量。

**返回值数量**：1 个

- 频率值 (Hz)

**YAML 配置示例**：
dat
testActions:
measureFrequency:
id: measureFrequency
name: 频率测量
mode: auto
functionType: FREQUENCY
channel: input1
functionParameters: {}
dataFields: - tableRef: '#/tables/frequencyTable'
cells: - row: measurement1
column: frequency

````

**注意事项**：
- 必须指定 `channel`
- `functionParameters` 为空对象 `{}`
- `dataFields` 包含1个单元格

---

## 数字输入函数

### 9. DIGITAL_INPUT - 数字输入读取

**功能描述**：读取数字输入状态，返回布尔值。

**适用场景**：开关状态检测，数字信号读取。

**返回值数量**：1个
- 状态值 (true/false)

**YAML 配置示例**：

```yaml
testActions:
  readDigitalInput:
    id: readDigitalInput
    name: 数字输入读取
    mode: auto
    functionType: DIGITAL_INPUT
    channel: input1
    functionParameters: {}
    dataFields:
      - tableRef: '#/tables/digitalTable'
        cells:
          - row: input1
            column: state
````

**注意事项**：

- 必须指定 `channel`
- `functionParameters` 为空对象 `{}`
- `dataFields` 包含 1 个单元格
- 表格字段类型应设置为 `boolean`

---

## 绝缘测试函数

### 10. INSULATION - 绝缘电阻测试

**功能描述**：绝缘电阻测试，返回绝缘电阻值(MΩ)。

**适用场景**：电气设备绝缘检测，传感器绝缘测试。

**返回值数量**：1 个

- 绝缘电阻 (MΩ)

**YAML 配置示例**：

```yaml
testActions:
  insulationTest:
    id: insulationTest
    name: 绝缘测试
    mode: auto
    functionType: INSULATION
    channel: input1
    functionParameters:
      testVoltage: 50
      testTime: 20
      dischargeTime: 5
    dataFields:
      - tableRef: '#/tables/insulationTable'
        cells:
          - row: sensor1
            column: insulation
```

**functionParameters 参数说明**：

- `testVoltage`: 测试电压 (V)
- `testTime`: 测试时间 (秒)
- `dischargeTime`: 放电时间 (秒)

**注意事项**：

- 必须指定 `channel`
- `functionParameters` 可以指定测试参数，也可以使用空对象 `{}`
- `dataFields` 包含 1 个单元格

---

## 数据采集函数

### 11. DATA_ACQUISITION - 通用数据采集

**功能描述**：从上位机或 DCS 系统采集多个参数的数据。

**适用场景**：批量读取传感器数据、报警状态、系统参数等。

**返回值数量**：可变，与参数列表数量相同

**YAML 配置示例**：

```yaml
testActions:
  acquireData:
    id: acquireData
    name: 数据采集
    mode: auto
    functionType: DATA_ACQUISITION
    functionParameters:
      - RCP030MT
      - RCP033MT
      - RCP031MT
      - RCP034MT
    dataFields:
      - tableRef: '#/tables/dataTable'
        cells:
          - row: RCP030MT
            column: value
          - row: RCP033MT
            column: value
          - row: RCP031MT
            column: value
          - row: RCP034MT
            column: value
```

**functionParameters 参数说明**：

- 参数为数组形式，每个元素是要采集的数据标识符
- 返回值顺序与参数顺序一致
- 支持任意数量的参数

**数据类型识别**：

- 包含 "MT" 的参数：识别为温度传感器，返回温度值
- 包含 "AA" 的参数：识别为报警状态，返回 "有报警" 或 "无报警"
- 其他参数：返回通用数值

**注意事项**：

- **不需要**指定 `channel`
- `functionParameters` 为数组，不能为空
- `dataFields` 中的单元格数量必须与参数数量一致

---

### 12. DATA_ACQUISITION_WITH_VALIDATION - 带验证的数据采集

**功能描述**：从上位机采集数据，并返回每个数据的验证结果。

**适用场景**：需要服务器端验证的数据采集。

**返回值数量**：参数数量的 2 倍 (每个参数返回：值 + 验证结果)

**YAML 配置示例**：

```yaml
testActions:
  acquireDataWithValidation:
    id: acquireDataWithValidation
    name: 带验证的数据采集
    mode: auto
    functionType: DATA_ACQUISITION_WITH_VALIDATION
    functionParameters:
      - RCP030MT
      - RCP033MT
    dataFields:
      - tableRef: '#/tables/dataTable'
        cells:
          - row: RCP030MT
            column: value
          - row: RCP030MT
            column: valid
          - row: RCP033MT
            column: value
          - row: RCP033MT
            column: valid
```

**functionParameters 参数说明**：

- 参数为数组形式，每个元素是要采集的数据标识符
- 每个参数返回 2 个值：数据值和验证结果

**返回值格式**：

- 第 1 个值：第 1 个参数的数据值
- 第 2 个值：第 1 个参数的验证结果 (true/false)
- 第 3 个值：第 2 个参数的数据值
- 第 4 个值：第 2 个参数的验证结果 (true/false)
- 以此类推...

**注意事项**：

- **不需要**指定 `channel`
- `functionParameters` 为数组，不能为空
- `dataFields` 中的单元格数量必须是参数数量的 2 倍
- 验证结果字段类型应设置为 `boolean`

---

## 字段映射

### 基本规则

**dataFields 是一个 fieldSelector 数组，每个 fieldSelector 可以是：**

1. **包含 cells 的对象** - 用于 Grid 表格，通过 `row` 和 `column` 定位
2. **包含 fields 的对象** - 用于 Form 表格，直接指定字段 ID
3. **ignore 对象** - `ignore: true` 用于跳过不需要的返回值

**注意**：

- 每个 fieldSelector 中的 cells 或 fields 可以包含多个项
- **所有 fieldSelector 消耗的返回值总数必须与函数返回值数量相等**
  - 包含 cells 的 fieldSelector：消耗 cells 数组长度个返回值
  - 包含 fields 的 fieldSelector：消耗 fields 数组长度个返回值
  - ignore 的 fieldSelector：消耗 1 个返回值
- 可以在同一个 dataFields 中混合使用不同类型的 fieldSelector

### Grid 类型表格 - 使用 cells

```yaml
dataFields:
  - tableRef: '#/tables/gridTable'
    cells:
      - row: sensor1
        column: value1
      - row: sensor1
        column: value2
```

### Form 类型表格 - 使用 fields

```yaml
dataFields:
  - tableRef: '#/tables/formTable'
    fields:
      - field1
      - field2
      - field3
```

### 忽略返回值

如果函数返回 5 个值，但只需要其中 4 个，忽略第 3 个：

```yaml
dataFields:
  - tableRef: '#/tables/gridTable'
    cells:
      - row: sensor1
        column: value1
      - row: sensor1
        column: value2
  - ignore: true # 忽略第3个返回值
  - tableRef: '#/tables/gridTable'
    cells:
      - row: sensor1
        column: value4
      - row: sensor1
        column: value5
```

### 混合使用

`ignore` 可以与 `cells` 和 `fields` 自由混合，不局限于单一类型：

```yaml
dataFields:
  - tableRef: '#/tables/gridTable'
    cells:
      - row: sensor1
        column: value1
  - tableRef: '#/tables/formTable'
    fields:
      - field1
      - field2
  - ignore: true # 忽略第4个返回值
  - tableRef: '#/tables/gridTable'
    cells:
      - row: sensor2
        column: value5
  - ignore: true # 忽略第6个返回值
  - tableRef: '#/tables/formTable'
    fields:
      - field3
```

**说明**：上述示例处理 7 个返回值：
- 第 1 个 → gridTable 的 cell
- 第 2-3 个 → formTable 的 field1 和 field2
- 第 4 个 → 忽略
- 第 5 个 → gridTable 的 cell
- 第 6 个 → 忽略
- 第 7 个 → formTable 的 field3