# distributed-manager

**Repository Path**: Fie_Ryan/distributed-manager

## Basic Information

- **Project Name**: distributed-manager
- **Description**: HarmonyOS 分布式设备管理工具库，提供设备发现、连接、数据同步等核心能力，基于 HarmonyOS 分布式服务框架封装，支持多设备协同场景下的设备管理、数据互通与业务协同。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: HarmonyOS, 分布式软总线, 跨设备协同, 分布式数据, 多设备管理

## README

# Distributed Manager 分布式设备管理工具库

HarmonyOS 分布式设备管理工具库，提供设备发现、连接、数据同步等核心能力，基于 HarmonyOS 分布式服务框架封装，支持多设备协同场景下的设备管理、数据互通与业务协同。

## 特性

- **设备管理**：设备扫描、绑定、解绑、设备信息查询
- **设备连接**：会话创建、数据传输、连接状态监控
- **KV 数据存储**：分布式键值型数据库操作与同步
- **关系型数据库**：分布式 SQL 数据库 CRUD 操作与数据同步
- **分布式数据对象**：跨设备数据对象同步与资源管理
- **统一日志**：支持开发/生产模式切换的日志工具

## 模块概览

| 模块            | 类名                             | 核心功能                | 文件路径                                                    | 依赖服务                       |
|---------------|--------------------------------|---------------------|---------------------------------------------------------|----------------------------|
| **设备管理**      | `DeviceManager`                | 设备发现、绑定、解绑、设备信息查询   | `src/main/ets/manager/DeviceManager.ets`                | `distributedDeviceManager` |
| **设备连接**      | `DeviceConnectionManager`      | 会话创建、连接管理、数据传输      | `src/main/ets/manager/DeviceConnectionManager.ets`      | `abilityConnectionManager` |
| **KV 数据**     | `KVDataManager`                | 键值型数据库读写与分布式同步      | `src/main/ets/manager/KVDataManager.ets`                | `distributedKVStore`       |
| **关系型数据库**    | `RDBManager`                   | SQL 数据库 CRUD 与分布式同步 | `src/main/ets/manager/RDBManager.ets`                   | `relationalStore`          |
| **分布式数据对象**   | `DistributedDataObjectManager` | 跨设备数据对象同步与资源管理      | `src/main/ets/manager/DistributedDataObjectManager.ets` | `distributedDataObject`    |
| **日志工具**      | `Logger`                       | 支持模式切换的日志输出         | `src/main/ets/utils/Logger.ets`                         | `hilog`                    |
| **Bundle 工具** | `BundleManagerUtils`           | 获取应用 BundleInfo 信息  | `src/main/ets/utils/BundleManagerUtils.ets`             | `bundleManager`            |
| **常量定义**      | `Constants`                    | 默认配置常量              | `src/main/ets/constants/Constants.ets`                  | -                          |

---

## 安装

```bash
ohpm install @ryan/distributed-manager
```

## 引入

```typescript
import {
  DeviceManager,
  DeviceConnectionManager,
  KVDataManager,
  RDBManager,
  DistributedDataObjectManager,
  Logger,
  BundleManagerUtils
} from '@ryan/distributed-manager'
```

---

## 权限配置

在 `module.json5` 中配置分布式相关权限：

```json
{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.DISTRIBUTED_DATASYNC",
        "reason": "$string:distributed_sync_reason",
        "usedScene": {
          "abilities": [
            "MainAbility"
          ],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.GET_DISTRIBUTED_DEVICE_INFO",
        "reason": "$string:get_device_info_reason",
        "usedScene": {
          "abilities": [
            "MainAbility"
          ],
          "when": "always"
        }
      }
    ]
  }
}
```

**权限说明**：

| 权限                            | 用途        | 授权方式  |
|-------------------------------|-----------|-------|
| `DISTRIBUTED_DATASYNC`        | 分布式数据同步   | 运行时授权 |
| `GET_DISTRIBUTED_DEVICE_INFO` | 获取分布式设备信息 | 运行时授权 |

---

## DeviceManager

设备管理模块，负责设备发现、绑定、解绑及设备信息查询。

### 核心实现原理

`DeviceManager` 内部封装了 HarmonyOS 的 `distributedDeviceManager`，通过以下步骤实现设备管理：

1. **创建设备管理器**：调用 `distributedDeviceManager.createDeviceManager(bundleName)` 创建底层管理器实例
2. **注册状态监听**：监听 `deviceStateChange`、`discoverSuccess`、`discoverFailure` 等事件
3. **维护设备列表**：内部维护 `devices`（所有发现设备）和 `trustedDeviceList`（可信设备）两个数组
4. **状态管理**：通过 `currentDeviceState` 枚举跟踪当前设备状态

### 初始化

```typescript
const listener: DeviceManagerListener<null> = {
  inited: () => console.log('设备管理器初始化完成'),
  success: (device) => console.log('发现设备:', device.deviceName),
  failure: (reason) => console.error('发现设备失败:', reason),
  available: (device) => console.log('设备上线:', device.deviceId),
  unavailable: (device) => console.log('设备离线:', device.deviceId),
  unknown: (device) => console.log('设备状态未知:', device.deviceId),
  change: (action, device) => console.log('设备状态变化:', action, device),
  deviceNameChange: (prev, now) => console.log('设备名称变化:', prev, '->', now),
  serviceDie: () => console.log('设备管理器服务崩溃'),
  error: (err) => console.error('设备管理错误:', err)
}
DeviceManager.initDeviceManager(getContext(this), { listener: this.listener })
```

