useKnowledgeGraphEditor

约 979 字大约 3 分钟

2025-08-29

简介

用于知识图谱编辑（教师侧）的组合式函数，提供对知识点与知识点关系的增删改查，以及批量编辑、选择集管理与数据校验能力。基于 Supabase 持久化数据。

接口定义

从 @/types/knowledge-graph 导入的类型（仅列出关键项，具体以代码为准）：

GraphNode：知识图谱节点模型
GraphLink：知识图谱关系模型
GraphData：图整体数据结构
EditOperation：批量编辑操作项定义（type、id、data）
NodeEditData：知识点可编辑字段
LinkEditData：关系可编辑字段
RelationType：关系类型枚举

返回对象结构

调用 useKnowledgeGraphEditor() 返回以下属性与方法：

状态：
- isEditing: Readonly<Ref<boolean>>：是否处于编辑请求中
- selectedNodes: Readonly<Ref<Set<string>>>：已选择的节点 ID 集合
- selectedLinks: Readonly<Ref<Set<string>>>：已选择的关系 ID 集合
知识点操作：
- addKnowledgePoint(courseId: string, data: NodeEditData): Promise<boolean>
- editKnowledgePoint(nodeId: string, data: Partial<NodeEditData>): Promise<boolean>
- deleteKnowledgePoint(nodeId: string): Promise<boolean>（软删除，设置 is_active=false）
关系操作：
- addKnowledgeRelation(data: LinkEditData): Promise<boolean>
- editKnowledgeRelation(linkId: string, data: Partial<LinkEditData>): Promise<boolean>
- deleteKnowledgeRelation(linkId: string): Promise<boolean>
批量操作：
- batchEdit(operations: EditOperation[]): Promise<boolean>
选择管理：
- toggleNodeSelection(nodeId: string): void
- toggleLinkSelection(linkId: string): void
- clearSelection(): void
数据验证：
- validateNodeData(data: NodeEditData): string[]
- validateLinkData(data: LinkEditData, nodes: GraphNode[]): string[]

方法详解

`addKnowledgePoint(courseId, data)`

功能：创建知识点并关联到课程（插入 knowledge_points，然后插入 course_knowledge_points）
参数：
- courseId: 课程 ID
- data: NodeEditData
返回：Promise<boolean> 成功/失败
注意：创建成功后将默认 is_active=true

`editKnowledgePoint(nodeId, data)`

功能：更新知识点字段
参数：
- nodeId: 知识点 ID
- data: Partial<NodeEditData>
返回：Promise<boolean>
实现要点：自动写入 updated_at = new Date().toISOString()

`deleteKnowledgePoint(nodeId)`

功能：软删除知识点
返回：Promise<boolean>
实现要点：设置 is_active=false 并更新 updated_at

`addKnowledgeRelation(data)`

功能：创建知识点关系（插入 knowledge_relations）
参数：LinkEditData（source_point_id、target_point_id、relation_type、weight?、description?）
返回：Promise<boolean>
默认值：weight 未提供时默认 1.0

`editKnowledgeRelation(linkId, data)`

功能：更新知识点关系
返回：Promise<boolean>

`deleteKnowledgeRelation(linkId)`

功能：删除知识点关系（硬删除 knowledge_relations 指定记录）
返回：Promise<boolean>

`batchEdit(operations)`

功能：顺序执行一组编辑操作，任一失败则抛错并返回 false
参数：EditOperation[]
支持类型：
- add_node（需外部补充课程 ID，当前实现为占位）
- edit_node → 调用 editKnowledgePoint
- delete_node → 调用 deleteKnowledgePoint
- add_link → 调用 addKnowledgeRelation
- edit_link → 调用 editKnowledgeRelation
- delete_link → 调用 deleteKnowledgeRelation

选择管理

toggleNodeSelection(nodeId)：切换节点选择状态
toggleLinkSelection(linkId)：切换关系选择状态
clearSelection()：清空已选节点与关系

数据验证

`validateNodeData(data)`

校验项：
- 名称必填且不超过 200 字符
- difficulty_level 必须在 1-5 之间

`validateLinkData(data, nodes)`

校验项：
- source_point_id、target_point_id 必填
- 源与目标不得相同
- relation_type 必填
- weight（如提供）需在 0-1 之间
- 源/目标节点必须存在于传入的 nodes 中

技术特点

并发状态控制：isEditing 防止重复提交
软删除策略：知识点采用软删除，保留历史
类型驱动：充分利用 NodeEditData、LinkEditData、EditOperation 等类型约束
最小职责：持久化与校验分层清晰，可扩展批量操作

使用示例（片段）

const editor = useKnowledgeGraphEditor()

// 新增知识点并关联课程
const ok1 = await editor.addKnowledgePoint(courseId, {
  name: '向量空间',
  description: '线性代数核心概念',
  difficulty_level: 3,
  content: '...',
})

// 新增关系
const ok2 = await editor.addKnowledgeRelation({
  source_point_id: sourceId,
  target_point_id: targetId,
  relation_type: 'prerequisite',
  weight: 0.8,
})

// 批量操作
await editor.batchEdit([
  { type: 'edit_node', id: nodeId, data: { name: '更新后的名称' } },
  { type: 'delete_link', id: linkId },
])

// 选择管理
editor.toggleNodeSelection(nodeId)
editor.toggleLinkSelection(linkId)
editor.clearSelection()

使用建议

课程 ID 传递：add_node 的批量操作需要外部传入 courseId 才能落库。
软删除一致性：删除知识点使用软删除，前端需过滤 is_active=false 的记录。
校验优先：在提交前先调用 validateNodeData / validateLinkData，减少后端错误。
原子性需求：当前批量操作为顺序执行且遇错中断，如需跨表原子性请迁移到数据库函数或使用事务（Edge Function/存储过程）。

版权所有

版权归属：Evoliant

许可证：MIT