You've already forked DataMate
feat(kg): 实现 Phase 3.1 前端图谱浏览器
核心功能： - G6 v5 力导向图，支持交互式缩放、平移、拖拽 - 5 种布局模式：force, circular, grid, radial, concentric - 双击展开节点邻居到图中（增量探索） - 全文搜索，类型过滤，结果高亮（变暗/高亮状态） - 节点详情抽屉：实体属性、别名、置信度、关系列表（可导航） - 关系详情抽屉：类型、源/目标、权重、置信度、属性 - 查询构建器：最短路径/全路径查询，可配置 maxDepth/maxPaths - 基于 UUID 的图加载（输入或 URL 参数 ?graphId=...） - 大图性能优化（200 节点阈值，超过时禁用动画） 新增文件（13 个）： - knowledge-graph.model.ts - TypeScript 接口，匹配 Java DTOs - knowledge-graph.api.ts - API 服务，包含所有 KG REST 端点 - knowledge-graph.const.ts - 实体类型颜色、关系类型标签、中文显示名称 - graphTransform.ts - 后端数据 → G6 节点/边格式转换 + 合并工具 - graphConfig.ts - G6 v5 图配置（节点/边样式、行为、布局） - hooks/useGraphData.ts - 数据钩子：加载子图、展开节点、搜索、合并 - hooks/useGraphLayout.ts - 布局钩子：5 种布局类型 - components/GraphCanvas.tsx - G6 v5 画布，力导向布局，缩放/平移/拖拽 - components/SearchPanel.tsx - 全文实体搜索，类型过滤 - components/NodeDetail.tsx - 实体详情抽屉 - components/RelationDetail.tsx - 关系详情抽屉 - components/QueryBuilder.tsx - 路径查询构建器 - Home/KnowledgeGraphPage.tsx - 主页面，整合所有组件 修改文件（5 个）： - package.json - 添加 @antv/g6 v5 依赖 - vite.config.ts - 添加 /knowledge-graph 代理规则 - auth/permissions.ts - 添加 knowledgeGraphRead/knowledgeGraphWrite - pages/Layout/menu.tsx - 添加知识图谱菜单项（Network 图标） - routes/routes.ts - 添加 /data/knowledge-graph 路由 新增文档（10 个）： - docs/knowledge-graph/ - 完整的知识图谱设计文档 Bug 修复（Codex 审查后修复）： - P1: 详情抽屉状态与选中状态不一致（显示旧数据） - P1: 查询构建器未实现（最短路径/多路径查询） - P2: 实体类型映射 Organization → Org（匹配后端） - P2: getSubgraph depth 参数无效（改用正确端点） - P2: AllPathsVO 字段名不一致（totalPaths → pathCount） - P2: 搜索取消逻辑无效（传递 AbortController.signal） - P2: 大图性能优化（动画降级） - P3: 移除未使用的类型导入 构建验证： - tsc --noEmit ✅ clean - eslint ✅ 0 errors/warnings - vite build ✅ successful
This commit is contained in:
289
docs/knowledge-graph/analysis/claude.md
Normal file
289
docs/knowledge-graph/analysis/claude.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# Claude 知识图谱分析结果
|
||||
|
||||
## 分析时间
|
||||
2026-02-17
|
||||
|
||||
## 核心建议
|
||||
|
||||
### 1. 技术选型
|
||||
|
||||
**图数据库**：Neo4j（社区版或企业版）
|
||||
|
||||
**存储架构**：MySQL + Neo4j 双存储
|
||||
- **MySQL**：元数据主库，保持现有业务逻辑
|
||||
- **Neo4j**：图结构专用存储，支持复杂查询
|
||||
|
||||
**同步策略**：最终一致性 + 对账机制
|
||||
|
||||
### 2. 架构设计（复用现有基础设施）
|
||||
|
||||
**核心原则**：
|
||||
- 复用现有的服务架构
|
||||
- 最小化对现有系统的影响
|
||||
- 渐进式集成
|
||||
|
||||
**集成方式**：
|
||||
```
|
||||
现有服务 → MySQL（主库）
|
||||
↓ 同步
|
||||
Neo4j（图库）
|
||||
↓ 查询
|
||||
kg-service（新服务）
|
||||
```
|
||||
|
||||
### 3. 数据建模（Schema 先行 + 版本管理）
|
||||
|
||||
#### Schema 设计原则
|
||||
1. **先行设计**：明确定义实体和关系
|
||||
2. **版本管理**：支持 Schema 演进
|
||||
3. **向后兼容**：新版本兼容旧版本
|
||||
4. **文档化**：详细记录每个版本的变更
|
||||
|
||||
#### 实体属性设计
|
||||
```json
|
||||
{
|
||||
"id": "UUID",
|
||||
"name": "名称",
|
||||
"type": "类型",
|
||||
"description": "描述",
|
||||
"tenant_id": "租户ID",
|
||||
"schema_version": "1.0",
|
||||
"created_at": "创建时间",
|
||||
"updated_at": "更新时间"
|
||||
}
|
||||
```
|
||||
|
||||
#### 关系属性设计
|
||||
```json
|
||||
{
|
||||
"source": "源节点ID",
|
||||
"target": "目标节点ID",
|
||||
"type": "关系类型",
|
||||
"confidence": "置信度（0-1）",
|
||||
"source": "来源（manual/auto）",
|
||||
"valid_from": "生效时间",
|
||||
"valid_to": "失效时间"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 实施路线图（4 阶段）
|
||||
|
||||
#### 第 0 阶段：基础设施（1周）✅
|
||||
- 搭建 Neo4j
|
||||
- 创建基础服务
|
||||
- 定义 Schema
|
||||
|
||||
#### 第 1 阶段：核心功能（2-3周）
|
||||
- 实现同步机制
|
||||
- 实现基础查询
|
||||
- 集成到现有系统
|
||||
|
||||
#### 第 2 阶段：高级功能（3-4周）
|
||||
- 实现 GraphRAG
|
||||
- 实现可视化
|
||||
- 性能优化
|
||||
|
||||
#### 第 3 阶段：持续优化
|
||||
- 扩展功能
|
||||
- 优化性能
|
||||
- 提升体验
|
||||
|
||||
### 5. 挑战解决方案
|
||||
|
||||
#### 数据一致性
|
||||
**问题**：MySQL 和 Neo4j 数据可能不一致
|
||||
|
||||
**解决方案**：
|
||||
- **最终一致性**：允许短暂的不一致
|
||||
- **对账机制**：定期对比并修复
|
||||
- **事件驱动**：通过事件同步变更
|
||||
|
||||
**实现**：
|
||||
```java
|
||||
@Scheduled(cron = "0 0 2 * * *") // 每天凌晨 2 点
|
||||
public void reconcile() {
|
||||
// 1. 查询 MySQL 中的所有实体
|
||||
List<Dataset> datasets = datasetRepository.findAll();
|
||||
|
||||
// 2. 查询 Neo4j 中的所有实体
|
||||
List<GraphEntity> graphEntities = graphEntityRepository.findAll();
|
||||
|
||||
// 3. 对比并找出差异
|
||||
List<Diff> diffs = compare(datasets, graphEntities);
|
||||
|
||||
// 4. 修复差异
|
||||
for (Diff diff : diffs) {
|
||||
if (diff.getType() == DiffType.MISSING_IN_NEO4J) {
|
||||
syncToNeo4j(diff.getEntity());
|
||||
} else if (diff.getType() == DiffType.OUTDATED_IN_NEO4J) {
|
||||
updateNeo4j(diff.getEntity());
|
||||
}
|
||||
}
|
||||
|
||||
// 5. 记录日志
|
||||
log.info("Reconciliation completed: {} diffs fixed", diffs.size());
|
||||
}
|
||||
```
|
||||
|
||||
#### 性能优化
|
||||
**问题**：大规模图谱查询性能下降
|
||||
|
||||
**解决方案**：
|
||||
- **索引策略**：在高频字段上创建索引
|
||||
- **限制遍历深度**：最大 3 跳
|
||||
- **Redis 缓存**：缓存热点数据
|
||||
- **离线计算**：预计算常用子图
|
||||
|
||||
**索引创建**：
|
||||
```cypher
|
||||
// 实体 ID 索引
|
||||
CREATE INDEX entity_id IF NOT EXISTS FOR (n:Entity) ON (n.id);
|
||||
|
||||
// 租户 ID 索引
|
||||
CREATE INDEX entity_tenant_id IF NOT EXISTS FOR (n:Entity) ON (n.tenant_id);
|
||||
|
||||
// 复合索引
|
||||
CREATE INDEX entity_id_graph_id IF NOT EXISTS
|
||||
FOR (n:Entity) ON (n.id, n.graph_id);
|
||||
```
|
||||
|
||||
#### 前端可视化
|
||||
**问题**：大规模图谱难以可视化
|
||||
|
||||
**解决方案**：
|
||||
- **分层加载**：先加载核心节点，再加载周边
|
||||
- **子图裁剪**：只显示相关子图
|
||||
- **WebGL 渲染**：使用 WebGL 提升性能
|
||||
- **虚拟滚动**：只渲染可见区域
|
||||
|
||||
**推荐库**：
|
||||
- Cytoscape.js（功能丰富）
|
||||
- AntV G6（国产，文档友好）
|
||||
- vis.js（简单易用）
|
||||
|
||||
### 6. 最佳实践
|
||||
|
||||
#### 开发实践
|
||||
1. **API 规范一致**：遵循 RESTful 规范
|
||||
2. **复用现有模式**：使用现有的 DTO、ErrorCode
|
||||
3. **事件驱动解耦**：通过事件同步变更
|
||||
4. **Cypher 注入防护**：使用参数化查询
|
||||
|
||||
#### 运维实践
|
||||
1. **Neo4j 备份**：每天全量备份
|
||||
2. **监控告警**：Prometheus + Grafana
|
||||
3. **性能调优**：定期分析慢查询
|
||||
4. **容量规划**：根据数据增长预测资源需求
|
||||
|
||||
#### 部署实践
|
||||
1. **Docker 部署**：使用 docker-compose
|
||||
2. **Kubernetes 扩展**：使用 Helm Chart
|
||||
3. **灰度发布**：先在小范围验证
|
||||
4. **回滚机制**：支持快速回滚
|
||||
|
||||
### 7. 代码实现细节
|
||||
|
||||
#### 双重防御示例
|
||||
```java
|
||||
// Controller 层：格式校验
|
||||
@GetMapping("/{graphId}/entities/{entityId}")
|
||||
public GraphEntity getEntity(
|
||||
@PathVariable @Pattern(regexp = UUID_REGEX, message = "graphId 格式无效")
|
||||
String graphId,
|
||||
@PathVariable @Pattern(regexp = UUID_REGEX, message = "entityId 格式无效")
|
||||
String entityId
|
||||
) {
|
||||
return entityService.getEntity(graphId, entityId);
|
||||
}
|
||||
|
||||
// Service 层：业务校验
|
||||
public GraphEntity getEntity(String graphId, String entityId) {
|
||||
// 1. 校验 graphId 格式
|
||||
validateGraphId(graphId);
|
||||
|
||||
// 2. 查询实体（同时校验 graphId 和 entityId）
|
||||
return entityRepository.findByIdAndGraphId(entityId, graphId)
|
||||
.orElseThrow(() -> BusinessException.of(
|
||||
KnowledgeGraphErrorCode.ENTITY_NOT_FOUND
|
||||
));
|
||||
}
|
||||
|
||||
// Repository 层：数据访问
|
||||
@Query("MATCH (n:Entity {id: $id, graph_id: $graphId}) RETURN n")
|
||||
Optional<GraphEntity> findByIdAndGraphId(
|
||||
@Param("id") String id,
|
||||
@Param("graphId") String graphId
|
||||
);
|
||||
```
|
||||
|
||||
#### 查询限流示例
|
||||
```java
|
||||
public List<GraphEntity> getNeighbors(
|
||||
String graphId,
|
||||
String entityId,
|
||||
int depth,
|
||||
int limit
|
||||
) {
|
||||
// Clamp 参数到配置的最大值
|
||||
int actualDepth = Math.min(depth, properties.getMaxDepth());
|
||||
int actualLimit = Math.min(limit, properties.getMaxNodesPerQuery());
|
||||
|
||||
// 查询
|
||||
return entityRepository.findNeighbors(
|
||||
graphId, entityId, actualDepth, actualLimit
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 8. 建议的下一步
|
||||
|
||||
**立即行动**：
|
||||
1. 实现 Relation 的完整功能
|
||||
2. 实现 MySQL → Neo4j 同步
|
||||
3. 补充单元测试
|
||||
|
||||
**短期目标**（1-2周）：
|
||||
1. 完成 MVP 功能
|
||||
2. 集成到现有系统
|
||||
3. 进行性能测试
|
||||
|
||||
**中期目标**（1-2月）：
|
||||
1. 实现 GraphRAG
|
||||
2. 实现可视化
|
||||
3. 上线第一个场景
|
||||
|
||||
## 与其他工具的对比
|
||||
|
||||
| 维度 | Claude | Codex | Gemini |
|
||||
|------|--------|-------|--------|
|
||||
| **技术选型** | Neo4j | Neo4j/JanusGraph | Neo4j |
|
||||
| **架构重点** | 复用现有基础设施 | 3个新模块 | GraphRAG 融合 |
|
||||
| **数据建模** | Schema先行+版本管理 | 10类实体+6类关系 | 灵活Schema+embedding |
|
||||
| **实现路径** | 4阶段 | 4阶段（0-3） | 3阶段（MVP优先） |
|
||||
| **独特优势** | 深度集成现有系统 | 详细的领域模型 | LangChain+RAG融合 |
|
||||
|
||||
## 关键洞察
|
||||
|
||||
1. **深度集成**：Claude 强调复用现有基础设施，最小化影响
|
||||
2. **最终一致性**：提出了实用的数据同步和对账方案
|
||||
3. **详细的代码示例**：提供了可直接使用的代码片段
|
||||
4. **运维实践**：关注生产环境的监控、备份、部署
|
||||
|
||||
## 建议采纳度
|
||||
|
||||
**强烈推荐**：
|
||||
- ✅ MySQL + Neo4j 双存储架构
|
||||
- ✅ 最终一致性 + 对账机制
|
||||
- ✅ 双重防御（Controller + Service）
|
||||
- ✅ 查询限流
|
||||
- ✅ 运维实践（备份、监控）
|
||||
|
||||
**可选**：
|
||||
- ⚠️ 事件驱动同步（可以先用定时任务）
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [总体方案](../README.md)
|
||||
- [架构设计](../architecture.md)
|
||||
- [Gemini 分析结果](./gemini.md)
|
||||
- [Codex 分析结果](./codex.md)
|
||||
Reference in New Issue
Block a user