**参数说明**：

| 参数           | 类型                      | 必填 | 说明                                             |
|--------------|-------------------------|----|------------------------------------------------|
| `context`    | `common.Context`        | 是  | 应用或组件上下文                                       |
| `bundleName` | `string`                | 否  | 应用的 bundleName，不传则自动通过 `BundleManagerUtils` 获取 |
| `listener`   | `DeviceManagerListener` | 否  | 事件监听器对象                                        |

### 设备扫描

```typescript
// 开启扫描（带超时时间）
const discoverParam: Record<string, number> = {
  // 发现同局域网或开启蓝牙的设备
  'discoverTargetType': 1
}
const filterOptions: Record<string, number> = {
  // 设备可用状态，0表示仅发现可用设备
  'availableStatus': 0
}
// discoveTime: 发现超时时间（秒），默认120秒，超时后自动停止
const flag: boolean = DeviceManager.startDiscovering(discoverParam, filterOptions, 60)

// 简化调用（使用默认参数）
const flag: boolean = DeviceManager.startDiscovering()

// 停止扫描
const flag: boolean = DeviceManager.stopDeviceDiscovery()
```

**参数说明**：

| 参数              | 类型                       | 必填 | 说明                                   |
|-----------------|--------------------------|----|--------------------------------------|
| `discoverParam` | `Record<string, number>` | 否  | 扫描模式参数，默认 `{ discoverTargetType: 1 }` |
| `filterOptions` | `Record<string, number>` | 否  | 过滤选项，为空或不传时不启用过滤                  |
| `discoveTime`   | `number`                 | 否  | 发现超时时间（秒），默认120秒，到时自动停止扫描         |

**返回值**：`boolean` - 操作是否成功

### 设备绑定与解绑

```typescript
// 绑定设备（bindParams 可空，会自动构建默认参数）
const options: BindTargerDevice = {
  device: device,
  bindParams: {
    'bindType': 1,
    'targetPkgName': 'com.example.app',
    'appName': '设备协同示例',
    'appOperation': '设备绑定',
    'customDescription': '设备绑定操作'
  },
  cb: (deviceId: string) => {
    console.log(`绑定成功, deviceId: ${deviceId}`);
  }
}
// bindParams 为空时自动构建默认参数
const optionsAuto: BindTargerDevice = {
  device: device,
  cb: (deviceId: string) => {
    console.log(`绑定成功, deviceId: ${deviceId}`);
  }
}
DeviceManager.bindDevice(options).then(() => {
  console.log('绑定流程完成');
})

// 解绑设备
const options: BaseTargetDeviceParams = {
  device: device,
  cb: (deviceId: string) => {
    console.log(`解绑成功, deviceId: ${deviceId}`);
  }
}
DeviceManager.unBindDevice(options)
```

**绑定流程**：

1. 调用 `DeviceManager.bindTarget(deviceId, bindParams, callback)`
2. 若 `bindParams` 为空，自动从 `BundleManagerUtils` 获取应用信息构建默认参数
3. 等待回调确认绑定结果
4. 更新可信设备列表

**参数说明**：

| 参数           | 类型                           | 必填 | 说明                                             |
|--------------|------------------------------|----|------------------------------------------------|
| `device`     | `DeviceBasicInfo`            | 是  | 目标设备信息，包含 `deviceId`、`deviceName`、`deviceType` |
| `bindParams` | `Record<string, ESObject>`  | 否  | 绑定参数，自动构建默认参数（包含 bindType、targetPkgName、appName、appOperation、customDescription） |
| `cb`         | `(deviceId: string) => void` | 否  | 操作完成回调                                         |

### 设备信息查询

```typescript
// 获取可信设备列表（已组网设备）
const trustedDevices = DeviceManager.getTrustedDevices()

// 获取发现的设备列表
const allDevices = DeviceManager.getDeviceList()

// 获取本地设备完整信息
const localDevice = DeviceManager.getLocalDevice()
// 返回: { networkId, deviceName, deviceType, deviceId }

// 根据 networkId 获取设备信息
const device = DeviceManager.getDeviceByNetworkId(networkId)

// 获取本地设备 ID
const deviceId = DeviceManager.getLocalDeviceId()

// 获取当前设备状态
const state = DeviceManager.getCurrentDeviceState()
// 返回: DeviceState.unknown | DeviceState.available | DeviceState.unavailable
```

**返回值说明**：

| 方法                        | 返回类型                     | 说明                   |
|---------------------------|--------------------------|----------------------|
| `getTrustedDevices()`     | `Array<DeviceBasicInfo>` | 可信设备列表，调用底层 API 实时获取 |
| `getDeviceList()`         | `Array<DeviceBasicInfo>` | 所有设备列表，内部维护的数组       |
| `getLocalDevice()`        | `DeviceInfos \| null`    | 本地设备信息对象             |
| `getDeviceByNetworkId()`  | `DeviceInfos \| null`    | 指定网络设备信息             |
| `getLocalDeviceId()`      | `string`                 | 本地设备 ID              |
| `getCurrentDeviceState()` | `DeviceState`            | 当前设备状态枚举             |

### 资源释放

```typescript
DeviceManager.releaseDeviceManager()
```

**释放流程**：

1. 停止设备发现：`deviceManager.stopDiscovering()`
2. 解绑所有事件监听：`off("deviceStateChange")`、`off("discoverSuccess")` 等
3. 释放底层管理器：`distributedDeviceManager.releaseDeviceManager()`
4. 重置内部状态：清空设备列表、重置状态枚举

