# sparkers-courses

**Repository Path**: robot228/sparkers-courses

## Basic Information

- **Project Name**: sparkers-courses
- **Description**: 课程资源文件，用来保存使用MD文件编写的课程。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-14
- **Last Updated**: 2025-11-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 课程开发指南

本文档说明如何在Sparkers教育平台中创建新课程和编写章节内容。

## 构建课程流程

### 基础构建流程

1. 创建课程根目录
命名规则：使用英文小写字母和连字符，例如：`your-course-name`
2. 创建课程配置文件:index.json
文件字段说明：
- `title`: 课程标题
- `description`: 课程描述
- `level`: 课程等级（初级|中级|高级）
- `group`: 课程分组
- `imageUrl`: 课程封面图片URL（可选）
- `chapterList`: 章节列表，每个元素为章节名称
- `author`: 课程作者（可选）
- `status`: 课程状态（可选），默认值为 `draft`，可选值为 `draft`、`active`、`archived`
3. 创建章节目录
命名规则：使用英文小写字母和连字符，例如：`chapter-name`
4. 创建章节配置文件：info.json
文件字段说明：
- `title`: 章节标题
- `description`: 章节描述
- `level`: 章节等级（初级|中级|高级）
- `group`: 章节分组
- `imageUrl`: 章节封面图片URL（可选）
5. 创建章节数据文件：data.json
文件字段说明：
- `overview`: 章节概述
- `terminology`: 术语列表，每个元素为术语对象，包含以下字段
  - `term`: 术语名称
  - `definition`: 术语定义
  - `description`: 术语描述（可选）
- `keyPoints`: 关键知识点列表，每个元素为一个对象，包含以下字段
  - `title`: 知识点标题
  - `points`: 知识点列表，每个元素为一个字符串
- `attachments`: 附件列表，每个元素为一个对象，包含以下字段
  - `title`: 附件标题
  - `url`: 附件URL
6. 创建章节内容文件：content.md
文件内容使用Markdown格式编写，合理安排章节内容，使用示例或专业性语言讲述所有知识点。并详细解释出现的专业术语。
7. 创建练习题目文件（可选）：exercises.json
文件字段说明：
- 练习题目列表，每个元素为一个对象，包含以下字段
  - `filePrefix`: 练习题目文件名前缀（可选），用于指定文件上传练习的文件名前缀，推荐使用章节id+编号的命名规则。（例如："chapter1-01"）
  - `title`: 练习题目标题
  - `content`: 练习题目内容列表，每个元素为一个字符串，用于指定练习题目内容（支持Markdown格式）。
  - `type`: 练习类型（例如："multiple_choice"）支持以下类型
    - "single_choice": 单选题
    - "multiple_choice": 多选题
    - "true_false": 判断题
    - "file": 文件上传练习（例如："resource.ttt"）
  - `options`: 选项列表（如果是选择题），每个元素为一个字符串，用于指定选项内容（支持Markdown格式）。
  - `answer`: 正确答案，根据练习类型不同，格式也不同
    - "single_choice": 单选题，答案为选项的索引（从A开始）
    - "multiple_choice": 多选题，答案为选项索引列表（从A开始）
    - "true_false": 判断题，答案为"true"或"false"
    - "file": 文件上传练习，答案为文件名（例如："resource.ttt"）,可选字段，用于指定文件上传练习的文件名。
  - `hints`: 题目提示信息列表，用于解释为什么。

```
# 练习题目属性接口
interface ExercisesProps {
  filePrefix?: string;
  title: string;
  content: string[];
  type?: 'single_choice' | 'multiple_choice' | 'true_false' | 'file';
  options?: string[];
  answer?: string;
  hints?: string[];
}
```
8. 创建章节资源文件（可选）：files/
文件字段说明：
- 章节资源文件目录，用于存放章节中使用的图片、文件等资源。
- 文件名建议使用英文小写字母和连字符，例如：`image1.png`、`resource.ttt`等。

### 可选构建流程：创建交互组件

9. 创建交互组件文件（可选）：widgets.json
文件字段说明：
- 交互组件列表，每个元素为一个对象，包含以下字段
  - `title`: 组件标题
  - `type`: 组件类型，支持三种类型："widget"、"html"、"string"
  - `url`: 组件链接（可选，用于外部组件）
  - `config`: 组件配置项（可选），用于指定组件的额外参数

```json
# 交互组件属性接口
interface WidgetConfig {
  title: string;
  type: string;
  url?: string;
  config?: Record<string, string|number|boolean>;
}
```

