@realsee/vr-signals/docs/media/COMPATIBILITY.md

vr 信号器

# 版本兼容性指南

## 概述

本文档说明 `@realsee/vr-signals` 1.x 和 2.x 版本之间的兼容性问题和解决方案。

## 问题描述

当 Remote 端使用 2.0 版本，Client 端使用 1.0 版本时，可能会出现通信异常。

**✅ 最新状态（2.0.0-beta.7+）**：已经内置了兼容性修复，2.0 Remote 默认兼容 1.0 Client。

## 兼容性问题原因（已修复）

### 1. 安全配置差异

2.0 版本引入了安全验证机制，虽然默认配置是兼容的，但某些场景下可能需要显式配置：

```typescript
// 2.0 默认配置（兼容 1.x）
{
  strictMode: false,        // 禁用严格模式
  validateOrigin: false,    // 禁用来源验证
  validateSignature: false, // 禁用签名验证
}
```

### 2. 消息格式差异

2.0 版本可能对消息格式进行了优化，需要确保向后兼容。

### 3. API 差异

- 1.x 版本：使用 `callAction()` 和 `subscribe.on()`
- 2.x 版本：推荐使用 `send()` 和直接的 `on()`（但仍支持旧 API）

## 已实现的修复

### 修复 1：消息验证宽松模式

2.0.0-beta.7+ 版本中，MessageBridge 在非严格模式下不会拒绝验证失败的消息，只会记录警告日志。这确保了 1.x Client 的消息能够被正确处理。

### 修复 2：默认兼容配置

2.0 版本的默认安全配置已经设置为兼容 1.x：
```typescript
{
  strictMode: false,        // 禁用严格模式
  validateOrigin: false,    // 禁用来源验证
  validateSignature: false  // 禁用签名验证
}
```

### 修复 3：ActionMap 访问兼容

MessageBridge 的 `executeRequest` 方法支持三层回退：
1. 优先使用 `handleActionRequest()` 方法（2.0 的 ActionRegistry）
2. 回退到 `_actionManager`（2.0 的 StandardActionManager）
3. 最后回退到 `_actionMap`（1.0 的方式）

### 修复 4：初始化时序优化

Remote 类在调用 `super()` 后立即初始化 `actionRegistry` 并注册 actionMap，确保握手时所有 actions 已就绪。

## 解决方案

### 方案 1：使用默认配置（推荐）

**从 2.0.0-beta.7 开始，不需要特殊配置！** 默认配置已经兼容 1.x Client：

```typescript
import { RealseeVRSignalsRemote } from '@realsee/vr-signals'

const remote = new RealseeVRSignalsRemote({
  logLevel: 'INFO',
  actionMap: {
    setState(data) {
      console.log('State update:', data)
      return { success: true }
    }
  }
})
// 默认配置已经兼容 1.x Client，无需额外配置！
```

### 方案 2：显式使用兼容配置（明确意图）

如果你想明确表示兼容意图，可以显式使用兼容配置：

```typescript
import { RealseeVRSignalsRemote, getV1CompatibilityConfig } from '@realsee/vr-signals'

const remote = new RealseeVRSignalsRemote({
  logLevel: 'INFO',
  // 显式使用 1.x 兼容配置（实际上与默认配置相同）
  security: getV1CompatibilityConfig(),
  actionMap: {
    setState(data) {
      console.log('State update:', data)
      return { success: true }
    }
  }
})
```

### 方案 3：使用自动兼容配置

```typescript
import { RealseeVRSignalsRemote, getAutoCompatibilityConfig } from '@realsee/vr-signals'

const remote = new RealseeVRSignalsRemote({
  logLevel: 'INFO',
  // 自动检测并配置兼容性
  security: getAutoCompatibilityConfig(),
  actionMap: {
    setState(data) {
      console.log('State update:', data)
      return { success: true }
    }
  }
})
```

### 方案 4：手动配置完全兼容模式

```typescript
import { RealseeVRSignalsRemote } from '@realsee/vr-signals'

const remote = new RealseeVRSignalsRemote({
  logLevel: 'INFO',
  // 手动配置完全兼容 1.x 版本（与默认配置相同）
  security: {
    strictMode: false,
    validateOrigin: false,
    validateSignature: false,
    allowedOrigins: ['*'],
    allowWildcardDomains: true
  },
  actionMap: {
    setState(data) {
      console.log('State update:', data)
      return { success: true }
    }
  }
})
```

### 方案 5：2.x Client + 2.x Remote（高安全模式）

如果你的 Client 和 Remote 都是 2.x 版本，可以启用更高的安全配置：

```typescript
import { RealseeVRSignalsRemote, getV2DefaultConfig } from '@realsee/vr-signals'

const remote = new RealseeVRSignalsRemote({
  logLevel: 'INFO',
  // 使用 2.x 默认配置，启用更多安全特性
  security: getV2DefaultConfig('my-secret-key'),
  actionMap: {
    setState(data) {
      console.log('State update:', data)
      return { success: true }
    }
  }
})
```

## 兼容性测试

### 测试场景 1：1.0 Client + 2.0 Remote

```typescript
// 1.0 Client 端代码（保持不变）
const client = new RealseeVRSignalsClient({
  vrLink: 'http://localhost:3000/vr-app',
  element: iframeElement
})

// 使用 1.x API
client.callAction('setState', { mode: 'editing' })
client.subscribe.on('cameraUpdate', (data) => {
  console.log('Camera update:', data)
})
```