---

## DeviceConnectionManager

设备连接管理模块，负责会话创建、连接管理、数据传输。内部会自动初始化 `DeviceManager`，无需重复初始化。

### 核心实现原理

`DeviceConnectionManager` 基于 `abilityConnectionManager` 实现跨设备能力连接：

1. **自动初始化 DeviceManager**：确保设备管理器已就绪
2. **创建会话**：调用 `createAbilityConnectionSession()` 获取会话 ID
3. **建立连接**：通过 `connect(sessionId)` 建立设备间连接
4. **数据传输**：支持文本消息（`sendMessage`）和字节流（`sendData`）
5. **状态跟踪**：通过 `currentconnectionState` 维护连接状态

### 初始化

```typescript
DeviceConnectionManager.initDeviceConnectionManager(context, {
  bundleName: 'com.example.app',
  listener: {
    inited: () => console.log('连接管理器初始化完成'),
    connect: (info) => console.log('设备已连接:', info),
    disconnect: (info) => console.log('设备已断开:', info),
    receiveMessage: (info) => console.log('收到文本消息:', info),
    receiveData: (info) => console.log('收到字节数据:', info),
    error: (err) => console.error('连接错误:', err),
    release: () => console.log('连接资源已释放')
  }
})
```

### 创建连接会话

```typescript
const sessionId = await DeviceConnectionManager.createConnectionSession({
  deviceId: 'remote_device_id', // 目标设备 ID
  serviceName: 'my_collaboration_service', // 服务名称（可选）
  parameters: { key: 'value' }, // 传输参数（可选）
  peerInfo: {
    // 对等应用信息（可选）
    bundleName: 'com.example.app',
    moduleName: 'entry',
    abilityName: 'MainAbility'
  },
  connectOption: {
    // 连接选项（可选）
    needSendData: true,
    startOptions: 0
  }
})
```

**创建流程**：

1. 构建 `PeerInfo`：包含目标设备 ID、bundleName、moduleName、abilityName
2. 构建 `ConnectOptions`：配置是否需要发送数据、启动选项、参数
3. 调用 `createAbilityConnectionSession()` 创建会话
4. 注册事件监听（connect、disconnect、receiveMessage、receiveData）
5. 自动调用 `connect()` 建立连接

**参数说明**：

| 参数              | 类型                       | 必填 | 说明                                  |
|-----------------|--------------------------|----|-------------------------------------|
| `deviceId`      | `string`                 | 是  | 目标设备的 deviceId                      |
| `serviceName`   | `string`                 | 否  | 服务名称，默认 `device_connection_manager` |
| `parameters`    | `Record<string, string>` | 否  | 传递给目标设备的参数                          |
| `peerInfo`      | `PeerInfo`               | 否  | 目标设备的应用信息，不传则自动获取当前应用信息             |
| `connectOption` | `ConnectOptions`         | 否  | 连接配置选项                              |

**返回值**：`number` - 会话 ID

### 连接控制

```typescript
// 接受来自发起端的连接请求（sink 端使用）
const acceptResult = await DeviceConnectionManager.acceptConnect(sessionId, token)
// 返回: { success: boolean, data?: Record<string, ESObject>, error?: BusinessError }

// 连接设备（createConnectionSession 会自动调用此方法）
const connectResult = await DeviceConnectionManager.connection(sessionId)
// 返回: { success: boolean, data?: boolean, error?: BusinessError }

// 断开连接（保留会话，可重连）
const disconnectResult = DeviceConnectionManager.disConnection(sessionId)
// 返回: { success: boolean, data?: boolean, error?: BusinessError }

// 释放连接资源（销毁会话）
const released = DeviceConnectionManager.releaseDeviceConnectionManager()
```

**返回值说明**：

| 方法              | 返回类型                              | 说明                    |
|-----------------|-----------------------------------|-----------------------|
| `acceptConnect` | `Promise<FunctionResult<Record<string, ESObject>>>` | 接受连接请求            |
| `connection`    | `Promise<FunctionResult<boolean>>`                | 建立连接                |
| `disConnection` | `FunctionResult<boolean>`                        | 断开连接                |
| `releaseDeviceConnectionManager` | `boolean`           | 释放资源                |

**连接状态转换**：

```
disconnect ──connection()──▶ connect ──disConnection()──▶ disconnect
                              │                        │
                              └──release()─────────────┘
```

### 数据传输

```typescript
// 发送文本消息
const messageSent = await DeviceConnectionManager.sendMessage('Hello, HarmonyOS!')

// 发送字节流数据
const buffer = new ArrayBuffer(1024)
const view = new Uint8Array(buffer)
view[0] = 0x01
const dataSent = await DeviceConnectionManager.sendData(buffer)
```

**传输协议**：

| 方法            | 数据类型          | 适用场景         |
|---------------|---------------|--------------|
| `sendMessage` | `string`      | 文本消息、JSON 数据 |
| `sendData`    | `ArrayBuffer` | 二进制数据、文件传输   |

**返回值**：`Promise<boolean>` - 是否发送成功

### 状态查询

```typescript
// 获取连接状态
const state = DeviceConnectionManager.getConnectionState()
// 返回: DeviceConnectionState.disconnect | DeviceConnectionState.connect

// 获取当前会话 ID
const id = DeviceConnectionManager.getSessionId()

// 获取当前服务名称
const name = DeviceConnectionManager.getServiceName()
```

---

## KVDataManager