**交互组件示例：**

```json
[
  {
    "title": "坐标计算器",
    "type": "widget",
    "config": {
      "precision": 2,
      "showSteps": true
    }
  },
  {
    "title": "自定义HTML组件",
    "type": "html",
    "url": "/components/custom-chart.html",
    "config": {
      "width": 800,
      "height": 400
    }
  },
  {
    "title": "文本说明",
    "type": "string",
    "config": {
      "content": "这是一个文本类型的交互组件，用于显示说明信息。"
    }
  }
]
```

## 目录结构

```
courses/
├── 课程名称/           # 课程根目录
│   ├── index.json      # 课程配置文件
│   └── 章节名称/       # 章节目录
│       ├── info.json   # 章节配置文件
│       ├── data.json   # 章节数据文件
│       ├── content.md  # 章节内容文件
│       ├── exercises.json # 练习题目文件（可选）
│       └── files/      # 章节资源文件目录（可选）
│           ├── image1.png
│           ├── image2.jpg
│           └── resource.ttt
```

## 创建新课程

### 1. 创建课程根目录
在 `courses/` 目录下创建新课程目录，目录名使用英文小写字母和连字符：
```bash
mkdir courses/your-course-name
```

### 2. 创建课程配置文件
在课程根目录下创建 `index.json` 文件：

```json
{
  "title": "课程标题",
  "description": "课程描述",
  "level": "初级|中级|高级",
  "group": "课程分组",
  "imageUrl": "课程封面图片URL（可选）",
  "courseList": ["章节1", "章节2", "章节3"]
}
```

### 3. 创建章节目录
在课程根目录下创建章节目录：
```bash
mkdir courses/your-course-name/chapter-name
```

### 4. 创建章节配置文件
在章节目录下创建 `info.json` 文件：

```json
{
  "title": "章节标题",
  "description": "章节描述",
  "level": "初级|中级|高级",
  "group": "章节分组",
  "imageUrl": "章节封面图片URL（可选）"
}
```

### 5. 创建章节数据文件
在章节目录下创建 `data.json` 文件：

```json
{
  "overview": "章节概述",
  "terminology": [
    {
      "term": "术语名称",
      "definition": "术语定义",
      "description": "术语描述（可选）"
    }
  ],
  "keyPoints": [
    {
      "title": "知识点标题",
      "points": ["知识点1", "知识点2"]
    }
  ],
  "attachments": [],
  "widgets": []
}
```

### 6. 创建章节内容文件
在章节目录下创建 `content.md` 文件，使用Markdown格式编写内容。

### 7. 创建练习题目文件（可选）
在章节目录下创建 `exercises.json` 文件：

```json
[
  {
    "filePrefix": "ex1",
    "title": "坐标变换练习1",
    "content": [
      "给定一个点P(2, 3, 4)，在坐标系A中，将其变换到坐标系B中。",
      "坐标系A的旋转矩阵为：",
      "| 1 0 0 |",
      "| 0 0 -1 |",
      "| 0 1 0 |",
      "坐标系B的平移向量为：(1, 2, 3)",
      "请计算点P在坐标系B中的坐标。"
    ]
  },
  {
    "title": "单选题测试",
    "content": [
      "下面哪个是 $\\sin{30}$ 的值"
    ],
    "type": "single_choice",
    "options": [
      "0.5",
      "1",
      "$\\frac{\\sqrt{3}}{2}$",
      "√2/2"
    ],
    "answer": "A",
    "hints": [
      "正弦函数的定义为 $\\sin{\\theta} = \\frac{\\theta}{\\pi}$"
    ]
  },
  {
    "title": "复选题测试",
    "content": [
      "下面对圆的半径为r的描述，正确的是"
    ],
    "type": "multiple_choice",
    "options": [
      "圆的周长为$2\\pi r$",
      "圆的面积为$\\pi r^2$",
      "圆的直径为$2r$",
      "圆的半径为$\\frac{r}{2}$"
    ],
    "answer": "A,D"
  },
  {
    "title": "判断题测试",
    "content": [
      "下面对圆的半径为r的描述，正确的是"
    ],
    "type": "true_false",
    "options": [
      "圆的周长为$2\\pi r$",
      "圆的半径为$\\frac{r}{2}$"
    ],
    "answer": "true"
  }
]
```

**题目类型说明：**

1. **基础练习类型**（无type字段）：
   - `filePrefix`: 练习文件前缀，用于标识练习
   - `title`: 练习标题
   - `content`: 练习内容数组，每行一个步骤

