# 编程学习模块教学内容与资料下载实现计划

## 需求总结
为编程学习模块（Python基础）添加三部分教学内容：
1. **文章教学** - Markdown格式的章节内容
2. **视频学习** - 章节视频播放
3. **资料下载** - 新增功能，支持下载课程资料（代码、PDF等）

## 当前状态分析

### 现有架构
- **Course** → **Chapter** → **ChapterContent**（Markdown内容）
- 章节已有 `video_url` 字段，但**缺少资料下载功能**
- `CourseLearn.tsx` 已有视频和文档标签页，但无下载入口

### 需要新增的内容
- 5个Python基础章节的完整Markdown教学内容
- 视频链接（使用免费教学视频）
- **资料下载功能**（新模型 + 前端UI）

## 实现方案

### 1. 新增资料下载模型

**文件**：`learn/models.py`

**新增模型** `CourseMaterial`：
```python
class CourseMaterial(models.Model):
    chapter = models.ForeignKey(Chapter, on_delete=models.CASCADE, related_name='materials', verbose_name='章节')
    title = models.CharField(max_length=200, verbose_name='资料名称')
    file = models.FileField(upload_to='learn/materials/%Y/%m/', verbose_name='文件')
    file_type = models.CharField(max_length=20, choices=[('pdf', 'PDF'), ('code', '代码'), ('other', '其他')], default='other')
    file_size = models.PositiveIntegerField(default=0, verbose_name='文件大小（字节）')
    download_count = models.PositiveIntegerField(default=0, verbose_name='下载次数')
    sort_order = models.IntegerField(default=0)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        ordering = ['sort_order']
        verbose_name = '课程资料'
        verbose_name_plural = '课程资料'
```

### 2. 新增资料下载API

**文件**：`learn/views.py`

**新增视图**：
- `MaterialListView` - 获取章节资料列表
- `MaterialDownloadView` - 文件下载接口（增加下载次数统计）

**文件**：`learn/serializers.py`

**新增序列化器**：
- `MaterialSerializer` - 资料列表序列化

### 3. 前端资料下载UI

**文件**：`CourseLearn.tsx`

**修改内容**：
- 新增"资料"标签页，显示当前章节的可下载资料
- 资料卡片展示：文件名、类型图标、大小、下载次数
- 点击下载按钮触发文件下载
- 支持PDF、代码文件、压缩包等类型图标

### 4. Python基础教学内容

**文件**：`learn/management/commands/seed_python_content.py`

**新增种子命令**，为Python课程填充5个章节内容：

#### 章节1：Python 简介与安装
- **文章内容**：Python历史、特点、安装步骤、第一个程序
- **视频**：B站Python入门视频链接
- **资料**：Python安装包链接、练习题

#### 章节2：变量与数据类型
- **文章内容**：变量命名、数字、字符串、列表、字典、元组
- **视频**：数据类型详解视频
- **资料**：练习题代码、速查表PDF

#### 章节3：条件判断与循环
- **文章内容**：if/else、for循环、while循环、break/continue
- **视频**：流程控制教学视频
- **资料**：编程练习题、示例代码

#### 章节4：函数与模块
- **文章内容**：函数定义、参数、返回值、模块导入、标准库
- **视频**：函数与模块视频
- **资料**：常用模块速查表、练习代码

#### 章节5：面向对象编程
- **文章内容**：类与对象、继承、多态、封装、魔术方法
- **视频**：OOP教学视频
- **资料**：完整示例代码、OOP设计模式PDF

### 5. 种子数据更新

**文件**：`seed_courses.py`

在创建章节时，同时创建示例 `ChapterContent` 内容（Markdown格式）。

## 涉及文件

### 后端（Django）
| 文件 | 修改类型 | 说明 |
|------|----------|------|
| `learn/models.py` | 修改 | 新增 `CourseMaterial` 模型 |
| `learn/serializers.py` | 修改 | 新增 `MaterialSerializer` |
| `learn/views.py` | 修改 | 新增资料列表和下载接口 |
| `learn/urls.py` | 修改 | 新增资料相关路由 |
| `learn/admin.py` | 修改 | 注册 `CourseMaterial` 模型 |
| `learn/management/commands/seed_python_content.py` | 新增 | Python基础内容种子命令 |

### 前端（React）
| 文件 | 修改类型 | 说明 |
|------|----------|------|
| `CourseLearn.tsx` | 修改 | 新增资料下载标签页和UI |
| `CourseLearn.css` | 修改 | 资料卡片样式 |
| `api/request.ts` | 修改 | 新增资料API调用 |
| `locales/zh.json` | 修改 | 新增资料相关文本 |

## 资料下载功能设计

### 数据库流程
```
Chapter → CourseMaterial（1:N）
用户点击下载 → API查询文件 → 文件流返回 → download_count + 1
```

### 前端展示
```
[视频] [文档] [资料]  ← 标签页
┌─────────────────────────┐
│ 📄 Python基础速查表.pdf   │
│ 📝 1.2 MB  |  128次下载   │
│ [ 立即下载 ]             │
├─────────────────────────┤
│ 💻 示例代码.zip          │
│ 📝 856 KB  |  89次下载    │
│ [ 立即下载 ]             │
└─────────────────────────┘
```

### 支持的文件类型
| 类型 | 扩展名 | 图标 |
|------|--------|------|
| PDF | .pdf | 📄 |
| 代码 | .py, .js, .html, .css | 💻 |
| 压缩包 | .zip, .rar, .7z | 📦 |
| 文档 | .doc, .docx, .md | 📝 |
| 其他 | * | 📎 |

## 验证步骤

1. **模型迁移**
   ```bash
   python manage.py makemigrations learn
   python manage.py migrate
   ```

2. **种子数据**
   ```bash
   python manage.py seed_python_content
   ```

3. **API测试**
   - GET /api/learn/materials/?chapter_id=1 - 获取资料列表
   - GET /api/learn/materials/1/download/ - 下载文件

4. **前端测试**
   - 进入Python课程 → 选择章节 → 点击"资料"标签
   - 显示资料列表 → 点击下载按钮 → 文件下载成功

## 风险评估
- 文件上传需要配置 `MEDIA_ROOT` 和 `MEDIA_URL`
- 大文件下载可能需要流式传输
- 下载权限控制（是否需要登录）
- 文件大小限制和存储配额

## 后续优化
- 资料上传进度条
- 批量下载（打包为zip）
- 资料搜索功能
- 用户上传资料审核