核心概念

理解平台的核心概念有助于更高效地使用SDK和API。

数据模型

Inteagle 结构健康监测平台采用三层数据模型：

graph TD
    subgraph L1["第一层 - 租户层"]
        A[客户 Customer]
    end

    subgraph L2["第二层 - 项目层"]
        B[项目 Project]
    end

    subgraph L3["第三层 - 数据采集层"]
        C1[监测点<br/>Monitoring Point<br/>业务视角]
        C2[设备<br/>Device<br/>物理设备]
    end

    subgraph DATA["数据层"]
        D1[监测点数据<br/>dx dy tilt]
        D2[设备原始数据<br/>标靶坐标]
    end

    A -->|1:N 包含| B
    B -->|1:N 包含| C1
    B -->|1:N 包含| C2
    C1 -->|1:N 产生| D1
    C2 -->|1:N 上报| D2
    C1 <-.->|N:M 多对多映射| C2

    style A fill:#e1f5ff,stroke:#01579b,stroke-width:3px
    style B fill:#fff4e1,stroke:#e65100,stroke-width:3px
    style C1 fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style C2 fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style D1 fill:#e8f5e9,stroke:#1b5e20,stroke-width:1px
    style D2 fill:#e8f5e9,stroke:#1b5e20,stroke-width:1px

核心特点：

1. 第一层（租户层）：客户级数据隔离
2. 第二层（项目层）：一个项目对应一个监测工程
3. 第三层（数据采集层）：
   • 监测点：业务视角，反映监测需求
   • 设备：物理设备，采集原始数据
   • 关键：监测点 ↔ 设备 是多对多映射关系

层级关系

核心实体

项目 (Project)

监测工程的顶层容器，对应一个实际的工程项目（如桥梁监测、边坡监测）。

属性：

• 项目名称、编号
• 监测类型（桥梁/隧道/边坡/环境等）
• 地理位置
• 起止日期

包含：

• 多个监测点（类型取决于监测场景）
• 多个设备

典型项目场景：

场景 1：桥梁监测项目

graph TD
    P1[桥梁监测项目]
    P1 --> PT1["位移监测点 x10"]
    P1 --> PT2["倾斜监测点 x4"]
    P1 --> PT3["应变监测点 x8"]
    P1 --> PT4["环境监测点 x2"]
    P1 --> D1["设备: V2K x6, X1 x4, O1 x8"]

    style P1 fill:#fff4e1
    style PT1 fill:#f3e5f5
    style PT2 fill:#f3e5f5
    style PT3 fill:#f3e5f5
    style PT4 fill:#f3e5f5
    style D1 fill:#e1f5ff

场景 2：隧道监测项目

graph TD
    P2[隧道监测项目]
    P2 --> PT1["收敛监测点 x15"]
    P2 --> PT2["沉降监测点 x20"]
    P2 --> D2["设备: V2K x10, X1 x5"]

    style P2 fill:#e3f2fd
    style PT1 fill:#f3e5f5
    style PT2 fill:#f3e5f5
    style D2 fill:#e1f5ff

场景 3：环境监测项目

graph TD
    P3[环境监测项目]
    P3 --> PT1["环境监测点 x5"]
    P3 --> D3["环境传感器 x5"]

    style P3 fill:#e8f5e9
    style PT1 fill:#f3e5f5
    style D3 fill:#e1f5ff

监测点 (Monitoring Point)

业务视角的测量点，聚合了来自设备的监测指标。

特点：

• 业务导向：反映实际的监测需求（如"3号桥墩位移"）
• 指标聚合：可从多个设备/通道汇总数据
• 多对多关系：
  • 一个监测点可以从多个设备的数据组合而成
  • 一个设备可以为多个监测点提供数据（如视觉位移计设备可为多个监测点提供数据）
• 场景化配置：不同监测场景下，监测点关注的指标类型不同

监测点类型与场景：

详细监测点类型参见 数据字典 - 监测点类型

示例 1：多设备融合 → 一个监测点（3D 空间位移）

典型应用：通过两台视觉位移计的三角测量，融合计算出 3D 空间位移。