2. **单选题**（type: "single_choice"）：
   - `title`: 题目标题
   - `content`: 题目内容数组
   - `type`: "single_choice"
   - `options`: 选项数组，使用大写字母A-Z标识
   - `answer`: 正确答案（单个字母，如"A"）
   - `hints`: 提示信息数组（可选）

3. **多选题**（type: "multiple_choice"）：
   - `title`: 题目标题
   - `content`: 题目内容数组
   - `type`: "multiple_choice"
   - `options`: 选项数组，使用大写字母A-Z标识
   - `answer`: 正确答案（多个字母，用逗号分隔，如"A,D"）

4. **判断题**（type: "true_false"）：
   - `title`: 题目标题
   - `content`: 题目内容数组
   - `type`: "true_false"
   - `options`: 判断选项数组（通常为两个选项）
   - `answer`: 正确答案（"true"或"false"）

### 8. 创建资源文件目录（可选）
在章节目录下创建 `files/` 目录，存放图片、场景文件等资源。

## 文件命名规范

### 目录命名
- 使用英文小写字母
- 使用连字符分隔单词
- 避免使用空格和特殊字符
- 示例：`coppeliasim-introduction`

### 文件命名
- JSON配置文件：`index.json`, `info.json`, `data.json`
- 内容文件：`content.md`
- 练习文件：`exercises.json`
- 图片资源：使用有意义的英文名称

## 示例结构

### CoppeliaSim课程示例
```
courses/coppeliasim/
├── index.json                    # 课程配置
├── coppeliasim-introduction/     # 章节目录
│   ├── info.json                # 章节信息
│   ├── data.json               # 章节数据
│   ├── content.md              # 章节内容
│   ├── exercises.json          # 练习题目
│   └── files/                  # 资源文件
│       ├── main.png            # 主界面图片
│       ├── toolbar.png         # 工具栏图片
│       └── mobileRobotPathPlanning_BiTRRT.ttt  # 场景文件
└── basic-shapes/               # 其他章节
    ├── info.json
    ├── data.json
    └── content.md
```

## 最佳实践

### 内容编写
1. **结构清晰**: 使用合理的标题层级
2. **图文并茂**: 适当插入图片和图表
3. **术语统一**: 保持术语使用的一致性
4. **代码规范**: 代码示例要简洁易懂

### 资源管理
1. **图片优化**: 控制图片大小，推荐使用PNG格式
2. **路径正确**: 确保资源文件路径引用正确
3. **命名规范**: 资源文件要有描述性的名称

### 配置规范
1. **字段完整**: 确保所有必需字段都已填写
2. **格式正确**: 使用标准的JSON格式
3. **编码统一**: 使用UTF-8编码

## 注意事项

1. **路径引用**: 在Markdown中引用图片时使用相对路径
2. **文件编码**: 所有文件必须使用UTF-8编码
3. **JSON格式**: 确保JSON文件格式正确，无语法错误
4. **测试验证**: 创建完成后在平台上测试显示效果
5. **练习文件**: exercises.json中的filePrefix用于标识练习文件，确保唯一性
6. **资源文件**: 图片文件建议使用PNG格式，场景文件使用.ttt格式

## 示例结构

以下是一个完整的课程示例：

```
robotics/
├── index.json
├── robotics-coordinates/
│   ├── info.json
│   ├── data.json
│   └── content.md
└── two-link-system/
    ├── info.json
    ├── data.json
    └── content.md
```

## 命名规范

1. **目录命名**: 使用英文小写字母、数字和连字符（-），避免使用空格
2. **文件命名**: 使用固定的文件名（index.json, info.json, data.json, content.md）
3. **JSON格式**: 使用UTF-8编码，确保JSON格式正确

## 最佳实践

1. **保持一致性**: 确保所有课程的目录结构和文件命名保持一致
2. **内容质量**: 使用清晰的Markdown格式，包含适当的标题层级
3. **图片资源**: 将课程相关图片放置在统一的图片目录中
4. **测试验证**: 创建完成后验证JSON文件格式是否正确

## 注意事项

- 确保 `index.json` 中的 `chapterList` 数组与实际的章节目录名称完全匹配
- 章节目录名称不要包含特殊字符或空格
- 所有JSON文件必须使用有效的JSON格式
- 资源文件（如图片、场景文件）的路径引用要正确
- 严格按照文件字段要求填写
- 练习文件中的filePrefix要为唯一标识
- 内容文件使用标准的Markdown语法

如有问题，请参考现有课程的结构作为示例。