# capability-socketio 模块

## 📋 模块说明

SocketIO 能力层模块，提供实时通信能力，可独立打包为 SDK。

## 🎯 功能特性

- ✅ Socket.IO 实时通信
- ✅ 自动重连机制
- ✅ Token 自动刷新
- ✅ 生命周期管理
- ✅ 事件订阅/发布
- ✅ 独立打包 SDK

## 📦 依赖

- `@xdz/base-core`: 基础设施层（ILog、StorageImpl）
- `@kit.NetworkKit`: HarmonyOS 网络工具包（WebSocket）
- `@kit.AbilityKit`: HarmonyOS Ability 工具包

## 🚀 使用方式

### 1. 初始化（在 AppInitializer 中）

```typescript
import { SocketIOManager } from '@xdz/capability-socketio';
import { AuthManager } from '@xdz/base-common';

// 1. 初始化 SocketIO 管理器
SocketIOManager.init(context);

// 2. 设置回调函数
SocketIOManager.isLoggedInProvider = () => {
  return AuthManager.getInstance().isLoggedIn();
};

SocketIOManager.refreshTokenProvider = async () => {
  const result = await AuthManager.getInstance().refreshToken();
  if (result.isSuccess) {
    return AuthManager.getInstance().getAccessToken();
  }
  return null;
};
```

### 2. 在 EntryAbility 中监听生命周期

```typescript
import { SocketIOManager } from '@xdz/capability-socketio';

async onForeground(): Promise<void> {
  await SocketIOManager.onForeground();
}

onBackground(): void {
  SocketIOManager.onBackground();
}
```

### 3. 业务代码中使用

```typescript
import { SocketIORepositoryFactory } from '@xdz/capability-socketio';

// 获取 Repository 实例
const repository = SocketIORepositoryFactory.getInstance();

// 连接服务器
await repository.connect(serverUrl, token);

// 观察连接状态
repository.connectionState.observe((isConnected) => {
  console.log('连接状态:', isConnected);
});

// 发送消息
await repository.sendVehicleControl('lock', vehicleId);

// 观察车辆报警
repository.vehicleAlarm.observe((alarm) => {
  if (alarm) {
    console.log('收到报警:', alarm.data);
  }
});
```

## 📁 模块结构

```
capability-socketio/
├── src/main/ets/socketio/
│   ├── api/              # API 接口
│   │   └── SocketIOService.ets
│   ├── factory/          # 工厂类
│   │   ├── SocketIOServiceFactory.ets
│   │   └── SocketIORepositoryFactory.ets
│   ├── impl/             # 实现类
│   │   └── SocketIOServiceImpl.ets
│   ├── manager/          # 管理器
│   │   └── SocketIOManager.ets
│   ├── model/            # 数据模型
│   │   ├── SocketIOEvent.ets
│   │   └── SocketIOResponse.ets
│   └── repository/       # 数据仓库
│       ├── SocketIORepository.ets
│       └── StateFlow.ets
├── oh-package.json5      # 依赖配置
├── module.json5         # 模块配置
└── index.ets            # 导出入口
```

## 🔧 独立打包 SDK

### 1. 配置模块为 HAR（HarmonyOS Archive）

模块已配置为 `type: "har"`，可以独立打包。

### 2. 打包步骤

```bash
# 在 DevEco Studio 中
# 1. 右键点击 capability-socketio 模块
# 2. 选择 "Build" -> "Make Module 'capability-socketio'"
# 3. 生成的 HAR 文件在 build/default/outputs/default/ 目录下
```

### 3. 使用打包的 SDK

```json5
// 在其他项目的 oh-package.json5 中
{
  "dependencies": {
    "@xdz/capability-socketio": "file:../path/to/capability-socketio.har"
  }
}
```

## 📝 API 文档

### SocketIORepository

- `connect(serverUrl?: string, token?: string)`: 连接服务器
- `disconnect()`: 断开连接
- `isConnected()`: 检查连接状态
- `checkAndReconnect(serverUrl?: string, token?: string)`: 检查并重连
- `sendVehicleControl(command: string, vehicleId: number)`: 发送车辆控制指令

### SocketIOManager

- `init(context: Context)`: 初始化管理器
- `onForeground()`: App 进入前台时调用
- `onBackground()`: App 进入后台时调用
- `isLoggedInProvider`: 登录状态检查回调
- `refreshTokenProvider`: Token 刷新回调

## ⚠️ 注意事项

1. **WebSocket 实现**: 当前使用 HarmonyOS WebSocket API，需要确保服务器支持 Socket.IO 协议
2. **Token 传递**: Token 通过 URL 参数传递（`?token=xxx`）
3. **生命周期**: 需要在 EntryAbility 中手动调用 `onForeground()` 和 `onBackground()`
4. **依赖方向**: capability-socketio 只依赖 base-core，不依赖 base-common

## 📄 许可证

MIT