键值型数据管理模块，基于 HarmonyOS `distributedKVStore` 封装，支持分布式数据同步。

### 核心实现原理

`KVDataManager` 封装了两层 API：

1. **KVManager 层**：管理 KV 数据库的生命周期，监听 `distributedDataServiceDie` 事件
2. **KVStore 层**：具体的数据读写操作，监听 `dataChange` 和 `syncComplete` 事件

**存储类型**：默认使用 `DEVICE_COLLABORATION`（设备协同分布式库），支持多设备数据互通。

### 初始化

```typescript
import distributedKVStore from '@ohos.data.distributedKVStore'

KVDataManager.initKVDataManager(context, {
  bundleName: 'com.example.app',
  storeId: 'my_kv_store', // 数据库 ID
  securityLevel: distributedKVStore.SecurityLevel.S1,
  storeOptions: {
    createIfMissing: true, // 不存在时自动创建
    encrypt: false, // 是否加密
    backup: true, // 是否自动备份
    autoSync: false, // 是否自动同步
    kvStoreType: distributedKVStore.KVStoreType.DEVICE_COLLABORATION
  },
  listener: {
    inited: () => console.log('KV 数据管理器初始化完成'),
    dataChange: (data) => console.log('数据变化:', data),
    syncComplete: (data) => console.log('同步完成:', data),
    distributedDataServiceDie: () => console.log('数据服务终止'),
    error: (err) => console.error('KV 管理错误:', err),
    release: () => console.log('KV 资源已释放')
  }
})
```

**安全等级说明**：

| 等级   | 说明            | 适用场景  |
|------|---------------|-------|
| `S1` | 普通安全等级，明文存储   | 非敏感数据 |
| `S2` | 低安全等级，普通非敏感数据 | 默认值   |
| `S3` | 中安全等级，需要加密存储  | 敏感数据  |
| `S4` | 高安全等级，强加密存储   | 机密数据  |

**参数说明**：

| 参数              | 类型                      | 必填 | 说明                        |
|-----------------|-------------------------|----|---------------------------|
| `bundleName`    | `string`                | 否  | 应用 bundleName             |
| `storeId`       | `string`                | 否  | 数据库 ID，默认 `kv_store_data` |
| `securityLevel` | `SecurityLevel`         | 否  | 安全等级，优先级高于 `storeOptions` |
| `storeOptions`  | `Options`               | 否  | 数据库配置选项                   |
| `listener`      | `KVDataManagerListener` | 否  | 事件监听器                     |

### 数据操作

```typescript
// 写入数据
const putResult = await KVDataManager.putData('user_1', {
  name: '张三',
  age: 25,
  email: 'zhangsan@example.com'
})
// 返回: { success: boolean, data?: boolean, error?: BusinessError }

// 读取数据
const getResult = await KVDataManager.getData('user_1')
// 返回: { success: boolean, data?: boolean | string | number | Uint8Array | undefined | null, error?: BusinessError }

// 判断操作是否成功
if (putResult.success) {
  console.log('写入成功')
} else {
  console.error('写入失败:', putResult.error?.message)
}

if (getResult.success) {
  console.log('读取成功:', getResult.data)
} else {
  console.error('读取失败:', getResult.error?.message)
}
```

**支持的数据类型**：

| 类型           | 说明    | 示例                          |
|--------------|-------|-----------------------------|
| `boolean`    | 布尔值   | `true`, `false`             |
| `string`     | 字符串   | `'hello'`                   |
| `number`     | 数字    | `123`, `3.14`               |
| `Uint8Array` | 二进制数据 | `new Uint8Array([1, 2, 3])` |
| `ESObject`   | 对象    | `{ name: '张三' }`            |

**返回值说明**：

| 方法          | 返回类型                                                                      | 说明     |
|-------------|---------------------------------------------------------------------------|--------|
| `putData()` | `Promise<FunctionResult<boolean>>`                                        | 包含 success、data、error 字段 |
| `getData()` | `Promise<FunctionResult<boolean \| string \| number \| Uint8Array \| undefined \| null>>` | 包含 success、data、error 字段 |

### 数据同步

```typescript
// 同步数据到指定设备（双向同步）
const deviceIds = ['device_1', 'device_2']
const syncSuccess = await KVDataManager.syncData(deviceIds, undefined, 1000)

// 带查询条件的同步
const query = distributedKVStore.createQuery()
query.equalTo('type', 'user')
const filteredSync = await KVDataManager.syncData(deviceIds, query, 1000)
```

**参数说明**：

| 参数             | 类型              | 必填 | 说明               |
|----------------|-----------------|----|------------------|
| `deviceIds`    | `Array<string>` | 是  | 目标设备 ID 列表       |
| `query`        | `Query`         | 否  | 查询条件，不传则同步全部数据   |
| `milliseconds` | `number`        | 否  | 同步超时时间，默认 1000ms |

### 资源释放

```typescript
KVDataManager.releaseKVDataManager()
```

**释放流程**：

1. 解绑 KVManager 监听：`off("distributedDataServiceDie")`
2. 解绑 KVStore 监听：`off("dataChange")`、`off("syncComplete")`
3. 重置内部状态：清空实例引用、恢复默认 storeId

---

## RDBManager

关系型数据库管理模块，基于 HarmonyOS `relationalStore` 封装，支持分布式 SQL 数据库操作和数据同步。

### 核心实现原理

`RDBManager` 提供完整的关系型数据库操作：