graph TD
    PT[监测点<br/>桥墩A-3D位移监测点<br/>输出: dx, dy, dz]
    D1[设备1 V2W<br/>标靶1]
    D2[设备2 V2W<br/>标靶1]
    L1[local坐标<br/>dx1, dy1]
    L2[local坐标<br/>dx2, dy2]
    FUSION[三维融合算法]

    D1 -->|测量| L1
    D2 -->|测量| L2
    L1 --> FUSION
    L2 --> FUSION
    FUSION -->|计算| PT

    style PT fill:#fff4e1,stroke:#e65100,stroke-width:3px
    style D1 fill:#e1f5ff
    style D2 fill:#e1f5ff
    style FUSION fill:#ffe0b2,stroke:#f57c00,stroke-width:2px

两台设备各自测量标靶在自己 local 坐标系下的 dx, dy，通过三维融合算法（空间几何计算）得到 global 坐标系下的完整 3D 位移（dx, dy, dz）。

示例 2：一个设备 → 多个监测点

graph TD
    D[设备 dev_001<br/>V2K 2靶位移计]
    T1[标靶1]
    T2[标靶2]
    PT1[监测点A<br/>桥墩A位移]
    PT2[监测点B<br/>桥墩B位移]

    D --> T1
    D --> T2
    T1 --> PT1
    T2 --> PT2

    style D fill:#e1f5ff
    style PT1 fill:#fff4e1
    style PT2 fill:#fff4e1

设备 (Device)

物理传感器/采集设备，上报原始测量数据。

VDM 视觉位移计系列：

所有 视觉位移计设备均基于视觉测量原理，可测量多个标靶。不同型号在视觉传感器数量（单目/双目）、云台功能（固定式/旋转式）、连接方式（有线/无线）上有所差异。

型号分类：

• 固定式：V1（单目）、V2K（双目）、V2W（双目） - 安装角度固定或可手动调整
• 旋转式：O1（单目单轴）、X1（单目双轴）、X2W（双目双轴） - 支持云台控制和自动巡航

详细型号规格参见 数据字典 - 设备类型

遥测数据 (Telemetry)

遥测数据是设备上报的时序监测数据，是平台的核心数据类型。

HTTP API 响应格式

通过 HTTP API 查询历史遥测数据时，返回按指标分组的时间序列：

示例：

{
  "dx": [
    { "ts": 1735560000000, "value": 0.05 },
    { "ts": 1735563600000, "value": 0.06 }
  ],
  "dy": [
    { "ts": 1735560000000, "value": 0.02 },
    { "ts": 1735563600000, "value": 0.03 }
  ]
}

注意：MQTT 实时推送格式不同，详见 MQTT 数据订阅。

时间戳约定

时间转换示例：

UTC 时间戳: 1735560000000
UTC 时间:   2024-12-30T12:00:00Z
北京时间:   2024-12-30 20:00:00 (UTC+8)

告警系统 (Alarm)

告警系统采用四态状态模型，支持完整的告警生命周期管理。

告警生命周期

stateDiagram-v2
    [*] --> ACTIVE_UNACK: 触发告警
    ACTIVE_UNACK --> ACTIVE_ACK: 确认
    ACTIVE_UNACK --> CLEARED_UNACK: 自动清除
    ACTIVE_ACK --> CLEARED_ACK: 自动清除
    CLEARED_UNACK --> CLEARED_ACK: 确认
    CLEARED_ACK --> [*]: 归档

告警状态说明

告警级别 (3A 体系)

平台采用 3A 告警级别体系：

详细告警定义参见 数据字典 - 告警级别

告警触发流程

sequenceDiagram
    participant D as 设备
    participant I as Inteagle平台
    participant C as 第三方云平台

    D->>I: 上报遥测数据
    I->>I: 检查告警规则
    alt 超过阈值
        I->>I: 创建告警 (ACTIVE_UNACK)
        I-->>C: MQTT 推送告警
    end
    alt 恢复正常
        I->>I: 清除告警 (CLEARED_*)
        I-->>C: MQTT 推送清除
    end

数据访问方式

Inteagle 提供 SDK，集成了 HTTP 和 MQTT 两种通道，配合使用获取完整的数据能力。

SDK 集成的两种通道

典型使用流程

1. 初始化：通过 HTTP 查询项目、监测点列表
2. 加载历史：通过 HTTP 查询历史遥测数据
3. 实时更新：通过 MQTT 订阅接收实时数据推送

下一步

根据您的需求选择阅读路径：