# topv-adaptor-java

**Repository Path**: iotopo/topv-adaptor-java

## Basic Information

- **Project Name**: topv-adaptor-java
- **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-09-23
- **Last Updated**: 2025-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TopV Adaptor Java 实现

这是一个基于 Java 实现的 TopV 接口适配器。该程序内置了一个 HTTP 服务器，提供了实时数据查询、历史数据查询、设备标签查询、测点标签查询以及基于 NATS 的实时数据推送功能，用于实现用户自有平台与 TopV 进行接口适配。

## 接口实现

1. 推送接口

   **基于 NATS 推送实时数据** - 自动推送模拟数据到 NATS

2. 实时数据接口

​	HTTP 接口实现 - `GET /api/find_last`

3. 历史数据接口

​	HTTP 接口实现 - `POST /api/query_history`

4. 标签接口

   * 查询设备标签  - `GET /api/query_devices`

   * 查询测点标签  - `GET /api/query_points`


5. 反写接口

​	HTTP 接口实现 - `POST /api/set_value`


## 依赖要求

- Java 11+
- Maven 3.6+
- NATS 服务器 (默认连接 `nats://127.0.0.1:4222`)

## 构建和运行

### 1. 构建项目

```bash
mvn clean package -DskipTests
```

### 2. 运行项目

```bash
# 使用 Maven
mvn exec:java

# 或者使用生成的 jar 文件
java -jar target/topv-adaptor-1.0.0-SNAPSHOT-fat.jar
```

### 3. 启动 NATS 服务器

确保 NATS 服务器在 `127.0.0.1:4222` 运行：

```bash
# 使用 Docker
docker run -p 4222:4222 nats:latest

# 或者直接安装 NATS
nats-server
```

## API 接口

### 1. 查询实时数据

**请求：**
```http
GET /api/find_last
Content-Type: application/json

{
  "projectID": "project1",
  "tag": "group1.dev1.a",
  "device": false
}
```

**响应：**
```json
{
  "tag": "group1.dev1.a",
  "timestamp": "2024-01-01T12:00:00Z",
  "value": "12.3",
  "quality": 1
}
```

### 2. 查询历史数据

**请求：**
```http
POST /api/query_history
Content-Type: application/json

{
  "projectID": "project1",
  "tag": ["group1.dev1.a"],
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-01T23:59:59Z"
}
```

**响应：**
```json
{
  "results": [
    {
      "tag": "group1.dev1.a",
      "values": [
        {
          "value": "12.3",
          "time": "2024-01-01T12:00:00Z"
        }
      ]
    }
  ]
}
```

### 3. 查询设备标签

**请求：**
```http
GET /api/query_devices
Content-Type: application/json

{
  "projectID": "project1"
}
```

**响应：**
```json
[
  {
    "tag": "group1",
    "name": "group1",
    "children": [
      {
        "tag": "group1.dev1",
        "name": "dev1",
        "isDevice": true
      }
    ],
    "isDevice": false
  }
]
```

### 4. 查询测点标签

**请求：**
```http
GET /api/query_points
Content-Type: application/json

{
  "projectID": "project1",
  "parentTag": "group1.dev1"
}
```

**响应：**
```json
[
  {
    "tag": "group1.dev1.a",
    "name": "a"
  },
  {
    "tag": "group1.dev1.b",
    "name": "b"
  },
  {
    "tag": "group1.dev1.c",
    "name": "c"
  }
]
```

## NATS 推送

服务启动后会自动开始推送实时数据到 NATS，主题格式为：`rtdb.iotopo.{tag}`

推送的数据格式：
```json
{
  "tag": "group1.dev1.a",
  "timestamp": "2024-01-01T12:00:00Z",
  "value": 45.67,
  "quality": 1
}
```

## 配置

- HTTP 服务器端口：8080
- NATS 服务器地址：`nats://127.0.0.1:4222`
- 实时数据推送间隔：1秒

## 项目结构

```
src/main/java/com/iotopo/topv/
├── MainVerticle.java          # 主启动类
├── handler/
│   └── ApiHandler.java        # API 处理器
├── model/                     # 数据模型
│   ├── ValueItem.java
│   ├── DataItem.java
│   ├── Result.java
│   ├── HistoryResponse.java
│   ├── TagPoint.java
│   └── Device.java
└── service/
    └── NatsPushService.java   # NATS 推送服务
```