# WebSocket Server 说明文档

## 1. 概述

WebSocket Server 是基于 Ratchet 库实现的纯 PHP WebSocket 服务器，主要用于为智能客服系统提供实时通信支持，特别是为不支持 EventSource 的微信小程序提供流式请求处理能力。

## 2. 安装与依赖

### 2.1 依赖库

- **Ratchet**: 纯 PHP WebSocket 实现库
  ```bash
  composer require cboden/ratchet
  ```

### 2.2 环境要求

- PHP 7.4+
- Composer
- ThinkPHP 6.x

## 3. 服务器文件结构

### 3.1 核心文件

- **启动脚本**: `src/ws_server.php` - WebSocket 服务器主启动文件
- **智能客服控制器**: `src/addon/aikefu/api/controller/WebSocket.php` - aikefu 插件的 WebSocket 控制器实现

### 3.2 目录结构

```
├── backend/
│   ├── docs/
│   │   └── websocket/
│   │       └── README.md          # 本文档
│   └── src/
│       ├── ws_server.php          # WebSocket 服务器启动脚本
│       └── addon/
│           └── aikefu/
│               └── api/
│                   └── controller/
│                       └── WebSocket.php  # aikefu 插件 WebSocket 控制器
```

## 4. 服务器启动与配置

### 4.1 启动命令

在 `src` 目录下执行：

```bash
php ws_server.php
```

### 4.2 默认配置

- **监听地址**: `0.0.0.0` (所有网络接口)
- **端口**: `8080`
- **WebSocket 地址**: `ws://localhost:8080`

### 4.3 自定义配置

可以在 `ws_server.php` 中修改以下配置：

```php
// 配置WebSocket服务器
$httpHost = 'localhost'; // 客户端连接时使用的主机名
$port = 8080; // WebSocket服务器端口
$address = '0.0.0.0'; // 监听所有网络接口
```

## 5. WebSocket 路径

### 5.1 默认测试路径

- **路径**: `/ws`
- **功能**: 用于测试 WebSocket 连接
- **示例**: `ws://localhost:8080/ws`

### 5.2 智能客服路径

- **路径**: `/ws/aikefu`
- **功能**: 智能客服聊天功能接口
- **示例**: `ws://localhost:8080/ws/aikefu`

## 6. 消息格式

### 6.1 客户端发送消息格式

```json
{
  "message": "用户输入的消息",
  "token": "用户认证令牌",
  "session_id": "会话ID",
  "action": "chat" // 动作类型
}
```

### 6.2 服务器响应消息格式

#### 聊天响应

```json
{
  "type": "chat",
  "message": "客服回复的消息内容",
  "session_id": "会话ID",
  "complete": false // 是否完成响应
}
```

#### 错误响应

```json
{
  "type": "error",
  "message": "错误信息描述",
  "code": "错误代码"
}
```

#### 系统消息

```json
{
  "type": "system",
  "message": "系统消息内容"
}
```

## 7. 客户端使用示例

### 7.1 JavaScript 示例

```javascript
// 创建WebSocket连接
const ws = new WebSocket('ws://localhost:8080/ws/aikefu');

// 连接打开时
ws.onopen = function(event) {
    console.log('WebSocket连接已打开');
    
    // 发送聊天消息
    ws.send(JSON.stringify({
        message: '你好',
        token: 'user_token_here',
        session_id: 'session_123',
        action: 'chat'
    }));
};

// 接收消息
ws.onmessage = function(event) {
    const data = JSON.parse(event.data);
    console.log('收到消息:', data);
    
    if (data.type === 'chat') {
        // 处理聊天消息
        console.log('客服回复:', data.message);
        
        if (data.complete) {
            console.log('对话完成');
        }
    } else if (data.type === 'error') {
        // 处理错误
        console.error('错误:', data.message);
    }
};

// 连接关闭时
ws.onclose = function(event) {
    console.log('WebSocket连接已关闭');
};

// 连接错误时
ws.onerror = function(error) {
    console.error('WebSocket错误:', error);
};
```