1. **数据库初始化**：通过 `getRdbStore()` 获取数据库实例
2. **表创建**：执行 SQL 创建表，并通过 `setDistributedTables()` 设置分布式表
3. **数据操作**：封装 insert、query、update、delete 操作
4. **分布式查询**：支持 `remoteQuery()` 查询远端设备数据
5. **数据同步**：提供多种同步策略（云端优先、本地优先、时间优先）

### 初始化

```typescript
import relationalStore from '@ohos.data.relationalStore'
import { InitRDBManagerOptions, RelationalStore } from "../type/RDBManager.type";

const options: InitRDBManagerOptions = {
  tableName: ['users', 'orders'],
  createTable: [
    'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, createTime TEXT)',
    'CREATE TABLE IF NOT EXISTS orders (id INTEGER PRIMARY KEY AUTOINCREMENT, userId INTEGER, amount INTEGER, status INTEGER)'
  ],
  columns: ['id', 'name', 'age', 'createTime'],
  config: {
    name: 'my_app.db',
    securityLevel: relationalStore.SecurityLevel.S1,
    encrypt: false,
    allowRebuild: false,
    persist: true
  },
  listener: {
    inited: (data?: RelationalStore.RdbStore) => console.log('RDB 管理器初始化完成' + JSON.stringify(data)),
    createTable: (tables) => console.log('表创建成功:', tables),
    dataChange: (devices) => console.log('数据变化:', devices),
    autoSyncProgress: (progress) => console.log('同步进度:', progress),
    statistics: (info) => console.log('SQL 统计:', info),
    perfStat: (info) => console.log('性能统计:', info),
    syncData: (results) => console.log('同步结果:', results),
    error: (err) => console.error('RDB 管理错误:', err),
    release: () => console.log('RDB 资源已释放')
  }
}
RDBManager.initRDBManager<RelationalStore.RdbStore>(context, options)
```

**配置项说明**：

| 配置项             | 类型              | 默认值          | 说明        |
|-----------------|-----------------|--------------|-----------|
| `name`          | `string`        | `default.db` | 数据库文件名    |
| `securityLevel` | `SecurityLevel` | `S1`         | 安全等级      |
| `encrypt`       | `boolean`       | `false`      | 是否加密      |
| `allowRebuild`  | `boolean`       | `false`      | 损坏时是否自动重建 |
| `persist`       | `boolean`       | `true`       | 是否持久化     |

**参数说明**：

| 参数            | 类型                   | 必填 | 说明            |
|---------------|----------------------|----|---------------|
| `tableName`   | `Array<string>`      | 是  | 数据库表名列表       |
| `createTable` | `Array<string>`      | 是  | 创建表的 SQL 语句列表 |
| `columns`     | `Array<string>`      | 是  | 默认查询列名        |
| `config`      | `StoreConfig`        | 否  | 数据库配置         |
| `listener`    | `RDBManagerListener` | 否  | 事件监听器         |

### 数据操作

```typescript
// 插入数据
const user = { name: '张三', age: 25, createTime: new Date().toISOString() }
const inserted = await RDBManager.insertData('users', user)

// 查询数据
const users = await RDBManager.queryData('users', ['id', 'name', 'age'])

// 带条件查询
const predicates = new relationalStore.RdbPredicates('users')
predicates.equalTo('age', 25).orderByDesc('createTime')
const filteredUsers = await RDBManager.queryData('users', ['id', 'name'], predicates)

// 更新数据
const updatedUser = { id: 1, name: '李四', age: 26 }
const updated = await RDBManager.updateData('users', updatedUser, 'id')

// 删除数据（支持多种格式）
const deleted1 = await RDBManager.deleteData('users', [1, 2, 3]) // 数组 ID
const deleted2 = await RDBManager.deleteData('users', [{ id: 1 }, { id: 2 }]) // 对象数组
const deleted3 = await RDBManager.deleteData('users', [1, 2], 'userId') // 指定字段
```

**Predicates 查询条件示例**：

```typescript
const predicates = new relationalStore.RdbPredicates('users')
  .equalTo('age', 25)           // 等于
  .notEqualTo('name', '张三')   // 不等于
  .greaterThan('age', 18)       // 大于
  .lessThanOrEqualTo('age', 60) // 小于等于
  .orderByDesc('createTime')    // 降序排序
  .limit(10) // 限制数量
```

**参数说明**：

| 方法           | 参数                                                                      | 说明             |
|--------------|-------------------------------------------------------------------------|----------------|
| `insertData` | `tableName: string, data: T`                                            | 插入单条数据         |
| `queryData`  | `tableName: string, columns: Array<string>, predicates?: RdbPredicates` | 查询数据           |
| `updateData` | `tableName: string, data: T, equalKey?: string`                         | 更新数据，默认按 id 匹配 |
| `deleteData` | `tableName: string, datas: Array<ESObject>, equalKey?: string`          | 删除数据，默认按 id 匹配 |

### 远程查询

```typescript
// 查询远端设备上的数据
const remoteUsers = await rdbManager.remoteQuery(
  deviceInfo, // 目标设备信息（需包含 networkId）
  'users', // 表名
  ['id', 'name', 'age'], // 查询列
  predicates                   // 查询条件（可选）
)
```

**远程查询原理**：通过 `deviceInfo.networkId` 定位目标设备，直接查询该设备上的分布式表数据，无需先同步到本地。

### 数据同步

