产品文档已发布

RAILWISE-OS 与 TSM 数据对接指南

RAILWISE-OS 与 RAILWISE-TSM 全站仪自动化监测平台的数据对接规范与集成方案

复核 2026-07-09入门公开可引用RailWise 技术团队

产品文档

RAILWISE-OS 与 TSM 数据对接指南

AI语义标签: #数据对接 #TSM集成 #全站仪自动化监测 #MQTT #实时数据 #系统集成

1. 概述

RAILWISE-TSM（Total Station Monitoring）是 RailWise 的全站仪自动化监测平台，负责自动化监测设备的控制与数据采集。RAILWISE-OS 作为业务操作系统，需要与 TSM 进行数据对接，实现“采集 → 处理 → 业务”的闭环。

1.1 对接架构

┌─────────────────────────────────────────────────────────────┐
│                    数据对接架构                               │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐      MQTT/REST      ┌──────────────┐     │
│  │ RAILWISE-TSM │  <───────────────>  │ RAILWISE-OS  │     │
│  │              │     实时数据推送      │              │     │
│  │ • 全站仪控制  │                     │ • 数据校验    │     │
│  │ • 自动采集   │                     │ • 异常预警    │     │
│  │ • 原始数据   │                     │ • 报告生成    │     │
│  │ • 设备状态   │                     │ • 业务管理    │     │
│  └──────────────┘                     └──────────────┘     │
│         │                                      │           │
│         │ 设备指令下发                            │ 告警通知   │
│         ▼                                      ▼           │
│  ┌──────────────┐                     ┌──────────────┐     │
│  │  全站仪设备   │                     │  企业微信/钉钉  │     │
│  │  Leica/Trimble│                     │  邮件/短信     │     │
│  └──────────────┘                     └──────────────┘     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

1.2 对接模式

对接模式	实时性	适用场景	技术方案
实时推送	秒级	自动化监测、高频快报	MQTT + WebSocket
定时同步	分钟级	定期汇总、日报生成	REST API 批量写入
文件同步	小时级	历史数据迁移、离线数据	SFTP / 对象存储

2. 实时推送对接（MQTT）

2.1 TSM 侧配置

在 RAILWISE-TSM 管理后台配置数据推送目标：

# TSM 推送配置
data_push:
  enabled: true
  target: "railwise-os"
  protocol: "mqtt"
  broker: "mqtts://mqtt.os.railwise.cn:8883"
  auth:
    username: "tsm_proj_abc123"
    password: "auto_generated_password"
  topics:
    data: "railwise/proj_abc123/{device_id}/data"
    status: "railwise/proj_abc123/{device_id}/status"
  format: "json"
  compression: "gzip"  # 可选
  batch_size: 10       # 批量推送条数
  interval_ms: 5000    # 推送间隔（毫秒）

2.2 数据推送格式

TSM 向 OS 推送的数据格式：

{
  "timestamp": "2026-07-08T08:00:00+08:00",
  "device_id": "tsm_001",
  "device_type": "total_station",
  "device_model": "Leica TS16",
  "project_id": "proj_abc123",
  "session_id": "sess_20260708_080000",
  "records": [
    {
      "point_id": "point_k12_350_01",
      "point_name": "K12+350-1#",
      "measured_at": "2026-07-08T08:00:00+08:00",
      "values": {
        "x": 395123.456,
        "y": 2812345.678,
        "z": 15.234,
        "dx": 0.5,
        "dy": -0.3,
        "dz": 0.1
      },
      "quality": {
        "hdop": 1.2,
        "vdop": 1.8,
        "confidence": 0.98
      }
    }
  ],
  "environment": {
    "temperature": 28.5,
    "humidity": 65,
    "weather": "晴"
  }
}

2.3 OS 侧接收配置

RAILWISE-OS 自动识别 TSM 推送的数据，无需额外配置。数据接入后自动执行：

数据校验：执行 20+ 校验规则
质量标记：自动标记 valid / warning / suspicious
异常检测：触发阈值预警、趋势预警
数据归档：写入 PostgreSQL 主数据库
事件通知：触发 Webhook / 企业微信通知

3. 定时同步对接（REST API）

3.1 TSM 数据查询 API

TSM 提供数据查询接口供 OS 主动拉取：

# TSM 数据查询（在 TSM 平台执行）
curl -X GET "https://api.tsm.railwise.cn/v2/projects/proj_abc123/data" \
  -H "X-API-Key: tsmk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -G -d "start_time=2026-07-08T00:00:00+08:00" \
     -d "end_time=2026-07-08T23:59:59+08:00" \
     -d "format=os_compatible"

3.2 OS 批量写入

将 TSM 数据转换为 OS 格式后批量写入：

import { RailWiseOSClient } from '@railwise/os-sdk';
import { RailWiseTSMClient } from '@railwise/tsm-sdk';

const osClient = new RailWiseOSClient({
  apiKey: 'rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  baseURL: 'https://api.os.railwise.cn/v3',
});

const tsmClient = new RailWiseTSMClient({
  apiKey: 'tsmk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  baseURL: 'https://api.tsm.railwise.cn/v2',
});

