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
2026-02-20 19:13:46 +08:00
parent 9b6ff59a11
commit afcb8783aa
29 changed files with 6472 additions and 37 deletions
--- a/docs/knowledge-graph/implementation.md
+++ b/docs/knowledge-graph/implementation.md
@@ -0,0 +1,395 @@
+# DataMate 知识图谱实施计划
+
+## 📅 总体时间线
+
+```
+第 0 阶段：基础设施（1周）        ✅ 已完成
+第 1 阶段：MVP（2-3周）           ⏳ 进行中
+第 2 阶段：GraphRAG 融合（3-4周）  ⏳ 待开始
+第 3 阶段：可视化与优化（4-6周）   ⏳ 待开始
+```
+
+**总计**：10-14 周
+
+---
+
+## ✅ 第 0 阶段：基础设施（已完成）
+
+### 目标
+搭建知识图谱的基础设施，包括 Neo4j、Java 服务、Python 模块。
+
+### 已完成任务
+
+#### 1. Neo4j Docker Compose 配置
+- ✅ 创建 `deployment/docker/neo4j/docker-compose.yml`
+- ✅ 配置 Neo4j 社区版
+- ✅ 端口：7474 (HTTP), 7687 (Bolt)
+- ✅ 数据持久化：Docker volume
+- ✅ 环境变量化密码
+
+#### 2. Makefile 更新
+- ✅ 添加 `neo4j-up`：启动 Neo4j
+- ✅ 添加 `neo4j-down`：停止 Neo4j
+- ✅ 添加 `neo4j-logs`：查看日志
+- ✅ 添加 `neo4j-shell`：进入 Cypher Shell
+
+#### 3. knowledge-graph-service（Spring Boot）
+- ✅ 创建完整的 DDD 分层架构
+- ✅ 实现 GraphEntity 的 CRUD
+- ✅ 实现 graphId 双重防御
+- ✅ 实现查询限流
+- ✅ 统一异常处理体系
+
+**文件清单**（11 个 Java 文件）：
+- `KnowledgeGraphServiceConfiguration.java`
+- `GraphEntityService.java`
+- `GraphEntity.java`, `GraphRelation.java`
+- `GraphEntityRepository.java`
+- `KnowledgeGraphErrorCode.java`
+- `KnowledgeGraphProperties.java`
+- `GraphEntityController.java`
+- `CreateEntityRequest.java`, `UpdateEntityRequest.java`, `CreateRelationRequest.java`
+- `application-knowledgegraph.yml`
+
+#### 4. kg_extraction 模块（Python）
+- ✅ 创建 `KnowledgeGraphExtractor` 类
+- ✅ 集成 LangChain LLMGraphTransformer
+- ✅ 支持异步/同步/批量抽取
+- ✅ 支持 schema-guided 模式
+- ✅ 兼容 OpenAI 及自部署模型
+
+**文件清单**（3 个 Python 文件）：
+- `__init__.py`
+- `models.py`：Pydantic 数据模型
+- `extractor.py`：抽取器实现
+
+#### 5. 代码审查和修复
+- ✅ 3 轮 Codex 审查
+- ✅ 2 轮 Claude 修复
+- ✅ 所有 P0 和 P1 问题已解决
+- ✅ 编译通过，无阻塞性问题
+
+### 成果
+- Commit: `5a553dd`
+- 文件变更：22 个文件，1007 行新增
+- 分支：`lsf`
+
+---
+
+## ⏳ 第 1 阶段：MVP（2-3周）
+
+### 目标
+实现基础的图谱构建和查询功能，支持 2-3 个高价值场景。
+
+### 任务列表
+
+#### 任务 1.1：实现 Python 抽取器的 FastAPI 接口（3天）
+
+**子任务**：
+1. 创建 `kg_extraction/interface.py`
+   - 定义 FastAPI 路由
+   - 实现 `/api/kg/extract` 端点
+   - 支持文本输入，输出节点和边
+
+2. 集成到 FastAPI 主路由
+   - 在 `app/module/__init__.py` 中注册路由
+   - 添加 API 文档
+
+3. 实现配置管理
+   - 从环境变量读取 API Key
+   - 使用 `SecretStr` 保护敏感信息
+
+4. 编写单元测试
+   - 测试抽取功能
+   - 测试错误处理
+
+**验收标准**：
+- ✅ 能够通过 API 调用抽取功能
+- ✅ 返回结构化的节点和边
+- ✅ 有完整的 API 文档
+- ✅ 单元测试覆盖率 > 80%
+
+#### 任务 1.2：实现 Java 服务的关系（Relation）功能（3天）
+
+**子任务**：
+1. 补充 `GraphRelationRepository`
+   - 实现 `findByGraphId`
+   - 实现 `findBySourceAndTarget`
+   - 实现 `findByType`
+
+2. 实现 `GraphRelationService`
+   - 创建关系
+   - 查询关系
+   - 更新关系
+   - 删除关系
+
+3. 实现 `GraphRelationController`
+   - `POST /{graphId}/relations`：创建关系
+   - `GET /{graphId}/relations`：列表查询
+   - `GET /{graphId}/relations/{relationId}`：单个查询
+   - `PUT /{graphId}/relations/{relationId}`：更新关系
+   - `DELETE /{graphId}/relations/{relationId}`：删除关系
+
+4. 编写单元测试和集成测试
+
+**验收标准**：
+- ✅ 关系的 CRUD 功能完整
+- ✅ 支持按类型、源节点、目标节点查询
+- ✅ 有完整的权限控制
+- ✅ 测试覆盖率 > 80%
+
+#### 任务 1.3：定义核心实体和关系模型（2天）
+
+**子任务**：
+1. 确定 5-8 类核心实体
+   - 分析 DataMate 现有数据模型
+   - 选择高价值实体
+   - 定义实体属性
+
+2. 定义实体之间的关系
+   - 分析业务流程
+   - 定义关系类型
+   - 定义关系属性
+
+3. 设计 Schema 版本管理
+   - 定义 Schema 版本号
+   - 实现 Schema 迁移机制
+   - 记录 Schema 变更历史
+
+4. 创建文档
+   - 实体和关系清单
+   - 属性说明
+   - 示例数据
+
+**验收标准**：
+- ✅ 有清晰的实体和关系定义
+- ✅ 有完整的文档
+- ✅ 有示例数据
+
+**建议的核心实体**（5-8 类）：
+1. **Dataset**：数据集
+2. **Field**：字段
+3. **LabelTask**：标注任务
+4. **Workflow**：工作流
+5. **Job**：作业
+6. **User**：用户
+7. **Model**：模型（可选）
+8. **Rule**：规则（可选）
+
+**建议的核心关系**：
+1. **HAS_FIELD**：数据集包含字段
+2. **TRIGGERS**：触发关系（Workflow → Job）
+3. **USES_DATASET**：使用数据集（Workflow → Dataset）
+4. **ASSIGNED_TO**：分配给（LabelTask → User）
+5. **PRODUCED_BY**：产生于（Dataset → Job）
+6. **DEPENDS_ON**：依赖于（Job → Job）
+
+#### 任务 1.4：实现基础的图谱构建流程（5天）
+
+**子任务**：
+1. 实现 MySQL → Neo4j 同步
+   - 创建 `GraphSyncService`
+   - 实现全量同步
+   - 实现增量同步
+   - 实现对账机制
+
+2. 实现手动触发构建
+   - 创建 `/api/kg/sync` 端点
+   - 支持按实体类型同步
+   - 支持按时间范围同步
+
+3. 实现同步监控
+   - 记录同步日志
+   - 统计同步数据量
+   - 监控同步耗时
+
+4. 编写集成测试
+   - 测试全量同步
+   - 测试增量同步
+   - 测试对账机制
+
+**验收标准**：
+- ✅ 能够从 MySQL 同步元数据到 Neo4j
+- ✅ 支持增量更新
+- ✅ 有完整的监控和日志
+- ✅ 集成测试通过
+
+#### 任务 1.5：实现基础查询功能（2天）
+
+**子任务**：
+1. 实现邻居查询
+   - 支持 N 跳邻居查询
+   - 支持按关系类型过滤
+   - 支持分页
+
+2. 实现路径查询
+   - 最短路径
+   - 所有路径（限制最大数量）
+
+3. 实现子图查询
+   - 按条件筛选子图
+   - 支持导出
+
+4. 编写单元测试
+
+**验收标准**：
+- ✅ 查询功能完整
+- ✅ 性能满足要求（< 1s）
+- ✅ 测试覆盖率 > 80%
+
+### 里程碑
+
+**M1.1**（第 1 周结束）：
+- ✅ Python 抽取器 API 完成
+- ✅ Java 关系功能完成
+
+**M1.2**（第 2 周结束）：
+- ✅ 核心实体和关系模型定义完成
+- ✅ 图谱构建流程完成
+
+**M1.3**（第 3 周结束）：
+- ✅ 基础查询功能完成
+- ✅ 集成测试通过
+- ✅ MVP 演示
+
+### 验收标准
+
+1. **功能完整性**：
+   - ✅ 能够从文本抽取实体和关系
+   - ✅ 能够存储到 Neo4j
+   - ✅ 能够查询和遍历图谱
+   - ✅ 支持基础的权限控制
+
+2. **性能指标**：
+   - ✅ 抽取响应时间 < 5s
+   - ✅ 查询响应时间 < 1s
+   - ✅ 同步吞吐量 > 1000 实体/分钟
+
+3. **质量指标**：
+   - ✅ 单元测试覆盖率 > 80%
+   - ✅ 集成测试通过
+   - ✅ 代码审查通过
+
+---
+
+## ⏳ 第 2 阶段：GraphRAG 融合（3-4周）
+
+### 目标
+将知识图谱与现有 RAG 系统深度融合，提升检索和生成质量。
+
+### 任务列表
+
+#### 任务 2.1：实现混合检索（2周）
+
+**子任务**：
+1. 在 `rag-query-service` 中增加图检索模块
+2. 实现 Milvus + Neo4j 并行检索
+3. 实现结果融合和排序
+4. 实现三元组文本化
+
+#### 任务 2.2：实现 GraphRAG（1周）
+
+**子任务**：
+1. 设计 GraphRAG 流程
+2. 实现 Context 构建
+3. 实现 LLM 生成
+4. 优化 Prompt
+
+#### 任务 2.3：评估和优化（1周）
+
+**子任务**：
+1. 设计评估指标
+2. 收集测试数据
+3. 进行 A/B 测试
+4. 优化检索策略
+
+### 验收标准
+- ✅ 混合检索性能优于单一检索
+- ✅ 支持可配置的检索策略
+- ✅ 有完整的评估指标
+
+---
+
+## ⏳ 第 3 阶段：可视化与优化（4-6周）
+
+### 目标
+提供友好的图谱可视化和编辑功能，优化性能和运维。
+
+### 任务列表
+
+#### 任务 3.1：前端图谱浏览器（2周）
+
+**子任务**：
+1. 搭建 React + AntV G6 项目
+2. 实现图谱可视化
+3. 实现交互功能（缩放、拖拽、搜索）
+4. 实现查询构建器
+
+#### 任务 3.2：Human-in-the-loop 编辑（1周）
+
+**子任务**：
+1. 实现实体编辑
+2. 实现关系编辑
+3. 实现批量操作
+4. 实现审核流程
+
+#### 任务 3.3：性能优化（1周）
+
+**子任务**：
+1. 优化索引策略
+2. 实现缓存机制
+3. 实现离线计算
+4. 优化查询语句
+
+#### 任务 3.4：监控和运维（1周）
+
+**子任务**：
+1. 集成 Prometheus + Grafana
+2. 实现备份和恢复
+3. 编写运维文档
+4. 进行压力测试
+
+### 验收标准
+- ✅ 支持大规模图谱可视化（10000+ 节点）
+- ✅ 支持实时编辑和反馈
+- ✅ 查询响应时间 < 1s
+- ✅ 有完整的监控和告警
+
+---
+
+## 📊 资源需求
+
+### 人力资源
+- **后端开发**：1-2 人
+- **前端开发**：1 人
+- **算法工程师**：1 人（兼职）
+- **测试工程师**：1 人（兼职）
+
+### 基础设施
+- **Neo4j**：4 核 8GB 内存（开发环境）
+- **MySQL**：现有资源
+- **Milvus**：现有资源
+- **Redis**：现有资源
+
+### 外部依赖
+- **LLM API**：OpenAI 或自部署模型
+- **对象存储**：备份使用
+
+---
+
+## 🎯 关键里程碑
+
+| 里程碑 | 时间 | 交付物 |
+|--------|------|--------|
+| M0 | 第 1 周 | 基础设施搭建完成 ✅ |
+| M1 | 第 4 周 | MVP 完成，支持基础图谱构建和查询 |
+| M2 | 第 8 周 | GraphRAG 融合完成，检索质量提升 |
+| M3 | 第 12 周 | 可视化和优化完成，系统上线 |
+
+---
+
+## 🔗 相关文档
+
+- [总体方案](./README.md)
+- [架构设计](./architecture.md)
+- [AI 分析结果](./analysis/)