npm package: @qycreate/qy-learn-host-api-sdk
Description: Host API SDK for Remote applications to report course info and learning progress
Author: your-name
Latest version: 0.1.0

# @qycreate/qy-learn-host-api-sdk

Host API SDK for Remote applications to report course info and learning progress.

用于远程应用调用Host API的SDK，支持报告课程信息（Course > Module > Lesson三层结构）和学习进度。

## 安装

```bash
npm install @qycreate/qy-learn-host-api-sdk
```

## 使用

### 报告课程信息

一次性报告完整的课程结构（Course > Module > Lesson），用于初始化后端数据库：

```typescript
import { reportCourseInfo, Course } from '@qycreate/qy-learn-host-api-sdk';

const course: Course = {
  courseId: 'course-001',
  title: '前端开发课程',
  description: '这是一门前端开发课程',
  version: '1.0.0',
  modules: [
    {
      moduleId: 'module-001',
      courseId: 'course-001',
      title: 'HTML基础',
      description: '学习HTML基础知识',
      lessons: [
        {
          lessonId: 'lesson-001',
          moduleId: 'module-001',
          title: 'HTML简介'
        },
        {
          lessonId: 'lesson-002',
          moduleId: 'module-001',
          title: 'HTML标签'
        }
      ]
    },
    {
      moduleId: 'module-002',
      courseId: 'course-001',
      title: 'CSS基础',
      description: '学习CSS基础知识',
      lessons: [
        {
          lessonId: 'lesson-003',
          moduleId: 'module-002',
          title: 'CSS选择器'
        }
      ]
    }
  ]
};

await reportCourseInfo(course);
```

### 报告学习进度

在Lesson层级报告进度，progress为0-100的百分比。progress = 100 表示该课时已完成。Host会自动计算上级（Module和Course）的进度：

```typescript
import { reportLearningProgress, LessonProgress } from '@qycreate/qy-learn-host-api-sdk';

// 报告单个课时的学习进度
const progress: LessonProgress = {
  courseId: 'course-001',
  moduleId: 'module-001',
  lessonId: 'lesson-001',
  progress: 75 // 0-100 百分比
};

await reportLearningProgress(progress);
```

### 检查Host API是否可用

```typescript
import { isHostAPIAvailable } from '@qycreate/qy-learn-host-api-sdk';

if (isHostAPIAvailable()) {
  // Host API可用，可以调用相关方法
} else {
  // Host API不可用
}
```

## API

### `getHostAPI(): HostAPI | null`

获取Host API实例。如果Host API不可用，返回null。

### `reportCourseInfo(course: Course): Promise<void>`

报告课程信息。接收完整的Course对象（包含所有Module和Lesson），用于初始化后端数据库。

### `reportLearningProgress(progress: LessonProgress): Promise<void>`

报告学习进度。接收单个Lesson的进度信息，progress为0-100的百分比。Host会自动计算上级（Module和Course）的进度。

### `isHostAPIAvailable(): boolean`

检查Host API是否可用。

## 类型定义

### `Course`

课程接口，包含完整的课程信息（所有模块和课时）：

```typescript
interface Course {
  courseId: string;
  title: string;
  description: string;
  version: string; // 课程版本号，用于Host判断课程是否有更新
  modules: Module[];
}
```

**version字段说明**：课程版本号，当课程信息有更新时，可以通过更新version字段来通知Host。Host可以根据version信息判断课程是否有更新。

### `Module`

模块接口，包含模块信息和该模块下的所有课时：

```typescript
interface Module {
  moduleId: string;
  courseId: string;
  title: string;
  description: string;
  lessons: Lesson[];
}
```

### `Lesson`

课时接口：

```typescript
interface Lesson {
  lessonId: string;
  moduleId: string;
  title: string;
}
```

### `LessonProgress`

学习进度接口，只在Lesson层级报告进度：

```typescript
interface LessonProgress {
  courseId: string;
  moduleId: string;
  lessonId: string;
  progress: number; // 0-100 百分比，progress = 100 表示已完成
}
```

## License

MIT