feat: PLANNING体系首版（00路线图/02任务总表/03执行协议/I-03/I-04/registry42口径）+M1止血交付

2026-09-12 14:25:25 +08:00
commit 39af400fc8
472 changed files with 36277 additions and 0 deletions
@@ -0,0 +1,157 @@
+# 编程学习视频方案 - BDCloudVideoView 集成计划
+
+## 概述
+在编程学习模块中引入百度智能云视频播放器(BDCloudVideoView)，支持B站视频和本地视频两种来源，并增强文档/资料绑定功能。
+
+## 当前状态分析
+
+### 现有视频机制
+- `Chapter.video_url` - URLField，仅支持外部链接
+- `Chapter.video_poster` - ImageField，视频封面图
+- 前端 `VideoPlayer` 组件支持 Bilibili/YouTube/Vimeo 嵌入 + 原生 video 标签
+- **无本地视频上传功能**
+
+### 现有资料机制
+- `CourseMaterial` 模型支持：PDF、代码、文档、压缩包、其他
+- 支持文件下载和下载次数统计
+- 缺少视频资料、数据集等类型
+
+## 实施方案
+
+### 步骤1：扩展 Chapter 模型 - 增加视频源类型字段
+**文件**: `chunyu_project/learn/models.py`
+
+在 `Chapter` 模型中添加：
+```python
+VIDEO_SOURCE_CHOICES = [
+    ('bilibili', 'B站视频'),
+    ('local', '本地视频'),
+]
+
+class Chapter:
+    # 新增字段
+    video_source = models.CharField(max_length=20, choices=VIDEO_SOURCE_CHOICES, default='bilibili')
+    video_local = models.FileField(upload_to='learn/videos/%Y/%m/', blank=True, null=True)
+```
+
+### 步骤2：创建数据库迁移
+**操作**: `python manage.py makemigrations learn` + `python manage.py migrate`
+
+### 步骤3：更新序列化器
+**文件**: `chunyu_project/learn/serializers.py`
+
+- `ChapterSerializer` 增加 `video_source`, `video_local_url` 字段
+- 确保前端能获取完整的视频信息
+
+### 步骤4：创建 BDCloudVideoView 组件
+**文件**: `chunyu_project_react/src/components/BDCloudVideoView/BDCloudVideoView.tsx`
+
+功能：
+- 根据 `video_source` 自动切换播放源
+- B站模式：使用百度智能云播放器加载B站视频
+- 本地模式：使用百度智能云播放器加载本地视频URL
+- 支持视频封面、自动播放、清晰度切换
+- 统一的控制栏和UI风格
+
+```typescript
+// 核心接口
+interface BDCloudVideoViewProps {
+  videoSource: 'bilibili' | 'local';
+  bilibiliUrl?: string;
+  localUrl?: string;
+  posterUrl?: string;
+  title?: string;
+}
+```
+
+### 步骤5：更新 CourseLearn 页面
+**文件**: `chunyu_project_react/src/pages/CourseLearn/CourseLearn.tsx`
+
+- 将 `VideoPlayer` 替换为 `BDCloudVideoView`
+- 增加视频源切换UI（B站/本地）
+- 加载百度智能云播放器 SDK（CDN引入）
+
+### 步骤6：更新 LearnEditor 编辑器
+**文件**: `chunyu_project_react/src/pages/LearnEditor/LearnEditor.tsx`
+
+在章节编辑中增加：
+- 视频源类型选择器（B站/本地）
+- B站URL输入框
+- 本地视频上传组件（支持mp4/mov/webm）
+- 视频封面上传
+
+### 步骤7：增强 CourseMaterial 资料类型
+**文件**: `chunyu_project/learn/models.py`
+
+扩展 `CourseMaterial.FILE_TYPE_CHOICES`：
+```python
+FILE_TYPE_CHOICES = [
+    ('pdf', 'PDF'),
+    ('code', '代码'),
+    ('doc', '文档'),
+    ('video', '视频'),      # 新增
+    ('dataset', '数据集'),   # 新增
+    ('zip', '压缩包'),
+    ('other', '其他'),
+]
+```
+
+### 步骤8：添加视频下载功能
+**文件**: `chunyu_project/learn/views.py`
+
+新增API端点：
+- `GET /learn/chapters/<pk>/video/download/` - 下载本地视频
+- 添加下载统计和权限检查
+
+### 步骤9：前端下载功能集成
+**文件**: `chunyu_project_react/src/pages/CourseLearn/CourseLearn.tsx`
+
+- 在播放器组件中添加下载按钮
+- 本地视频直接下载
+- B站视频提示使用B站客户端下载
+
+### 步骤10：CSS样式适配
+**文件**:
+- `CourseLearn.css` - 播放器容器样式
+- `BDCloudVideoView.css` - 组件专用样式
+- 确保在暗色模式下正常显示
+
+## 文件清单
+
+| 文件路径 | 操作 | 说明 |
+|---------|------|------|
+| `chunyu_project/learn/models.py` | 修改 | 添加 video_source, video_local 字段；扩展资料类型 |
+| `chunyu_project/learn/serializers.py` | 修改 | 序列化器增加新字段 |
+| `chunyu_project/learn/views.py` | 修改 | 添加视频下载API |
+| `chunyu_project/learn/urls.py` | 修改 | 添加视频下载路由 |
+| `chunyu_project_react/src/components/BDCloudVideoView/BDCloudVideoView.tsx` | 新建 | 百度智能云播放器组件 |
+| `chunyu_project_react/src/components/BDCloudVideoView/index.ts` | 新建 | 导出入口 |
+| `chunyu_project_react/src/pages/CourseLearn/CourseLearn.tsx` | 修改 | 替换为BDCloudVideoView |
+| `chunyu_project_react/src/pages/LearnEditor/LearnEditor.tsx` | 修改 | 添加视频源选择器和上传组件 |
+| `chunyu_project_react/src/pages/CourseLearn/CourseLearn.css` | 修改 | 适配播放器样式 |
+| `chunyu_project_react/src/pages/LearnEditor/LearnEditor.css` | 修改 | 适配编辑器样式 |
+| `chunyu_project_react/index.html` | 修改 | 引入百度智能云播放器CDN |
+
+## 验证步骤
+
+1. **模型验证**: 运行迁移，确认数据库字段正确添加
+2. **后端API验证**: 通过Swagger测试章节CRUD，确认新字段正常
+3. **编辑器验证**: 登录后台，编辑章节，验证：
+   - 可选择视频源类型（B站/本地）
+   - 可输入B站URL
+   - 可上传本地视频文件
+4. **前端播放器验证**: 访问课程学习页，验证：
+   - B站视频使用BDCloudVideoView正常播放
+   - 本地视频使用BDCloudVideoView正常播放
+   - 视频封面正确显示
+5. **资料下载验证**: 验证新增的"视频"和"数据集"类型资料可正常下载
+6. **暗色模式验证**: 在暗色模式下检查播放器和编辑器样式
+
+## 假设与决策
+
+1. **视频源默认值**: 默认为 `bilibili`，兼容现有数据
+2. **本地视频存储**: 使用 Django FileField 存储在本地文件系统
+3. **播放器SDK**: 百度智能云播放器通过CDN引入，无需npm安装
+4. **视频格式**: 本地视频支持 mp4、mov、webm 格式
+5. **视频大小限制**: 默认限制 500MB，可通过设置调整
+6. **资料类型扩展**: 新增"视频"和"数据集"两种类型，保留原有类型