math_cms/docs/STUDENT_KNOWLEDGE_GRAPH.md

学生知识图谱可视化系统

概述

学生知识图谱可视化系统是一个基于D3.js的交互式可视化工具，用于展示学生的知识点掌握情况和依赖关系。系统通过Filament管理后台提供直观的Web界面，帮助教师和学生理解学习进度和知识结构。

功能特性

1. 交互式知识图谱

• 力导向图布局: 使用D3.js力导向算法自动布局知识点
• 节点大小: 根据掌握度动态调整节点大小（10-40px）
• 颜色编码:
  • 🟢 绿色: 优秀 (≥80%)
  • 🔵 蓝色: 良好 (60-80%)
  • 🟡 黄色: 中等 (40-60%)
  • 🟠 橙色: 待提高 (20-40%)
  • 🔴 红色: 薄弱 (<20%)

2. 交互功能

• 悬浮提示: 鼠标悬浮显示节点详细信息
• 点击详情: 点击节点查看完整知识点信息
• 拖拽移动: 可拖拽节点调整布局
• 滚轮缩放: 支持0.5x-3x缩放
• 边拖拽边缩放: 实时调整视角

3. 数据可视化

• 掌握度统计: 展示优秀/良好/中等/待提高/薄弱知识点数量
• 平均掌握度: 计算整体掌握度平均值
• 分布图: Chart.js柱状图展示掌握度分布

4. 导出功能

• PNG导出: 一键导出知识图谱为PNG图片
• 高质量输出: 支持高分辨率图片导出

技术架构

前端技术栈

• Livewire 3: 响应式组件框架
• D3.js v7: 数据驱动的可视化库
• Chart.js: 图表绘制库
• Tailwind CSS: 样式框架

后端集成

• LearningAnalytics API: 端口5016
  • 获取学生掌握度数据
  • 获取知识点依赖关系
  • 获取学习路径
• 模拟数据: API不可用时的备用数据

文件结构

FilamentAdmin/
├── app/
│   ├── Livewire/
│   │   └── StudentKnowledgeGraph.php        # Livewire组件
│   ├── Filament/
│   │   └── Pages/
│   │       └── StudentKnowledgeGraphPage.php    # Filament页面
│   ├── Services/
│   │   └── KnowledgeGraphService.php        # API集成服务
│   └── Models/
│       └── Student.php                      # 学生模型
├── resources/
│   └── views/
│       ├── filament/
│       │   └── pages/
│       │       └── student-knowledge-graph-page.blade.php
│       └── livewire/
│           └── student-knowledge-graph.blade.php    # 可视化视图
└── docs/
    └── STUDENT_KNOWLEDGE_GRAPH.md           # 本文档

核心组件

StudentKnowledgeGraph.php

• 功能: 数据获取和处理
• 主要方法:
  • loadStudents(): 加载学生列表
  • loadStudentData(): 加载学生知识图谱数据
  • fetchKnowledgeGraphData(): 调用LearningAnalytics API
  • buildKnowledgeGraphData(): 构建D3.js数据格式
  • getMasteryColor(): 获取掌握度颜色
  • getMasterySize(): 计算节点大小

student-knowledge-graph.blade.php

• 功能: 可视化渲染和交互
• 主要特性:
  • D3.js力导向图渲染
  • 响应式布局
  • 交互式tooltip
  • 缩放和拖拽功能
  • Chart.js统计图表

KnowledgeGraphService.php

• 功能: HTTP客户端封装
• API端点:
  • /knowledge-points/: 获取知识点列表
  • /graph/node/{kpCode}: 获取技能列表
  • /skills/: 获取所有技能
  • /graph/relations: 获取关联关系
  • /api/mastery/{studentId}: 获取学生掌握度
  • /api/mastery/{studentId}/statistics: 获取统计信息

使用说明

访问路径

在Filament管理后台中导航到：

学习分析 > 学生知识图谱

操作步骤

1. 从学生下拉列表选择要查看的学生
2. 系统自动加载该学生的知识图谱数据
3. 在知识图谱中：
   • 鼠标悬浮查看节点详情
   • 点击节点查看详细信息
   • 拖拽节点调整位置
   • 滚轮缩放视图
4. 查看右侧掌握度统计信息
5. 点击"导出PNG"保存图谱

数据流程

1. Livewire组件从数据库获取学生列表
2. 选择学生后调用LearningAnalytics API
3. API返回掌握度数据和依赖关系
4. 构建D3.js所需的nodes和links数据
5. 渲染交互式力导向图
6. 显示统计图表和详细信息

API接口

LearningAnalytics服务 (端口5016)

// 获取学生掌握度
GET /api/mastery/{studentId}
Response: {
  "masteries": [
    {
      "student_id": "S001",
      "kp_code": "R01",
      "mastery_level": 0.85,
      "confidence_level": 0.8
    }
  ]
}

// 获取统计信息
GET /api/mastery/{studentId}/statistics
Response: {
  "total_knowledge_points": 8,
  "average_mastery": 0.594,
  "high_mastery_count": 1,
  "medium_mastery_count": 2,
  "low_mastery_count": 2
}

// 获取依赖关系
GET /api/knowledge/dependencies
Response: {
  "dependencies": [
    {
      "prerequisite_kp": "R01",
      "dependent_kp": "R02",
      "influence_weight": 0.9,
      "dependency_type": "must"
    }
  ]
}

配置项

环境变量

LEARNING_ANALYTICS_URL=http://localhost:5016
LEARNING_ANALYTICS_TIMEOUT=30

服务配置 (config/services.php)

'learning_analytics' => [
    'url' => env('LEARNING_ANALYTICS_URL', 'http://localhost:5016'),
    'timeout' => env('LEARNING_ANALYTICS_TIMEOUT', 30),
],

容错机制

1. API超时: 10秒超时后返回模拟数据
2. API失败: 自动加载本地模拟数据
3. 数据缺失: 使用默认值填充
4. 网络错误: 记录日志并显示错误信息

性能优化

1. 懒加载: 只在选择学生时加载数据
2. 模拟数据: API不可用时快速切换到本地数据
3. 缓存: 可在KnowledgeGraphService中添加缓存机制
4. 压缩: SVG导出时进行优化

浏览器兼容性

• Chrome 80+
• Firefox 75+
• Safari 13+
• Edge 80+

扩展建议

1. 节点详情页面: 点击节点跳转到知识点详情页
2. 学习路径推荐: 基于依赖关系生成学习建议
3. 多学生对比: 并排显示多个学生的知识图谱
4. 时间维度: 添加历史趋势图
5. 导出多种格式: 支持SVG、PDF、Excel导出
6. 3D视图: 升级到3D力导向图
7. 动画效果: 添加过渡动画

故障排除

常见问题

问题1: 知识图谱不显示

• 检查LearningAnalytics服务是否运行
• 查看浏览器控制台是否有JavaScript错误
• 确认学生数据存在

问题2: 统计数据错误

• 验证API返回的数据格式
• 检查模拟数据计算逻辑

问题3: 导出功能不工作

• 检查浏览器是否允许下载
• 确认canvas元素正确渲染

日志位置

# Laravel日志
storage/logs/laravel.log

# 查找相关错误
grep "知识图谱" storage/logs/laravel.log

开发者信息

• 开发日期: 2025-11-23
• 版本: v1.0
• 维护者: Claude Code
• 许可: MIT