X-Agents/teams/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 时返回图谱数据）

请求参数：

{
  "db_type": "Neo4j",
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "password": "password",
  "database": "neo4j"
}

返回参数：

{
  "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

请求参数：

{
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "password": "password",
  "database": "neo4j",
  "label": "User",
  "limit": 5
}

返回参数：

{
  "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

请求参数：

{
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "password": "password",
  "database": "neo4j",
  "relationshipType": "KNOWS",
  "limit": 10
}

返回参数：

{
  "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. 如果关系类型少于节点数，可以创建额外连接让图谱更美观

前端缓存策略

方案设计

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

实现说明

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