@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();
// 初始化Plaso Electron功能，并获取事件发射器
const plasoEvents = init(remoteMain);

// 监听应用是否token过期
plasoEvents.on('relaunch', (args) => {
  // 可以做一些事情
});

```

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();

// 初始化资源模块 - 会打开新的资源页面
plasoClient.createResource();
```

## 事件系统

SDK提供了完整的事件系统，支持监听各种应用事件：

### 事件发射器

通过`init()`函数返回的事件发射器，您可以监听以下事件：

```javascript
const plasoEvents = init(remoteMain);

// 监听应用重启事件
plasoEvents.on('relaunch', (args) => {
  console.log('应用重启事件触发，参数:', args);
  // 执行重启逻辑
});

// 监听错误事件
plasoEvents.on('error', (error) => {
  console.error('SDK错误:', error);
  // 处理错误
});

// 监听资源模块创建事件
plasoEvents.on('module-created', (moduleInfo) => {
  console.log('资源模块已创建:', moduleInfo);
  // 处理模块创建后的逻辑
});
```

### 支持的事件类型

| 事件名 | 描述 | 参数 |
|--------|------|------|
| `relaunch` | 应用重启事件 | `args: any[]` - 重启参数 |
| `error` | 错误事件 | `error: Error` - 错误对象 |
| `module-created` | 资源模块创建事件 | `moduleInfo: object` - 模块信息 |
| `window-opened` | 新窗口打开事件 | `windowInfo: object` - 窗口信息 |

## 资源模块

SDK支持创建和管理各种资源模块，每个模块都有独立的功能和生命周期：

### 创建资源模块

```javascript
// 创建作业模块
await plasoClient.createModule(PlasoContentType.NHOMEWORK);

// 创建课堂模块
await plasoClient.createModule(PlasoContentType.LIVECLASS);

// 创建自定义模块
await plasoClient.createModule(PlasoContentType.MAIN);

// 创建资源模块 - 会打开一个新的页面
await plasoClient.createModule(PlasoContentType.RESOURCES);
```

### 模块生命周期管理

```javascript
// 创建模块
const module = await plasoClient.createModule(PlasoContentType.NHOMEWORK);

// 监听模块事件
plasoEvents.on('module-created', (moduleInfo) => {
  console.log('模块已创建:', moduleInfo.type, moduleInfo.id);
});

// 销毁模块
plasoClient.destroy();
```

### 资源模块类型

SDK支持以下资源模块类型：

- **NHOMEWORK**: 作业模块 - 用于显示和管理作业内容
- **LIVECLASS**: 课堂模块 - 用于在线课堂功能
- **MAIN**: 主模块 - 主页面内容
- **RESOURCES**: 资源模块 - 打开新的资源页面，用于资源管理和展示

## 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)`。

##### createResources(): Promise<void>
创建一个资源页面。内部调用`createModule(PlasoContentType.RESOURCES)`。这个模块会打开一个新的页面用于资源管理和展示。

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

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

### PlasoContentType

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

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

### 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): EventEmitter
初始化Electron相关功能，设置IPC通信以支持以下功能：
- 音频格式转换 (WAV到MP3)
- 系统进程获取
- 应用重启
- Electron远程模块支持
- 新窗口管理

**返回值**: 返回一个EventEmitter实例，用于监听各种事件。

**参数**:
- `remoteMain`: Electron远程模块的主进程实例

**使用示例**:
```javascript
const { app, BrowserWindow } = require('electron');
const remoteMain = require('@electron/remote/main');
const { init } = require('@plasosdk/client-sdk/electron');

remoteMain.initialize();

// 初始化并获取事件发射器
const plasoEvents = init(remoteMain);

// 监听应用重启事件
plasoEvents.on('relaunch', (args) => {
  console.log('应用重启事件触发，参数:', args);
  app.relaunch(args);
  app.exit();
});

// 监听错误事件
plasoEvents.on('error', (error) => {
  console.error('SDK错误:', error);
});

// 监听资源模块创建事件
plasoEvents.on('module-created', (moduleInfo) => {
  console.log('资源模块已创建:', moduleInfo);
});

// 监听新窗口打开事件
plasoEvents.on('window-opened', (windowInfo) => {
  console.log('新窗口已打开:', windowInfo);
});
```

#### 事件类型

| 事件名 | 描述 | 参数 | 触发时机 |
|--------|------|------|----------|
| `relaunch` | 应用重启事件 | `args: any[]` - 重启参数 | 当应用需要重启时 |
| `error` | 错误事件 | `error: Error` - 错误对象 | 当SDK发生错误时 |
| `module-created` | 资源模块创建事件 | `moduleInfo: object` - 模块信息 | 当资源模块创建完成时 |
| `window-opened` | 新窗口打开事件 | `windowInfo: object` - 窗口信息 | 当新窗口打开时 |

#### IPC通信接口

SDK还提供了以下IPC通信接口，可在渲染进程中使用：

```javascript
// 音频格式转换
const { ipcRenderer } = require('electron');
const result = await ipcRenderer.invoke('convert-audio', {
  inputPath: '/path/to/input.wav',
  outputPath: '/path/to/output.mp3'
});

// 获取系统进程
const processes = await ipcRenderer.invoke('getSystemProcess', 'win'); // 或 'mac'

// 打开新窗口
const windowInfo = await ipcRenderer.invoke('open-new-window', {
  url: 'https://example.com',
  width: 800,
  height: 600,
  frameless: false,
  modal: false,
  parentWindowId: parentWindow.id
});

// 存储操作
const value = await ipcRenderer.invoke('getStoreValue', 'key');
await ipcRenderer.invoke('setStoreValue', 'key', 'value');
```

## 错误处理

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.16
- 新增事件系统，支持监听应用重启、错误处理、资源模块创建等事件
- 新增资源模块管理功能，支持创建和管理各种类型的资源模块
- 新增RESOURCES资源模块类型，会打开新的资源管理页面
- 优化init函数返回值，现在返回EventEmitter实例用于事件监听
- 新增IPC通信接口文档，包括音频转换、系统进程获取、窗口管理等
- 完善事件类型文档，提供详细的事件参数和触发时机说明

### 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
- 初始版本发布
- 支持作业和课堂功能
- 提供错误处理和加载状态回调

## 开发计划

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