// 同步 TSM 数据到 OS
async function syncTSMDataToOS(
  projectId: string,
  startTime: string,
  endTime: string
) {
  // 1. 从 TSM 获取数据
  const tsmData = await tsmClient.data.query({
    projectId,
    startTime,
    endTime,
    format: 'os_compatible',
  });

  // 2. 数据转换（TSM 格式 → OS 格式）
  const osRecords = tsmData.records.map(record => ({
    point_id: record.pointId,
    sensor_type: 'total_station',
    measured_at: record.measuredAt,
    values: {
      x: record.values.x,
      y: record.values.y,
      z: record.values.z,
      dx: record.values.dx,
      dy: record.values.dy,
      dz: record.values.dz,
    },
  }));

  // 3. 批量写入 OS
  const result = await osClient.data.batchUpload({
    project_id: projectId,
    records: osRecords,
  });

  console.log(`同步完成: ${result.success}/${result.total}`);
  return result;
}

// 定时同步（每小时）
setInterval(async () => {
  const now = new Date();
  const oneHourAgo = new Date(now.getTime() - 60 * 60 * 1000);

  await syncTSMDataToOS(
    'proj_abc123',
    oneHourAgo.toISOString(),
    now.toISOString()
  );
}, 60 * 60 * 1000);

4. 设备状态同步

4.1 TSM 设备状态推送

TSM 实时推送设备状态到 OS：

{
  "timestamp": "2026-07-08T08:00:00+08:00",
  "device_id": "tsm_001",
  "device_type": "total_station",
  "status": "online",
  "metrics": {
    "battery_level": 85,
    "temperature": 32.5,
    "storage_usage": 45,
    "last_calibration": "2026-06-15",
    "calibration_due": "2026-12-15"
  },
  "active_session": {
    "session_id": "sess_20260708_080000",
    "project_id": "proj_abc123",
    "started_at": "2026-07-08T08:00:00+08:00",
    "points_count": 12,
    "measurements_count": 48
  }
}

4.2 OS 设备管理

OS 接收设备状态后，在设备管理模块展示：

设备在线/离线状态
电池电量与温度
校准到期提醒
当前监测任务信息

5. 指令下发

5.1 OS 向 TSM 下发指令

OS 可通过 TSM API 向设备下发指令：

# 启动监测任务
curl -X POST "https://api.tsm.railwise.cn/v2/devices/tsm_001/sessions" \
  -H "X-API-Key: tsmk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123",
    "session_type": "scheduled",
    "interval_minutes": 240,
    "points": ["point_k12_350_01", "point_k12_350_02"],
    "options": {
      "measurements_per_point": 3,
      "tolerance_mm": 0.5
    }
  }'

5.2 支持的指令类型

指令	说明	参数
`start_session`	启动监测会话	project_id, points, interval
`stop_session`	停止监测会话	session_id
`calibrate`	执行校准	calibration_type
`restart`	重启设备	-
`update_config`	更新配置	config_key, config_value

6. 数据一致性保障

6.1 数据校验机制

TSM 采集 → 原始数据校验 → 推送至 OS → OS 业务校验 → 入库
                ↓                           ↓
           校验失败 → 标记异常          校验失败 → 异常通知

6.2 数据对账

# 数据对账脚本
#!/bin/bash

PROJECT_ID="proj_abc123"
DATE="2026-07-08"

# 1. 统计 TSM 数据量
TSM_COUNT=$(curl -s "https://api.tsm.railwise.cn/v2/projects/$PROJECT_ID/data/count?date=$DATE" \
  -H "X-API-Key: tsmk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" | jq '.data.count')

# 2. 统计 OS 数据量
OS_COUNT=$(curl -s "https://api.os.railwise.cn/v3/data/monitoring/count?project_id=$PROJECT_ID&date=$DATE" \
  -H "X-API-Key: rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" | jq '.data.count')

# 3. 对比
if [ "$TSM_COUNT" -eq "$OS_COUNT" ]; then
  echo "✅ 数据一致: TSM=$TSM_COUNT, OS=$OS_COUNT"
else
  echo "⚠️ 数据不一致: TSM=$TSM_COUNT, OS=$OS_COUNT"
  # 触发告警
fi

7. 高频快报集成

7.1 4小时快报自动触发

TSM 完成 4 小时监测周期后，自动触发 OS 报告生成：

{
  "event_type": "tsm.session_completed",
  "timestamp": "2026-07-08T12:00:00+08:00",
  "data": {
    "session_id": "sess_20260708_080000",
    "project_id": "proj_abc123",
    "device_id": "tsm_001",
    "duration_minutes": 240,
    "measurements_count": 288,
    "points_count": 12,
    "abnormal_count": 1,
    "report_trigger": {
      "template_id": "tpl_4h_rapid_report",
      "auto_generate": true
    }
  }
}

7.2 OS 自动响应

OS 收到 tsm.session_completed 事件后：

自动拉取该时段完整数据
执行数据校验与异常检测
如 auto_generate: true，自动生成 4 小时快报
如 abnormal_count > 0，触发告警通知

8. 故障排查

问题	可能原因	解决方案
数据未同步	MQTT 连接断开	检查 TSM 网络配置，重启 MQTT 连接
数据格式错误	TSM/OS 版本不匹配	升级至兼容版本
数据丢失	网络中断	启用 TSM 本地缓存，恢复后补传
时区不一致	时间戳格式错误	统一使用 ISO 8601 + 时区偏移
设备状态不同步	心跳超时	调整心跳间隔，检查防火墙

9. 相关文档

文档版本: v3.2.0 | 最后更新: 2026-07-08