# 学生知识图谱可视化系统

## 概述

学生知识图谱可视化系统是一个基于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)
```php
// 获取学生掌握度
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"
    }
  ]
}
```

## 配置项

### 环境变量
```bash
LEARNING_ANALYTICS_URL=http://localhost:5016
LEARNING_ANALYTICS_TIMEOUT=30
```

### 服务配置 (config/services.php)
```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元素正确渲染

### 日志位置
```bash
# Laravel日志
storage/logs/laravel.log

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

## 开发者信息

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