简介

用于知识图谱学习进度的可视化与统计的组合式函数。提供颜色与标签映射、节点尺寸随进度自适应、对整图批量应用进度增强、基于前置依赖的学习路径推荐，以及整体进度统计汇总。

---

接口定义

从 @/types/knowledge-graph 导入（以源码为准）：

• GraphNode：图节点，包含 id、size?、color?、progress? 等
• GraphLink：图连线，source/target 可为 string | { id: string }，含 relation_type
• GraphData：{ nodes: GraphNode[]; links: GraphLink[] }
• ProgressStatus：'not_started' | 'in_progress' | 'completed'
• NodeProgress：{ status: ProgressStatus; progress_score: number }

---

API 详解

getProgressColor(status, score = 0): string

• 功能：按 ProgressStatus 与分数区间返回节点展示色。
• 颜色映射（十六进制）：
  • not_started：灰色 #9ca3af
  • in_progress：
    • <30：#fbbf24
    • <70：#f59e0b
    • >=70：#d97706
  • completed：
    • >=90：#10b981
    • >=70：#059669
    • <70：#047857

---

getProgressLabel(status, score = 0): string

• 功能：产出进度标签文案。
• 示例：
  • not_started → 未学习
  • in_progress → 学习中 ${score}%
  • completed：按分数分别为 已完成 ${score}% (优秀|良好|及格)

---

calculateProgressNodeSize(progress, baseSize = 16): number

• 功能：依据节点进度调整节点尺寸。
• 规则：
  • not_started：baseSize * 0.8
  • in_progress：baseSize * (0.9 + (progress_score / 100) * 0.3)（范围约 0.9x ~ 1.2x）
  • completed：baseSize * 1.3

---

applyProgressToGraph(graphData, progressMap): GraphData

• 功能：将 progressMap: Map<string, NodeProgress> 应用于整图：
  • 为匹配的节点写入 node.progress
  • 基于进度重算 node.color 与 node.size
• 返回：新的 GraphData（不修改入参对象）。

---

getLearningPath(currentNode, allNodes, allLinks): GraphNode[]

• 功能：在当前节点已完成的前提下，基于连线的 relation_type === 'prerequisite'，推荐其后续待学节点。
• 筛选条件：
  • source 为 currentNode.id
  • 目标节点存在且 node.progress?.status === 'not_started'
• 返回：按筛选得到的后续节点列表；若当前节点未完成或无进度，则返回空数组。

---

calculateProgressStats(nodes): { total, not_started, in_progress, completed, completion_rate, average_score }

• 功能：对节点集合进行进度统计与评分均值计算。
• 统计口径：
  • 无 progress 视为 not_started
  • completion_rate = completed / total * 100
  • average_score 仅统计 progress_score > 0 的节点均值

---

使用示例（片段）

const progress = useKnowledgeGraphProgress()

// 1) 颜色与标签
const color = progress.getProgressColor('in_progress', 42)
const label = progress.getProgressLabel('completed', 88) // 已完成 88% (良好)

// 2) 节点尺寸
const size = progress.calculateProgressNodeSize(
  { status: 'in_progress', progress_score: 60 },
  18
)

// 3) 应用到整图
const map = new Map<string, NodeProgress>([
  ['node-1', { status: 'completed', progress_score: 95 }],
  ['node-2', { status: 'in_progress', progress_score: 40 }],
])
const enhanced = progress.applyProgressToGraph(graphData, map)

// 4) 学习路径推荐（仅在当前节点完成后生效）
const next = progress.getLearningPath(
  currentNode,
  enhanced.nodes,
  enhanced.links
)

// 5) 统计
const stats = progress.calculateProgressStats(enhanced.nodes)
// { total, not_started, in_progress, completed, completion_rate, average_score }

---

技术特点

1. 纯计算与幂等：所有方法均为纯函数风格输入/输出，便于测试与复用。
2. 视觉语义统一：颜色与尺寸策略对齐进度语义，增强信息密度。
3. 非破坏性增强：applyProgressToGraph 返回新对象，不改写原图数据。
4. 类型明确：充分利用 ProgressStatus、NodeProgress 约束，减少歧义。

---

使用建议

• 分数与状态一致性：completed 场景建议搭配 progress_score >= 70 以上的配色梯度以保持视觉期望。
• 默认尺寸：若你的图渲染器有全局尺寸策略，可将 baseSize 通过配置传入以保持一致。
• 路径语义：getLearningPath 依赖 relation_type='prerequisite' 与 source → target 的方向语义，请确保数据正确建模。
• 缺省进度：后端/同步尚未返回时，可默认构建空 Map 与占位 progress，避免闪烁。

版权所有

版权归属：Evoliant

许可证：MIT