[English](./README.md) | 简体中文

> 智能设备模型（Smart Device Model）

## 安装

```sh
$ npm install @ray-js/panel-sdk
# or
$ yarn add @ray-js/panel-sdk
# or
$ pnpm add @ray-js/panel-sdk
```

## 使用

```typescript
import { SmartDeviceModel } from '@ray-js/panel-sdk';

// SmartDevices 定义来自于 typings/sdm.d.ts，非 Typescript 开发者可忽略
export const devices = {} as SmartDevices;

SmartDeviceModel.init<SmartDeviceSchema>().then(device => {
  /**
   * 此处建议以智能设备的名称作为键名赋值
   */
  devices.robot = device;
});

devices.robot.model.actions.power.toggle();
```

## Ray / React 项目

```tsx
// src/app.tsx
import React from 'react';
import 'ray';
import '@/i18n';
import { kit, SdmProvider } from '@ray-js/panel-sdk';
import { devices } from '@/devices';

const { initPanelEnvironment } = kit;

interface Props {
  children: React.ReactNode;
}

initPanelEnvironment({ useDefaultOffline: true });

export default class App extends React.Component<Props> {
  onLaunch() {
    console.info('=== App onLaunch');
  }

  render() {
    return <SdmProvider value={devices.robot}>{this.props.children}</SdmProvider>;
  }
}
```

```tsx
// src/pages/home/index.tsx
import React from 'react';
import { Button, View } from '@ray-js/components';
import { devices } from '@/devices';

export default function Home() {
  const device = devices.robot;
  return (
    <View>
      <Button onClick={() => device.model.actions.power.toggle()}>点击我切换设备开关状态</Button>
    </View>
  );
}
```

## 多设备管理

### SmartDevicesManager

用于统一管理多个设备实例，提供批量初始化、事件路由、全局状态缓存等能力。

```typescript
import { SmartDevicesManager, SdmProvider } from '@ray-js/panel-sdk';

const deviceManager = new SmartDevicesManager();

// 添加单个设备（支持 interceptors 配置）
await deviceManager.add({
  key: 'lamp',
  deviceId: 'lamp001',
  interceptors: lampKit.interceptors,  // 可选：协议转换器
  logConfig: { level: 'debug' },       // 可选：日志配置
});

// 批量添加设备（⚠️ 返回值变更）
const result = await deviceManager.batchAdd([
  { key: 'lamp1', deviceId: 'lamp001' },
  { key: 'lamp2', deviceId: 'lamp002', interceptors: lampKit.interceptors },
], { concurrency: 5 });

// 处理结果
console.log('成功:', Object.keys(result.success));  // ['lamp1', 'lamp2']
console.log('失败:', result.failed);                 // []

// 在 SdmProvider 中使用
<SdmProvider 
  value={mainDevice}
  deviceManager={deviceManager}
  isNeedMainDeviceInitialized={true}
  isNeedAllDevicesInitialized={false}
>
  {children}
</SdmProvider>
```

### 新增类型

```typescript
type BatchAddResult = {
  success: Record<string, SmartDeviceModel<any>>;
  failed: Array<{
    key: string;
    deviceId: string;
    error: Error;
  }>;
};
```

### 性能优化

- **批量获取优化**：`batchAdd()` 内部使用 `getDeviceListByDevIds` 批量获取设备信息
- **全局状态缓存**：网络状态和蓝牙状态在 Manager 层面懒加载并缓存，避免重复调用
- **事件路由优化**：Manager 统一注册全局事件监听器，通过 O(1) 映射路由到具体设备

### 更多信息

- [多设备设计文档](../../../../docs/sdm-multi-device-design.md)
- [页面事件集成最佳实践](./docs/page-event-integration.md)
- [Demo 示例](../../../../apps/sdm/src/pages/multi-device/)