# WebSocket 协议升级问题记录

## 问题描述

booins_app 升级到 WebSocket Protocol v4 后，连接时报错 `device signature invalid`，而 agent-chat 使用相同协议正常连接。

## 发生时间

2026-07-14

## 根本原因

**签名 payload 与 connect 消息的 platform 字段不一致**

booins_app 的 `wsGateway.js` 中：
1. `clientInfo` 对象初始化时 `platform: 'app'`
2. 在 `handleConnectChallenge` 函数中检测到真实的 platform（如 iOS 上是 `'iPhone'`）
3. 构建签名 payload 时使用了检测到的 platform 值
4. 但发送 connect 消息时，`clientInfo.platform` 仍然是初始值 `'app'`

服务端验证签名时，会用 connect 消息中的 `client.platform` 重建 payload 并验证签名，由于值不一致导致验证失败。

### 签名 payload 格式 (v3)

```
v3|deviceId|clientId|clientMode|role|scopes|signedAtMs|token|nonce|platform|deviceFamily
```

签名验证时，服务端会从 connect 消息中提取 `client.platform` 和 `client.deviceFamily`，如果这些值与客户端签名时使用的值不同，签名验证就会失败。

## 对比分析

### agent-chat (正常连接)
```json
{
  "client": {
    "platform": "Win32",
    "deviceFamily": "desktop"
  }
}
```
- 使用 `navigator.platform` 直接获取
- connect 消息和签名 payload 使用相同值

### booins_app (修复前)
```json
{
  "client": {
    "platform": "app",  // ← 问题：初始值未更新
    "deviceFamily": "mobile"
  }
}
```
- 虽然代码检测到正确的 platform（如 "iPhone"）
- 但只用于签名 payload，未更新 clientInfo 对象

## 解决方案

在 `booins_app/services/wsGateway.js` 的 `handleConnectChallenge` 函数中，检测到 platform 和 deviceFamily 后，立即更新 `clientInfo` 对象：

```javascript
// 获取系统信息用于 platform 和 deviceFamily
let platform = 'web'
let deviceFamily = 'desktop'

try {
  if (typeof navigator !== 'undefined' && navigator.platform) {
    platform = navigator.platform
    deviceFamily = 'desktop'
  } else {
    const sysInfo = uni.getSystemInfoSync()
    const uniPlatform = sysInfo.platform || 'app'
    if (uniPlatform === 'ios') {
      platform = 'iPhone'
      deviceFamily = 'mobile'
    } else if (uniPlatform === 'android') {
      platform = 'Linux armv8l'
      deviceFamily = 'mobile'
    } else {
      platform = uniPlatform
      deviceFamily = sysInfo.uniPlatform === 'web' ? 'desktop' : 'mobile'
    }
  }
} catch (e) {
  log('[handshake] 获取系统信息失败: ' + (e.message || e))
}

// ✅ 关键修复：更新 clientInfo，确保 connect 消息和签名使用相同值
clientInfo.platform = platform
clientInfo.deviceFamily = deviceFamily
```

## 相关文件

- `booins_app/services/wsGateway.js` - WebSocket 客户端（已修复）
- `booins_app/services/cryptoService.js` - 设备身份和签名（已升级到 v3）
- `agent-chat/js/gateway.js` - 参考实现
- `agent-chat/js/auth.js` - 参考实现

## 其他问题

在修复过程中发现文件中有 Git 冲突标记（`<<<<<<< HEAD`），导致应用白屏。已清理。

## 验证结果

修复后 booins_app 在 iOS 模拟器上成功连接 WebSocket Gateway。