q792602257/DataMate
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3a9afe34807c0eda12acfbfc56bda1f91aa063b2
DataMate/docs/knowledge-graph/schema/entities.md
Jerry Yan afcb8783aa 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

330 lines
12 KiB
Markdown
Raw Blame History

# DataMate 知识图谱 - 核心实体定义
> Schema 版本：1.0.0
> 更新日期：2026-02-17
## 概述
DataMate 知识图谱定义了 **8 类核心实体**，覆盖数据资产管理、任务追踪、组织归属和知识管理四大领域。
所有实体在 Neo4j 中统一使用 `Entity` 标签，通过 `type` 属性区分语义类型。每个实体都包含以下公共属性：
| 公共属性 | 类型 | 必填 | 说明 |
|---------|------|------|------|
| `id` | String (UUID) | 是 | 全局唯一标识符 |
| `name` | String | 是 | 实体名称 |
| `type` | String | 是 | 实体类型（见下文各类型定义） |
| `description` | String | 否 | 实体描述 |
| `graph_id` | String (UUID) | 是 | 所属图谱 ID，用于多租户隔离 |
| `source_id` | String | 否 | 来源记录 ID（MySQL 主键或外部系统 ID） |
| `source_type` | String | 否 | 来源类型：`SYNC`（MySQL 同步）、`EXTRACTION`（LLM 抽取）、`MANUAL`（人工创建） |
| `confidence` | Double | 否 | 置信度 0.0-1.0（同步数据默认 1.0，抽取数据由模型评分） |
| `properties_json` | String (JSON) | 否 | 类型特有 properties 的 JSON 序列化，各类型的 properties 定义见下文 |
| `created_at` | LocalDateTime | 是 | 创建时间 |
---
## 1. Dataset（数据集）
数据集是 DataMate 的核心资产，代表一组结构化或非结构化数据的集合。
**对应代码模型**：`data-management-service` 的 `Dataset.java`
### properties（properties_json 字段）
| property | 类型 | 必填 | 约束 | 说明 |
|----------|------|------|------|------|
| `dataset_type` | String | 是 | `IMAGE` / `TEXT` / `QA` / `MULTIMODAL` / `OTHER` | 数据集类型 |
| `status` | String | 是 | `DRAFT` / `ACTIVE` / `ARCHIVED` | 数据集状态 |
| `category` | String | 否 | 最长 50 字符 | 业务分类 |
| `format` | String | 否 | — | 数据格式（如 CSV、JSON、DICOM） |
| `record_count` | Long | 否 | >= 0 | 记录/文件数量 |
| `size_bytes` | Long | 否 | >= 0 | 数据集大小（字节） |
| `version` | Integer | 否 | >= 1 | 版本号 |
| `tags` | List\<String\> | 否 | — | 标签列表 |
### Cypher 示例
```cypher
// 创建 Dataset 实体（类型 properties 序列化到 properties_json）
CREATE (d:Entity {
id: 'a1b2c3d4-...',
name: '用户行为日志-v2',
type: 'Dataset',
description: '2025年Q4用户行为埋点数据',
graph_id: $graphId,
source_id: '12345',
source_type: 'SYNC',
confidence: 1.0,
properties_json: '{"dataset_type":"TEXT","status":"ACTIVE","category":"用户行为","format":"JSON","record_count":1500000,"size_bytes":2147483648,"version":2,"tags":["behavior","production"]}',
created_at: datetime()
})
```
---
## 2. Field（字段）
字段代表数据集中的列或属性元数据，是数据血缘分析和影响评估的基础单元。
**对应代码模型**：从 `DatasetFile` 的 schema 元数据中提取
### properties（properties_json 字段）
| property | 类型 | 必填 | 约束 | 说明 |
|----------|------|------|------|------|
| `data_type` | String | 是 | — | 数据类型（如 STRING、INT、FLOAT、DATETIME、JSON） |
| `nullable` | Boolean | 否 | — | 是否允许空值 |
| `is_primary_key` | Boolean | 否 | — | 是否为主键 |
| `default_value` | String | 否 | — | 默认值 |
| `sample_values` | List\<String\> | 否 | 最多 5 个 | 示例值 |
| `statistics` | String | 否 | JSON 格式 | 字段统计信息（null 率、唯一值数等） |
### Cypher 示例
```cypher
CREATE (f:Entity {
id: 'f1e2d3c4-...',
name: 'user_id',
type: 'Field',
description: '用户唯一标识符',
graph_id: $graphId,
source_type: 'SYNC',
confidence: 1.0,
properties_json: '{"data_type":"STRING","nullable":false,"is_primary_key":true,"sample_values":["U001","U002","U003"]}',
created_at: datetime()
})
```
---
## 3. LabelTask（标注任务）
标注任务代表一次数据标注活动，包括人工标注和自动标注。
**对应代码模型**：`data-annotation-service` 的 `LabelingProject`、`AutoAnnotationTask`；`task-coordination-service` 的 `TaskMeta`
### properties（properties_json 字段）
| property | 类型 | 必填 | 约束 | 说明 |
|----------|------|------|------|------|
| `task_mode` | String | 是 | `MANUAL` / `AUTO` / `HYBRID` | 标注模式 |
| `data_type` | String | 否 | `image` / `text` / `audio` / `video` / `pdf` 等 | 标注数据类型 |
| `labeling_type` | String | 否 | — | 标注类型（如 NER、目标检测、情感分析） |
| `status` | String | 是 | `PENDING` / `IN_PROGRESS` / `COMPLETED` / `FAILED` / `STOPPED` | 任务状态 |
| `progress` | Double | 否 | 0.0-100.0 | 完成进度百分比 |
| `template_name` | String | 否 | — | 使用的标注模板名称 |
### Cypher 示例
```cypher
CREATE (t:Entity {
id: 'e5f6a7b8-...',
name: '医学图像病灶标注-批次3',
type: 'LabelTask',
description: 'CT影像中肺结节目标检测标注',
graph_id: $graphId,
source_id: '67890',
source_type: 'SYNC',
confidence: 1.0,
properties_json: '{"task_mode":"HYBRID","data_type":"image","labeling_type":"object_detection","status":"IN_PROGRESS","progress":45.5,"template_name":"医学目标检测"}',
created_at: datetime()
})
```
---
## 4. Workflow（工作流）
工作流代表一组数据处理步骤的编排定义，涵盖数据清洗、数据合成、数据评估等处理管道。
**对应代码模型**：`data-cleaning-service` 的 `CleaningTemplate`；`data-collection-service` 的 `CollectionTemplate`；算子编排 `Operator`
### properties（properties_json 字段）
| property | 类型 | 必填 | 约束 | 说明 |
|----------|------|------|------|------|
| `workflow_type` | String | 是 | `CLEANING` / `SYNTHESIS` / `EVALUATION` / `COLLECTION` / `CUSTOM` | 工作流类型 |
| `status` | String | 否 | `DRAFT` / `ACTIVE` / `DEPRECATED` | 工作流状态 |
| `version` | String | 否 | — | 版本号 |
| `operator_count` | Integer | 否 | >= 0 | 包含的算子数量 |
| `schedule` | String | 否 | Cron 表达式 | 调度表达式（用于定时工作流） |
### Cypher 示例
```cypher
CREATE (w:Entity {
id: 'c9d0e1f2-...',
name: '文本去重清洗管道',
type: 'Workflow',
description: '基于SimHash的文本去重 + 格式标准化 + 质量过滤',
graph_id: $graphId,
source_type: 'SYNC',
confidence: 1.0,
properties_json: '{"workflow_type":"CLEANING","status":"ACTIVE","version":"2.1","operator_count":3}',
created_at: datetime()
})
```
---
## 5. Job（作业）
作业代表一次具体的任务执行实例，是工作流的运行时实体，记录输入输出和执行状态。
**对应代码模型**：`CleaningTask`、`DataSynthInstance`、`EvaluationTask`、`CollectionTask`、`TaskExecution`
### properties（properties_json 字段）
| property | 类型 | 必填 | 约束 | 说明 |
|----------|------|------|------|------|
| `job_type` | String | 是 | `CLEANING` / `SYNTHESIS` / `EVALUATION` / `COLLECTION` / `ANNOTATION` | 作业类型 |
| `status` | String | 是 | `PENDING` / `RUNNING` / `COMPLETED` / `FAILED` / `STOPPED` / `CANCELLED` | 执行状态 |
| `started_at` | String | 否 | ISO 8601 | 开始时间 |
| `completed_at` | String | 否 | ISO 8601 | 完成时间 |
| `duration_seconds` | Long | 否 | >= 0 | 执行耗时（秒） |
| `input_count` | Long | 否 | >= 0 | 输入记录/文件数 |
| `output_count` | Long | 否 | >= 0 | 输出记录/文件数 |
| `error_message` | String | 否 | — | 错误信息（失败时） |
### Cypher 示例
```cypher
CREATE (j:Entity {
id: 'd3e4f5a6-...',
name: '清洗作业-20260215-001',
type: 'Job',
description: '用户行为日志去重清洗',
graph_id: $graphId,
source_id: '54321',
source_type: 'SYNC',
confidence: 1.0,
properties_json: '{"job_type":"CLEANING","status":"COMPLETED","started_at":"2026-02-15T10:00:00","completed_at":"2026-02-15T10:35:00","duration_seconds":2100,"input_count":1500000,"output_count":1380000}',
created_at: datetime()
})
```
---
## 6. User（用户）
用户代表 DataMate 平台的操作人员，用于追踪数据资产的责任人和任务的执行者。
**对应代码模型**：`User.java`（`user` 表）
### properties（properties_json 字段）
| property | 类型 | 必填 | 约束 | 说明 |
|----------|------|------|------|------|
| `username` | String | 是 | 唯一 | 登录用户名 |
| `email` | String | 否 | — | 邮箱地址 |
| `role` | String | 否 | `ADMIN` / `USER` | 角色 |
| `enabled` | Boolean | 否 | — | 是否启用 |
### Cypher 示例
```cypher
CREATE (u:Entity {
id: 'b7c8d9e0-...',
name: '张三',
type: 'User',
graph_id: $graphId,
source_id: '1001',
source_type: 'SYNC',
confidence: 1.0,
properties_json: '{"username":"zhangsan","email":"zhangsan@example.com","role":"USER","enabled":true}',
created_at: datetime()
})
```
---
## 7. Org（组织）
组织代表企业内部的团队或部门，用于数据资产的归属管理和权限隔离。
**对应代码模型**：从 `User.organization` 字段聚合派生
### properties（properties_json 字段）
| property | 类型 | 必填 | 约束 | 说明 |
|----------|------|------|------|------|
| `org_code` | String | 否 | 唯一 | 组织编码 |
| `parent_org_id` | String | 否 | UUID | 上级组织 ID |
| `level` | Integer | 否 | >= 1 | 组织层级 |
| `member_count` | Integer | 否 | >= 0 | 成员数量 |
### Cypher 示例
```cypher
CREATE (o:Entity {
id: 'a0b1c2d3-...',
name: '数据工程部',
type: 'Org',
description: '负责数据采集、清洗和标注',
graph_id: $graphId,
source_type: 'SYNC',
confidence: 1.0,
properties_json: '{"org_code":"DE","level":2,"member_count":15}',
created_at: datetime()
})
```
---
## 8. KnowledgeSet（知识集）
知识集代表经过整理和验证的知识资产集合，是 RAG 检索和知识问答的基础。
**对应代码模型**：`KnowledgeSet.java`（`knowledge_set` 表）
### properties（properties_json 字段）
| property | 类型 | 必填 | 约束 | 说明 |
|----------|------|------|------|------|
| `status` | String | 是 | `DRAFT` / `PUBLISHED` / `ARCHIVED` / `DEPRECATED` | 知识集状态 |
| `domain` | String | 否 | — | 知识领域 |
| `business_line` | String | 否 | — | 业务线 |
| `sensitivity` | String | 否 | `PUBLIC` / `INTERNAL` / `CONFIDENTIAL` / `SECRET` | 敏感级别 |
| `item_count` | Integer | 否 | >= 0 | 包含的知识条目数 |
| `valid_from` | String | 否 | ISO 8601 | 有效期开始 |
| `valid_to` | String | 否 | ISO 8601 | 有效期结束 |
### Cypher 示例
```cypher
CREATE (k:Entity {
id: 'f4e5d6c7-...',
name: '医学影像标注规范知识库',
type: 'KnowledgeSet',
description: 'CT/MRI影像标注标准和常见病灶特征知识',
graph_id: $graphId,
source_id: '777',
source_type: 'SYNC',
confidence: 1.0,
properties_json: '{"status":"PUBLISHED","domain":"医学影像","business_line":"AI辅助诊断","sensitivity":"INTERNAL","item_count":320,"valid_from":"2026-01-01T00:00:00","valid_to":"2027-01-01T00:00:00"}',
created_at: datetime()
})
```
---
## 实体类型汇总
| 实体类型 | Neo4j type 值 | 核心用途 | 来源 |
|---------|--------------|---------|------|
| Dataset | `Dataset` | 数据资产管理、血缘追踪 | MySQL 同步 |
| Field | `Field` | 字段级血缘、影响分析 | MySQL 同步 / Schema 解析 |
| LabelTask | `LabelTask` | 标注任务追踪、人员管理 | MySQL 同步 |
| Workflow | `Workflow` | 流程编排、复用管理 | MySQL 同步 |
| Job | `Job` | 执行追踪、输入输出血缘 | MySQL 同步 |
| User | `User` | 责任人追踪、权限管理 | MySQL 同步 |
| Org | `Org` | 组织归属、资产隔离 | MySQL 同步 / 派生 |
| KnowledgeSet | `KnowledgeSet` | 知识资产管理、RAG 检索 | MySQL 同步 |
## 扩展说明
- **自定义实体类型**：除上述 8 类核心实体外，用户可通过 LLM 抽取或手动创建自定义实体类型。自定义实体使用相同的 `Entity` 标签和公共属性结构，`type` 字段可为任意字符串。
- **属性存储**：类型特有 properties 存储在 `properties_json` 字段中（JSON 序列化），不直接作为 Neo4j 节点属性。这保证了 schema 的灵活性，同时通过 `type` 字段实现类型区分。
- **索引策略**：`id`、`graph_id`、`type`、`name` 字段建立 Neo4j 索引，`properties_json` 中的 properties 不建立索引。如果某个 property 需要高频查询，应提升为节点顶层属性并建立索引。
Reference in New Issue View Git Blame Copy Permalink