@plasosdk/client-sdk/README.md

Plaso教育平台的客户端SDK

# Plaso Client SDK

这是一个用于快速集成Plaso教育平台的SDK。通过简单的API调用，您可以轻松地在您的应用中嵌入Plaso的作业和课堂功能。该SDK内置了所有必要的依赖，无需额外安装React等库。

## 特点

- **完全独立**: SDK包含所有所需依赖，不需要外部引入React
- **简单集成**: 只需提供一个DOM容器元素即可渲染Plaso内容
- **多环境支持**: 支持Web应用和Electron应用
- **多种功能**: 支持作业、课堂等多种内容类型

## 安装

```bash
npm install @plasosdk/client-sdk
npm install @plasosdk/plaso-electron-sdk
npm install fluent-ffmpeg@2.1.3
npm install ffmpeg-static@5.2.0
```

## 在Electron项目中使用

在Electron项目中，您需要进行以下配置：

1. 在main.js中启用webview,初始化@plasosdk/client-sdk：
```javascript
const { app, BrowserWindow } = require('electron')
const remoteMain = require('@electron/remote/main');
const { init } = require('@plasosdk/client-sdk/electron');

remoteMain.initialize();
init(remoteMain); // 初始化Plaso Electron功能

function createWindow () {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: false,
      webviewTag: true,  // 启用webview标签
      webSecurity: false,
    }
  })
  remoteMain.enable(mainWindow.webContents);
}
```

2. 在渲染进程中使用：
```javascript
import { PlasoClient } from '@plasosdk/client-sdk';

const plasoClient = new PlasoClient({
  token: 'your-token-here',
  container: document.getElementById('plaso-container')
});

// 初始化作业模块
plasoClient.createAssignment();

// 初始化课堂模块
plasoClient.createClassroom();

```

## API 文档

### PlasoClient

#### 构造函数参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| token | string | 是 | Plaso平台的认证令牌 |
| container | HTMLElement | 是 | 用于渲染内容的DOM容器元素 |
| sdkVersion | string | 是 | SDK的版本号，用于标识当前使用的SDK版本 |
| platform | string | 否 | 平台标识，默认为'plaso'，用于区分不同的平台环境 |
| env | Environment | 否 | 环境配置，可选值：PROD（生产环境）、TEST（测试环境）等 |
| onError | (error: Error) => void | 否 | 错误处理回调函数 |
| onLoading | (isLoading: boolean) => void | 否 | 加载状态回调函数 |
| devTools | boolean | 否 | 是否打开开发者工具，默认为false |

#### 方法

##### createModule(module: PlasoContentType): Promise<void>
创建一个指定类型的模块。这是最通用的方法，可以用于创建任何支持的内容类型。

##### createAssignment(): Promise<void>
创建一个作业页面。内部调用`createModule(PlasoContentType.NHOMEWORK)`。

##### createClassroom(): Promise<void>
创建一个课堂页面。内部调用`createModule(PlasoContentType.LIVECLASS)`。

##### renderCustomContent(type: PlasoContentType): Promise<void>
渲染自定义内容，可以用于渲染其他类型的内容。内部调用`createModule(type)`。

##### destroy(): void
销毁客户端实例，清理资源。

### PlasoContentType

内容类型枚举，用于指定要渲染的内容类型。

```typescript
export enum PlasoContentType {
  NHOMEWORK = 'nhomework',
  LIVECLASS = 'liveclass',
  MAIN = 'main'
  // 后期可以在这里添加更多类型
}
```

### Electron API

SDK提供了专用的Electron模块，支持特定的Electron功能：

```typescript
// 从electron入口导入
import { init } from '@plasosdk/client-sdk/electron';

// 或使用require
const { init } = require('@plasosdk/client-sdk/electron');
```

#### 方法

##### init(remoteMain: any): void
初始化Electron相关功能，设置IPC通信以支持以下功能：
- 音频格式转换 (WAV到MP3)
- 系统进程获取
- 应用重启
- Electron远程模块支持

## 错误处理

SDK提供了完善的错误处理机制：

1. 错误回调：通过onError回调函数获取详细错误信息
2. 加载状态：通过onLoading回调函数监控加载状态
3. 错误展示：在UI中展示友好的错误提示

## 注意事项

1. 确保在使用前已经获取了有效的Plaso平台认证令牌
2. 容器元素必须具有明确的宽高设置
3. 所有异步操作都返回Promise，可以使用async/await处理
4. 在Electron环境中使用时，确保已正确配置webview支持

## 示例

```javascript
// 在任何JS文件或框架中使用
const { PlasoClient, PlasoContentType } = require('@plasosdk/client-sdk');
// 或使用ES模块语法
// import { PlasoClient, PlasoContentType } from '@plasosdk/client-sdk';

// 创建容器元素
const container = document.getElementById('plaso-container');
if (!container) {
  console.error('容器元素不存在');
  return;
}

// 设置容器样式
container.style.width = '100%';
container.style.height = '600px';

// 初始化客户端
const client = new PlasoClient({
  token: 'your-token-here',
  container: container,
  sdkVersion: '1.53.409', // 指定SDK版本
  platform: 'plaso',   // 指定平台
  onError: (error) => {
    console.error('Plaso error:', error);
    // 显示错误信息
    container.innerHTML = `<div style="color: red;">错误: ${error.message}</div>`;
  },
  onLoading: (loading) => {
    console.log('加载状态:', loading);
    // 可以显示加载指示器
  }
});

// 使用通用方法创建作业
client.createModule(PlasoContentType.NHOMEWORK)
  .catch(error => {
    console.error('创建作业失败:', error);
  });

// 使用前记得在不需要时销毁实例
// client.destroy();
```

## 变更日志

### 3.0.1
- 优化了SDK的独立性，确保用户不需要安装额外的React依赖
- 改进了文档，更清晰地说明SDK的使用方式

### 1.0.30
- 添加了专用的Electron模块，可通过`@plasosdk/client-sdk/electron`导入
- 实现了双入口打包，分离React客户端和Electron主进程功能
- 新增音频格式转换功能(WAV转MP3)
- 新增系统进程获取功能
- 优化了Electron远程模块的支持

### 1.0.12
- 修复了依赖安装问题

### 1.0.7
- 添加了统一的`createModule`方法，使用module作为入参
- 重构了现有方法，使它们调用新的`createModule`方法
- 更新了PlasoContentType枚举，使用更准确的类型名称
- 优化了API文档和示例代码

### 1.0.6
- 优化了webview支持检测，更准确地识别Electron环境
- 移除了加载中的提示UI，使界面更加简洁
- 保留了加载状态变量，以便在需要时仍然可以跟踪加载状态

### 1.0.5
- 添加了PlasoContentType枚举，支持更多内容类型
- 添加了renderCustomContent方法，支持渲染自定义内容
- 优化了错误提示，全部改为中文
- 使用React 18推荐的createRoot API
- 通过URL参数传递token，而不是使用localStorage

### 1.0.0
- 初始版本发布
- 支持作业和课堂功能
- 提供错误处理和加载状态回调

## 开发计划

- [ ] 支持自定义主题
- [ ] 添加更多交互事件回调
- [ ] 支持移动端适配
- [ ] 添加加载状态提示