```typescript
// 云端优先同步（强制拉取覆盖本地）
const cloudSynced = await RDBManager.cloudFirstSync('users')

// 本地优先同步（强制推送覆盖云端）
const nativeSynced = await RDBManager.nativeFirstCloudSync('users')

// 时间优先双向同步（根据修改时间决定优先级）
const timeSynced = await RDBManager.syncByModifyTime('users')

// 从远端设备拉取数据到本地
const pulled = await RDBManager.pullRemoteData('users')

// 推送本地数据到远端设备
const pushed = await RDBManager.pushRemoteData('users')

// 手动指定同步模式
const result = await RDBManager.syncDistributedData(
  'users',
  relationalStore.SyncMode.SYNC_MODE_PUSH
)
```

**同步模式说明**：

| 模式                       | 说明              | 适用场景      |
|--------------------------|-----------------|-----------|
| `SYNC_MODE_CLOUD_FIRST`  | 云端数据优先，强制拉取覆盖本地 | 需要保持与云端一致 |
| `SYNC_MODE_NATIVE_FIRST` | 本地数据优先，强制推送覆盖云端 | 本地数据更权威   |
| `SYNC_MODE_TIME_FIRST`   | 时间优先，根据修改时间双向同步 | 多设备协同编辑   |
| `SYNC_MODE_PULL`         | 从远端设备拉取数据到本地    | 只读场景      |
| `SYNC_MODE_PUSH`         | 推送本地数据到远端设备     | 只写场景      |

**同步结果格式**：`Array<[string, number]>` - `[设备ID, 同步状态]`，状态值 `1` 表示成功，`0` 表示失败。

### 分布式表名

```typescript
// 获取指定设备对应的分布式表名
const tableName = await RDBManager.getDistributedTableNameByDevice(
  deviceId,
  'users'
)
// 返回: "deviceId_users"（带设备ID前缀的表名）
```

### 资源释放

```typescript
RDBManager.releaseRDBManager()
```

**释放流程**：

1. 解绑所有事件监听：`dataChange`、`autoSyncProgress`、`statistics`、`perfStat`、`sqliteErrorOccurred`
2. 重置内部状态：清空 rdbStore 引用、恢复默认配置

---

## DistributedDataObjectManager

分布式数据对象管理模块，基于 HarmonyOS `distributedDataObject` 封装，支持跨设备数据对象同步与资源管理。

### 核心实现原理

`DistributedDataObjectManager` 用于管理跨设备共享的数据对象：

1. **创建数据对象**：调用 `distributedDataObject.create(context, source)` 创建
2. **资源管理**：支持设置单个或多个资源（Asset）
3. **数据库绑定**：可将资源与关系型数据库绑定
4. **会话管理**：通过 sessionId 管理多设备协同会话
5. **数据同步**：自动同步数据对象变更到所有会话成员

### 初始化

```typescript
DistributedDataObjectManager.initDistributedDataObjectManager(context, {
  source: {
    title: '',
    content: '',
    timestamp: 0,
    images: []
  },
  listener: {
    inited: (obj) => console.log('分布式对象初始化完成', obj),
    dataChange: (sessionId, fields) => console.log('数据变化:', sessionId, fields),
    stateChange: (sessionId, networkId, status) => console.log('状态变化:', sessionId, networkId, status),
    sessionIdChange: (sessionId) => console.log('会话ID变化:', sessionId),
    error: (err) => console.error('数据对象错误:', err),
    release: () => console.log('分布式对象资源已释放')
  }
})
```

**source 对象说明**：作为分布式数据对象的初始数据模板，定义了对象的结构和初始值。

### 资源操作

```typescript
// 设置单个资源
const assetSet = await DistributedDataObjectManager.setAssetData('image', '/path/to/image.png')

// 设置多个资源
const assetsSet = await DistributedDataObjectManager.setAssetsData('images', [
  '/path/to/image1.png',
  '/path/to/image2.png'
])

// 绑定资源与数据库
const bindInfo = {
  storeName: 'my_app.db',
  tableName: 'images',
  primaryKey: 'id',
  columnName: 'assetColumn',
  assetName: 'my_asset'
}
const bound = await DistributedDataObjectManager.bindAssetStoreData('image', bindInfo)
```

**BindInfo 参数说明**：

| 参数           | 类型       | 说明    |
|--------------|----------|-------|
| `storeName`  | `string` | 数据库名称 |
| `tableName`  | `string` | 表名    |
| `primaryKey` | `string` | 主键字段名 |
| `columnName` | `string` | 资产列名  |
| `assetName`  | `string` | 资产名称  |

### 数据保存与撤回

```typescript
// 保存数据到本地设备
const saveResult = await DistributedDataObjectManager.saveData('local')

// 保存数据到指定设备
const remoteSave = await DistributedDataObjectManager.saveData('device_id')

// 撤回保存（删除所有设备上的数据）
const revokeResult = await DistributedDataObjectManager.revokeSaveData()
```

**保存机制**：

| 目标         | 说明                 |
|------------|--------------------|
| `'local'`  | 保存在本地设备，会同步到所有可信设备 |
| `deviceId` | 保存在指定远程设备          |

### 会话管理

```typescript
// 获取或生成会话 ID
const sessionId = DistributedDataObjectManager.getSessionId()

// 加入指定会话
await DistributedDataObjectManager.setSessionId('existing_session_id')

// 退出所有会话
await DistributedDataObjectManager.exitAllSession()
```

**会话机制**：多个设备通过相同的 sessionId 加入同一个协同会话，实现数据对象的实时同步。

### 资源释放

```typescript
DistributedDataObjectManager.releaseDistributedDataObjectManager()
```

