X-Agents/teams/api/neo4j-check.md

# Neo4j 连接测试

## 接口地址

```
POST /neo4j/check
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| host | string | 是 | Neo4j 主机 |
| port | int | 是 | Neo4j 端口（默认 7687） |
| username | string | 是 | 用户名（默认 neo4j） |
| password | string | 是 | 密码 |
| database | string | 否 | 数据库名（默认 neo4j） |
| name | string | 否 | 数据库名称，用于保存记录 |
| uri | string | 否 | Neo4j 连接地址（bolt://host:port） |
| description | string | 否 | 数据库描述 |

## 请求示例

```json
{
  "host": "localhost",
  "port": 7687,
  "username": "neo4j",
  "password": "password",
  "database": "neo4j",
  "name": "My Neo4j Database"
}
```

## 返回参数

| 参数 | 类型 | 说明 |
|------|------|------|
| success | bool | 是否连接成功 |
| message | string | 消息 |
| version | string | Neo4j 版本 |
| databases | array | 数据库列表 |
| databaseId | string | 数据库记录 ID（新增） |
| name | string | 数据库名称（新增） |
| description | string | 数据库描述（新增） |

## 返回示例

```json
{
  "success": true,
  "message": "connection successful",
  "version": "5.14.0",
  "databases": ["neo4j", "system"],
  "databaseId": "abc-123-def",
  "name": "Neo4j-neo4j",
  "description": "Neo4j neo4j@localhost:7687"
}
```

> **说明**：连接成功时，后端会自动检查数据库记录是否存在，不存在则创建并返回 `databaseId`、`name` 和 `description`。前端可使用这些信息进行后续保存图谱操作。

---

# Neo4j 获取图谱概览数据（核心接口）

获取所有标签(Labels)和关系类型(Relationship Types)的统计信息，用于前端图谱可视化。

## 接口地址

```
POST /neo4j/graphs
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| uri | string | 是 | Neo4j 连接地址，如 bolt://localhost:7687 |
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
| database | string | 否 | 数据库名（默认 neo4j） |

## 请求示例

```json
{
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "password": "password",
  "database": "neo4j"
}
```

## 返回参数

| 参数 | 类型 | 说明 |
|------|------|------|
| success | bool | 是否成功 |
| graphs | object | 图谱数据 |

### graphs 对象

| 参数 | 类型 | 说明 |
|------|
| labels------|------| | array | 标签列表 |
| relationshipTypes | array | 关系类型列表 |

### labels 数组项

| 参数 | 类型 | 说明 |
|------|------|------|
| name | string | 标签名称 |
| count | int | 该标签的节点数量 |

### relationshipTypes 数组项

| 参数 | 类型 | 说明 |
|------|------|------|
| name | string | 关系类型名称 |
| count | int | 该关系的数量 |

## 返回示例

```json
{
  "success": true,
  "graphs": {
    "labels": [
      {"name": "User", "count": 1523},
      {"name": "Order", "count": 856},
      {"name": "Product", "count": 2341},
      {"name": "Category", "count": 45},
      {"name": "Review", "count": 5678}
    ],
    "relationshipTypes": [
      {"name": "KNOWS", "count": 2341},
      {"name": "BOUGHT", "count": 5678},
      {"name": "BELONGS_TO", "count": 2341},
      {"name": "HAS_REVIEW", "count": 5678},
      {"name": "LOCATED_IN", "count": 1523}
    ]
  }
}
```

## 前端使用说明

前端使用 ECharts 力导向图谱展示：
- `labels` 生成图谱节点，count 决定节点大小
- `relationshipTypes` 生成图谱边
- 建议返回至少 5-10 个关系类型以便生成丰富图谱

---

# Neo4j 获取节点详情

## 接口地址

```
POST /neo4j/nodes
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| uri | string | 是 | Neo4j 连接地址，如 bolt://localhost:7687 |
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
| database | string | 否 | 数据库名 |
| label | string | 是 | 节点标签名 |
| limit | int | 否 | 返回数量限制，默认 10 |

## 请求示例

```json
{
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "password": "password",
  "label": "User",
  "limit": 10
}
```

## 返回参数

| 参数 | 类型 | 说明 |
|------|------|------|
| success | bool | 是否成功 |
| message | string | 消息 |
| nodes | array | 节点数据列表 |

## 返回示例

```json
{
  "success": true,
  "message": "success",
  "nodes": [
    {"id": "1", "name": "张三", "email": "zhangsan@example.com"},
    {"id": "2", "name": "李四", "email": "lisi@example.com"}
  ]
}
```

---

# Neo4j 获取关系详情

## 接口地址

```
POST /neo4j/relationships
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| uri | string | 是 | Neo4j 连接地址 |
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
| database | string | 否 | 数据库名 |
| relationship_type | string | 是 | 关系类型名 |
| limit | int | 否 | 返回数量限制，默认 10 |

## 请求示例

```json
{
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "password": "password",
  "relationship_type": "KNOWS",
  "limit": 10
}
```

## 返回参数

| 参数 | 类型 | 说明 |
|------|------|------|
| success | bool | 是否成功 |
| message | string | 消息 |
| relationships | array | 关系数据列表 |

## 返回示例

```json
{
  "success": true,
  "message": "success",
  "relationships": [
    {
      "startId": "1",
      "endId": "2",
      "startLabels": ["User"],
      "endLabels": ["User"],
      "since": "2020-01-01"
    }
  ]
}
```