X-Agents/team-require/web/neo4j-graphs.md

# 后端需求 - Neo4j 图谱数据获取（完善版）

## 需求描述

Neo4j 连接成功后，需要获取图谱数据供前端可视化展示。前端使用 ECharts 力导向图谱展示科幻风格效果。

## Neo4j 图谱核心概念

Neo4j 是图数据库，与关系型数据库概念不同：
- **Node（节点）** - 类似于表，但不需要固定结构
- **Label（标签）** - 类似于表的类型名（如 User, Order）
- **Relationship（关系）** - 节点之间的边
- **Relationship Type（关系类型）** - 关系的类型（如 KNOWS, OWNS）

## 后端需要提供的接口

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

返回所有 Label（标签）和 Relationship Type（关系类型）的统计信息。这是前端图谱可视化的核心数据来源。

**接口地址：** `POST /database/check` （复用现有接口，在 db_type 为 Neo4j 时返回图谱数据）

**请求参数：**
```json
{
  "db_type": "Neo4j",
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "password": "password",
  "database": "neo4j"
}
```

**返回参数：**
```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}
    ]
  }
}
```

### 2. 获取节点详情（可选，用于点击显示）

点击某个 Label 节点时，获取该类型节点的样本数据用于详情展示。

**接口地址：** `POST /database/neo4j/nodes`

**请求参数：**
```json
{
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "password": "password",
  "database": "neo4j",
  "label": "User",
  "limit": 5
}
```

**返回参数：**
```json
{
  "success": true,
  "nodes": [
    {"id": "1", "name": "张三", "email": "zhangsan@example.com", "created_at": "2024-01-01"},
    {"id": "2", "name": "李四", "email": "lisi@example.com", "created_at": "2024-01-02"}
  ],
  "properties": [
    {"name": "id", "type": "string"},
    {"name": "name", "type": "string"},
    {"name": "email", "type": "string"},
    {"name": "created_at", "type": "datetime"}
  ]
}
```

### 3. 获取关系详情（可选）

获取两个节点之间的关系数据。

**接口地址：** `POST /database/neo4j/relationships`

**请求参数：**
```json
{
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "password": "password",
  "database": "neo4j",
  "relationshipType": "KNOWS",
  "limit": 10
}
```

**返回参数：**
```json
{
  "success": true,
  "relationships": [
    {
      "id": "rel-1",
      "source": "1",
      "target": "2",
      "properties": {"since": "2020-01-01"}
    }
  ]
}
```

## 数据结构说明

### graphs.labels[] - 标签列表（前端图谱节点）
| 字段 | 类型 | 说明 | 用途 |
|------|------|------|------|
| name | string | 标签名称（如 User, Order） | 作为图谱节点显示 |
| count | int | 该标签的节点数量 | 计算节点大小 symbolSize |

### graphs.relationshipTypes[] - 关系类型列表（前端图谱边）
| 字段 | 类型 | 说明 | 用途 |
|------|------|------|------|
| name | string | 关系类型（如 KNOWS, OWNS） | 作为图谱边的标签 |
| count | int | 该关系的数量 | 可能影响边的粗细 |

### nodes[] - 节点详情
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 节点唯一标识 |
| (其他) | any | 节点的其他属性 |

### relationships[] - 关系详情
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 关系唯一标识 |
| source | string | 起始节点ID |
| target | string | 目标节点ID |
| properties | object | 关系属性 |

## 前端图谱展示逻辑

前端使用 ECharts 力导向图谱（force-directed graph），展示方式如下：

1. **节点生成**：
   - 根据 `graphs.labels` 数组生成节点
   - `name` 作为节点显示名称
   - `count` 决定节点大小（symbolSize = log2(count+1) * 12）
   - 节点颜色按索引分配科幻配色（紫、蓝、绿、橙、粉、青）
   - 节点带发光效果（shadowBlur: 20）

2. **边生成**：
   - 根据 `graphs.relationshipTypes` 生成边
   - 边 label 显示关系类型名称
   - 曲线连接（curveness: 0.2）
   - 带箭头

3. **交互效果**：
   - 弹簧物理效果（force layout）
   - 节点可拖拽
   - 滚轮缩放
   - hover 相邻节点高亮

## 优先级

高 - Neo4j 可视化的核心数据

## 注意事项

1. Neo4j 连接使用官方 Go 驱动：`github.com/neo4j/neo4j-go-driver`
2. 注意处理连接超时和认证失败的情况
3. 大数据量时需要限制返回数量（limit 参数）
4. **建议返回足够多的关系类型**（建议至少 5-10 个），以便前端生成丰富的图谱连接
5. 如果关系类型少于节点数，可以创建额外连接让图谱更美观

## 前端缓存策略

### 方案设计
- **首次加载**：获取数据并缓存
- **第二次展示**：直接使用缓存，秒开
- **刷新按钮**：用户手动点击刷新获取最新数据

### 实现说明
前端会缓存图谱数据，第二次进入时直接展示缓存数据，提升用户体验。同时提供"刷新"按钮供用户手动刷新。