**释放流程**：

1. 解绑事件监听：`off("change")`、`off("status")`
2. 重置内部状态：清空 distributedObject 引用、sessionId

---

## Logger

日志工具类，支持开发/生产模式切换，基于 HarmonyOS `hilog` 封装。

### 核心实现原理

`Logger` 基于 HarmonyOS 的 `hilog` 模块实现，提供以下特性：

1. **模式切换**：开发模式输出所有日志，生产模式仅输出错误日志
2. **日志分级**：debug、info、warn、error 四级
3. **域标识**：支持自定义日志域（domain）
4. **前缀标识**：支持自定义模块前缀

```typescript
import { Logger, LoggerMode } from '@ohos/distributed-manager'

// 创建日志实例
const logger = new Logger('MyModule', 0xFF00)

// 设置日志模式
logger.setLoggerMode(LoggerMode.DEVELOPMENT) // 开发模式，输出所有日志
// logger.setLoggerMode(LoggerMode.PRODUCTION) // 生产模式，仅输出错误日志

// 打印日志
logger.debug('调试信息', 'TAG')
logger.info('普通信息', 'TAG')
logger.warn('警告信息', 'TAG')
logger.error('错误信息', 'TAG', new Error('错误详情'))

// 获取当前模式
const mode = logger.getLoggerMode()
```

**构造参数**：

| 参数       | 类型       | 必填 | 说明                          |
|----------|----------|----|-----------------------------|
| `prefix` | `string` | 否  | 日志前缀，默认 `AVRecorderManage`  |
| `domain` | `number` | 否  | 日志域，范围 0x0~0xFFFF，默认 0xFF00 |

**日志模式**：

| 模式            | 说明   | 输出级别                  |
|---------------|------|-----------------------|
| `DEVELOPMENT` | 开发模式 | debug、info、warn、error |
| `PRODUCTION`  | 生产模式 | error                 |

---

## BundleManagerUtils

BundleManager 工具类，用于获取应用的 BundleInfo 信息。

```typescript
import { BundleManagerUtils } from '@ohos/distributed-manager'

const bundleInfo = await BundleManagerUtils.getBundleInfos()
console.log('应用名称:', bundleInfo.name)
console.log('版本号:', bundleInfo.versionName)
console.log('应用ID:', bundleInfo.bundleName)
```

**返回字段说明**：

| 字段            | 类型       | 说明     |
|---------------|----------|--------|
| `name`        | `string` | 应用名称   |
| `bundleName`  | `string` | 应用唯一标识 |
| `versionName` | `string` | 版本名称   |
| `versionCode` | `number` | 版本代码   |
| `vendor`      | `string` | 厂商名称   |

---

## 类型定义

### FunctionResult 类型

```typescript
/**
 * 方法返回值的结果
 */
interface FunctionResult<T> {
  /** 结果是否成功 */
  success: boolean;

  /** 结果数据 */
  data?: T;

  /** 错误时信息 */
  error?: BusinessError
}
```

### DeviceManager 类型

```typescript
interface InitDeviceManagerOptions {
bundleName?: string
listener?: DeviceManagerListener<ESObject>
}

enum DeviceState {
unknown, // 未知状态
available, // 在线状态
unavailable // 离线状态
}

interface BaseTargetDeviceParams {
device: distributedDeviceManager.DeviceBasicInfo
cb?: (deviceId: string) => void
}

interface BindTargerDevice extends BaseTargetDeviceParams {
/**
 * 绑定参数
 * 由开发者自行决定传入的键值对。默认会携带以下 key 值：
 * bindType 绑定类型，必填。默认为 1，PIN码。
 * targetPkgName 绑定目标的包名。
 * appName 尝试绑定目标应用程序名。
 * appOperation 应用程序要绑定的目标的原因。
 * customDescription 操作的详细说明。
 * */
bindParams?: Record<string, ESObject>,
}

interface DeviceInfos {
networkId?: string
deviceName?: string
deviceType?: number
deviceId?: string
}
```

### DeviceConnectionManager 类型

```typescript
interface InitDeviceConnectionManagerOptions {
bundleName?: string
listener?: DeviceConnectionManagerListener<ESObject>
}

interface CreateSessionParams {
deviceId: string
parameters?: Record<string, string>
peerInfo?: abilityConnectionManager.PeerInfo
connectOption?: abilityConnectionManager.ConnectOptions
serviceName?: string
}

enum DeviceConnectionState {
disconnect, // 未连接
connect // 已连接
}
```

### KVDataManager 类型

```typescript
interface InitKVDataManagerOptions {
bundleName?: string
storeId?: string
storeOptions?: distributedKVStore.Options
securityLevel?: distributedKVStore.SecurityLevel
listener?: KVDataManagerListener<ESObject>
}
```

### RDBManager 类型

```typescript
enum SyncDataStatus {
FAIL = 0,
SUCCESS = 1
}

interface InitRDBManagerOptions {
tableName: Array<string>
createTable: Array<string>
columns: Array<string>
listener?: RDBManagerListener<ESObject>
config?: data_rdb.StoreConfig
}

type SyncDataResultType = [string, number]

interface SyncDataResult {
deviceId: string
status: SyncDataStatus
}
```

### DistributedDataObjectManager 类型

```typescript
interface InitDistributedDataObjectManagerOptions {
source: object
listener?: DistributedDataObjectManagerListener<distributedDataObject.DataObject>
}
```

### 监听器类型