### 7.2 微信小程序示例

```javascript
// 创建WebSocket连接
const ws = wx.connectSocket({
    url: 'ws://localhost:8080/ws/aikefu',
    header: {
        'content-type': 'application/json'
    }
});

// 连接打开时
wx.onSocketOpen(function(res) {
    console.log('WebSocket连接已打开', res);
    
    // 发送聊天消息
    wx.sendSocketMessage({
        data: JSON.stringify({
            message: '你好',
            token: 'user_token_here',
            session_id: 'session_123',
            action: 'chat'
        })
    });
});

// 接收消息
wx.onSocketMessage(function(res) {
    const data = JSON.parse(res.data);
    console.log('收到消息:', data);
    
    if (data.type === 'chat') {
        // 处理聊天消息
        console.log('客服回复:', data.message);
        
        if (data.complete) {
            console.log('对话完成');
        }
    } else if (data.type === 'error') {
        // 处理错误
        console.error('错误:', data.message);
    }
});

// 连接关闭时
wx.onSocketClose(function(res) {
    console.log('WebSocket连接已关闭', res);
});

// 连接错误时
wx.onSocketError(function(res) {
    console.error('WebSocket错误:', res);
});
```

## 8. 功能特性

### 8.1 实时通信

- 支持双向实时通信
- 消息即时推送
- 支持流式响应

### 8.2 智能客服集成

- 与现有智能客服系统无缝集成
- 支持上下文会话管理
- 支持多用户并发访问

### 8.3 插件化设计

- 支持为不同插件注册独立的 WebSocket 控制器
- 路径格式：`/ws/{addon_name}`
- 便于扩展其他插件的 WebSocket 支持

## 9. 故障排除

### 9.1 常见问题

#### 问题：服务器无法启动

**可能原因**：
- 端口被占用
- 依赖库未安装
- PHP 版本不兼容

**解决方案**：
- 检查端口占用情况：`netstat -an | findstr 8080`
- 重新安装依赖：`composer install`
- 确保 PHP 版本 >= 7.4

#### 问题：客户端无法连接

**可能原因**：
- 服务器未启动
- 网络防火墙限制
- WebSocket 地址错误

**解决方案**：
- 确认服务器已启动
- 检查防火墙设置，确保端口 8080 开放
- 验证 WebSocket 地址格式

#### 问题：消息发送失败

**可能原因**：
- 消息格式错误
- 认证失败
- 服务器内部错误

**解决方案**：
- 检查消息格式是否符合要求
- 验证用户认证信息
- 查看服务器日志获取详细错误信息

### 9.2 日志查看

服务器启动时会输出详细日志，包括：
- 已注册的 WebSocket 控制器
- 连接信息
- 错误信息

## 10. 扩展开发

### 10.1 为其他插件添加 WebSocket 支持

1. 在插件目录下创建 WebSocket 控制器：
   ```
   addon/{addon_name}/api/controller/WebSocket.php
   ```

2. 实现 MessageComponentInterface 接口：
   ```php
   <?php
   namespace addon\{addon_name}\api\controller;
   
   use Ratchet\MessageComponentInterface;
   use Ratchet\ConnectionInterface;
   
   class WebSocket implements MessageComponentInterface {
       protected $clients;
       
       public function __construct() {
           $this->clients = new \SplObjectStorage;
       }
       
       public function onOpen(ConnectionInterface $conn) {
           // 处理连接打开
       }
       
       public function onMessage(ConnectionInterface $conn, $msg) {
           // 处理收到的消息
       }
       
       public function onClose(ConnectionInterface $conn) {
           // 处理连接关闭
       }
       
       public function onError(ConnectionInterface $conn, \Exception $e) {
           // 处理错误
       }
   }
   ```

3. 重启 WebSocket 服务器，新插件的 WebSocket 控制器将自动注册到 `/ws/{addon_name}` 路径

## 11. 版本历史

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2025-12-19 | 初始版本，支持智能客服系统的 WebSocket 通信 |

## 12. 联系方式

如有问题或建议，请联系技术支持团队。