# 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 需要高频查询，应提升为节点顶层属性并建立索引。