# 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/)