```typescript
// DeviceManagerListener
interface DeviceManagerListener<T> {
inited?: (data?: T) => void
success?: (device: DeviceBasicInfo) => void
failure?: (reason: number) => void
available?: (device: DeviceBasicInfo) => void
unavailable?: (device: DeviceBasicInfo) => void
unknown?: (device: DeviceBasicInfo) => void
change?: (action: DeviceStateChange, device: DeviceBasicInfo) => void
deviceNameChange?: (prevDeviceName: string, nowDeviceName: string) => void
serviceDie?: () => void
error?: (error: BusinessError) => void
release?: () => void
}

// DeviceConnectionManagerListener（继承自 DeviceManagerListener）
interface DeviceConnectionManagerListener<T> extends DeviceManagerListener<T> {
connect?: (info: EventCallbackInfo) => void
disconnect?: (info: EventCallbackInfo) => void
receiveMessage?: (info: EventCallbackInfo) => void
receiveData?: (info: EventCallbackInfo) => void
}

// KVDataManagerListener
interface KVDataManagerListener<T> {
inited?: (data?: T) => void
dataChange?: (data: ChangeNotification) => void
syncComplete?: (data: Array<[string, number]>) => void
distributedDataServiceDie?: () => void
error?: (error: BusinessError) => void
release?: () => void
}

// RDBManagerListener
interface RDBManagerListener<T> {
inited?: (data?: T) => void
createTable?: (tableNames: Array<string>) => void
dataChange?: (devices: Array<string> | Array<ChangeInfo>) => void
autoSyncProgress?: (progress: ProgressDetails) => void
statistics?: (info: SqlExecutionInfo) => void
perfStat?: (info: SqlExecutionInfo) => void
syncData?: (syncDataResults: Array<SyncDataResult>) => void
error?: (error: BusinessError) => void
release?: () => void
}

// DistributedDataObjectManagerListener
interface DistributedDataObjectManagerListener<T> {
inited?: (data?: T) => void
dataChange?: (sessionId: string, fields: Array<string>) => void
stateChange?: (sessionId: string, networkId: string, status: 'online' | 'offline') => void
sessionIdChange?: (sessionId?: string) => void
error?: (error: BusinessError) => void
release?: () => void
}
```

---

## 最佳实践

### 完整使用流程示例

```typescript
// 1. 初始化设备管理器
const deviceManager = DeviceManager.getInstance()
await deviceManager.initDeviceManager(context, {
  listener: {
    available: (device) => {
      console.log('发现在线设备:', device.deviceName)
    }
  }
})

// 2. 扫描设备
deviceManager.startDiscovering({ mode: 0 }, {})

// 3. 获取可信设备列表
const trustedDevices = deviceManager.getTrustedDevices()
const targetDevice = trustedDevices[0]

// 4. 创建连接会话
const connectionManager = DeviceConnectionManager.getInstance()
connectionManager.initDeviceConnectionManager(context, {
  listener: {
    connect: () => {
      console.log('设备连接成功')
    },
    receiveMessage: (info) => {
      console.log('收到消息:', info)
    }
  }
})
const sessionId = await connectionManager.createConnectionSession({
  deviceId: targetDevice.deviceId
})

// 5. 发送消息
await connectionManager.sendMessage('Hello from distributed manager!')

// 6. 使用 KV 数据库
const kvManager = KVDataManager.getInstance()
kvManager.initKVDataManager(context, {})
await kvManager.putData('shared_key', { value: 'shared_value' })

// 7. 使用关系型数据库
const rdbManager = RDBManager.getInstance()
rdbManager.initRDBManager(context, {
  tableName: ['messages'],
  createTable: ['CREATE TABLE IF NOT EXISTS messages (id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT)'],
  columns: ['id', 'content']
})
await rdbManager.insertData('messages', { content: 'Hello World' })

// 8. 资源释放
connectionManager.releaseDeviceConnectionManafger()
deviceManager.releaseDeviceManager()
kvManager.releaseKVDataManager()
rdbManager.releaseRDBManager()
```

### 错误处理建议

```typescript
try {
  const sessionId = await connectionManager.createConnectionSession({
    deviceId: targetDevice.deviceId
  })
} catch (error) {
  console.error('创建会话失败:', error)
  // 根据错误类型处理
  if (error.code === 12345) {
    // 设备不在线
  }
}
```

## 注意事项

1. **权限配置**：使用分布式能力需在 `module.json5` 中配置 `ohos.permission.DISTRIBUTED_DATASYNC` 和
   `ohos.permission.GET_DISTRIBUTED_DEVICE_INFO` 权限
2. **初始化顺序**：`DeviceConnectionManager` 内部会自动初始化 `DeviceManager`，无需重复初始化
3. **资源释放**：应用退出时需调用各模块的 `release` 方法释放资源，避免内存泄漏
4. **日志模式**：生产环境请设置 `LoggerMode.PRODUCTION`，避免敏感信息泄露
5. **设备兼容性**：分布式功能需要设备支持 HarmonyOS 分布式能力且已组网
6. **线程安全**：所有 Manager 均为单例模式，多线程环境下使用时需注意同步问题
7. **错误处理**：所有公共方法均会抛出异常或返回错误状态，使用时需做好错误捕获
8. **数据同步**：分布式数据同步需要设备处于同一局域网或已完成组网配置
9. **数据库加密**：如需加密存储，设置 `encrypt: true` 并配置合适的安全等级
10. **会话管理**：使用 `DeviceConnectionManager` 时，会话 ID 是连接的唯一标识，需妥善保存