```typescript
// 2.0 Remote 端代码（默认配置已兼容）
import { RealseeVRSignalsRemote } from '@realsee/vr-signals'

const remote = new RealseeVRSignalsRemote({
  logLevel: 'INFO',
  // ⭐ 无需特殊配置，默认已兼容 1.x Client
  actionMap: {
    setState(data) {
      console.log('Received from 1.x client:', data)
      return { success: true }
    }
  }
})

// 或者显式使用兼容配置（可选）
import { getV1CompatibilityConfig } from '@realsee/vr-signals'
const remoteWithExplicitConfig = new RealseeVRSignalsRemote({
  logLevel: 'INFO',
  security: getV1CompatibilityConfig(),
  actionMap: { /* ... */ }
})
```

### 测试场景 2：2.0 Client + 2.0 Remote

```typescript
// 2.0 Client 端代码
const client = new RealseeVRSignalsClient({
  vrLink: 'http://localhost:3000/vr-app',
  element: iframeElement,
  logLevel: 'INFO'
})

// 使用 2.x API
await client.send('setState', { mode: 'panorama' })
client.on('cameraUpdate', (data) => {
  console.log('Camera update:', data)
})
```

```typescript
// 2.0 Remote 端代码
const remote = new RealseeVRSignalsRemote({
  logLevel: 'INFO',
  // 可以使用更严格的安全配置
  security: {
    strictMode: true,
    validateOrigin: true,
    validateSignature: false
  },
  actionMap: {
    setState(data) {
      console.log('Received from 2.x client:', data)
      return { success: true }
    }
  }
})
```

## 调试方法

### 1. 启用详细日志

```typescript
const remote = new RealseeVRSignalsRemote({
  logLevel: 'DEBUG', // 或 'INFO'
  security: getV1CompatibilityConfig()
})
```

### 2. 检查消息传递

在浏览器控制台中监听 postMessage 事件：

```javascript
window.addEventListener('message', (event) => {
  console.log('Received message:', event.data)
})
```

### 3. 验证安全配置

```typescript
const remote = new RealseeVRSignalsRemote({
  logLevel: 'INFO',
  security: getV1CompatibilityConfig()
})

// 获取当前配置
const options = remote.getOptions()
console.log('Security config:', options.security)
```

## 常见错误和解决方法

### 错误 1：消息被拒绝

**症状**：控制台显示 "Message rejected" 或类似错误

**原因**：安全验证配置过于严格

**解决方法**：
```typescript
const remote = new RealseeVRSignalsRemote({
  security: {
    strictMode: false,        // 禁用严格模式
    validateOrigin: false,    // 禁用来源验证
    validateSignature: false  // 禁用签名验证
  }
})
```

### 错误 2：握手失败

**症状**：连接一直处于 "connecting" 状态

**原因**：握手消息格式不兼容或超时

**解决方法**：
```typescript
const remote = new RealseeVRSignalsRemote({
  shakehandRetryTimes: 20,  // 增加重试次数
  handshakeRetryStrategy: {
    baseDelay: 500,
    maxDelay: 5000,
    jitterRange: [0.85, 1.15]
  }
})
```

### 错误 3：Action 调用失败

**症状**：调用 action 时返回错误或无响应

**原因**：Action 名称或参数格式不匹配

**解决方法**：
```typescript
const remote = new RealseeVRSignalsRemote({
  logLevel: 'DEBUG', // 启用调试日志
  actionMap: {
    setState(data) {
      console.log('Received data:', data)
      console.log('Data type:', typeof data)
      return { success: true }
    }
  }
})
```

## 迁移建议

### 从 1.x 迁移到 2.x

1. **渐进式迁移**：先升级 Remote 端，保持兼容配置
2. **测试验证**：确保与现有 1.x Client 正常通信
3. **逐步升级**：逐步升级 Client 端到 2.x
4. **启用安全特性**：所有端都升级后，启用严格安全配置

```typescript
// 阶段 1：Remote 端升级到 2.x（兼容模式）
const remote = new RealseeVRSignalsRemote({
  security: getV1CompatibilityConfig() // 兼容 1.x Client
})

// 阶段 2：Client 端逐步升级到 2.x
// 可以混合使用 1.x 和 2.x Client

// 阶段 3：所有端都升级后，启用严格模式
const remote = new RealseeVRSignalsRemote({
  security: {
    strictMode: true,
    validateOrigin: true,
    validateSignature: true,
    signatureKey: 'your-secret-key'
  }
})
```

## 版本兼容性矩阵

| Client 版本 | Remote 版本 | 兼容性 | 配置要求 |
|------------|------------|--------|---------|
| 1.x | 1.x | ✅ 完全兼容 | 默认配置 |
| 1.x | 2.x | ✅ 兼容 | Remote 需使用 `getV1CompatibilityConfig()` |
| 2.x | 1.x | ✅ 兼容 | Client 默认配置即可 |
| 2.x | 2.x | ✅ 完全兼容 | 可使用严格安全配置 |

## 联系支持

如果遇到兼容性问题无法解决，请：

1. 检查本文档的常见错误部分
2. 启用 DEBUG 日志查看详细信息
3. 提供以下信息报告问题：
   - Client 版本和 Remote 版本
   - 错误信息和日志
   - 配置代码
   - 复现步骤