# 三人PK功能实现说明

## 功能概述

基于现有的三人主播连麦和一对一主播PK功能，新增了三人PK功能。该功能允许在三人连麦的基础上进行PK竞赛，通过礼物统计来决定胜负。

## 实现原理

### 1. 数据结构设计

#### Redis键值设计
- `LivePK_Three`: 存储三人PK房间信息
  - Key: room_id
  - Value: JSON格式 `{"uid1": "主播1ID", "uid2": "主播2ID", "uid3": "主播3ID", "room_id": "房间ID"}`

- `LivePK_Three_gift`: 存储三人PK礼物统计
  - Key: uid (主播ID)
  - Value: 礼物总价值

- `LivePK_Three_timer`: 存储三人PK开始时间
  - Key: room_id
  - Value: 开始时间戳

#### 现有Redis键复用
- `LiveRoom`: 房间成员列表
- `LiveRoomMaster`: 用户所在房间映射
- `LiveConnect`: 连麦关系
- `LiveConnect_pull`: 拉流地址

### 2. API接口

#### 2.1 开始三人PK
**接口**: `Livepk.setThreePK`

**参数**:
- `uid`: 发起者用户ID
- `pkuid2`: 第二个主播ID  
- `pkuid3`: 第三个主播ID
- `sign`: 签名

**返回**:
```json
{
    "code": 0,
    "msg": "",
    "info": [{
        "addtime": 1632123456,
        "room_id": "12345_1632123456"
    }]
}
```

#### 2.2 结束三人PK
**接口**: `Livepk.endThreePK`

**参数**:
- `uid`: 用户ID
- `addtime`: PK开始时间戳
- `type`: 结束类型 (0:自动结束, 1:手动结束)
- `sign`: 签名

**返回**:
```json
{
    "code": 0,
    "msg": "",
    "info": [{
        "win_uid": "获胜者ID",
        "uid1": "主播1ID",
        "uid2": "主播2ID", 
        "uid3": "主播3ID",
        "gift1": "主播1礼物总值",
        "gift2": "主播2礼物总值",
        "gift3": "主播3礼物总值",
        "room_id": "房间ID"
    }]
}
```

### 3. Socket消息协议

#### 3.1 三人PK消息类型
**方法**: `LiveThreePK`

**Action类型**:
- `1`: 发起三人PK
- `2`: 接受三人PK
- `3`: 拒绝三人PK
- `4`: 三人PK开始通知
- `5`: 手动结束三人PK
- `7`: 忙碌/不可用
- `8`: 无响应
- `9`: 三人PK结果

#### 3.2 消息格式示例

**发起三人PK**:
```json
{
    "msg": [{
        "_method_": "LiveThreePK",
        "action": "1",
        "msgtype": "10",
        "uid": "发起者ID",
        "uname": "发起者昵称",
        "pkuid2": "主播2ID",
        "pkuid3": "主播3ID"
    }],
    "retcode": "000000",
    "retmsg": "OK"
}
```

**PK开始通知**:
```json
{
    "msg": [{
        "_method_": "LiveThreePK",
        "action": "4",
        "msgtype": "10",
        "uid1": "主播1ID",
        "uid2": "主播2ID",
        "uid3": "主播3ID",
        "room_id": "房间ID",
        "addtime": "开始时间戳"
    }],
    "retcode": "000000",
    "retmsg": "OK"
}
```

**PK结果通知**:
```json
{
    "msg": [{
        "_method_": "LiveThreePK",
        "action": "9",
        "msgtype": "10",
        "win_uid": "获胜者ID",
        "uid1": "主播1ID",
        "uid2": "主播2ID",
        "uid3": "主播3ID",
        "gift1": "主播1礼物总值",
        "gift2": "主播2礼物总值",
        "gift3": "主播3礼物总值",
        "room_id": "房间ID"
    }],
    "retcode": "000000",
    "retmsg": "OK"
}
```

### 4. 礼物统计机制

#### 4.1 礼物发送增强
在原有礼物发送基础上，增加三人PK检测：

**新增字段**:
- `isthreepk`: 是否三人PK (0/1)
- `threepk_uid1`: 主播1ID
- `threepk_uid2`: 主播2ID  
- `threepk_uid3`: 主播3ID
- `threepk_total1`: 主播1礼物总值
- `threepk_total2`: 主播2礼物总值
- `threepk_total3`: 主播3礼物总值

#### 4.2 统计逻辑
1. 检查主播是否在三人PK房间中
2. 如果是，则增加对应主播的礼物统计
3. 返回所有三人的实时统计数据
4. 前端根据统计数据实时更新PK进度

### 5. 使用流程

#### 5.1 完整流程
1. **建立三人连麦**: 三个主播先建立连麦关系
2. **发起三人PK**: 任一主播发起三人PK邀请
3. **接受PK**: 其他主播接受PK邀请
4. **PK进行**: 观众送礼物，实时统计各主播礼物价值
5. **PK结束**: 5分钟后自动结束或手动结束
6. **结果公布**: 礼物价值最高者获胜，平局则无获胜者

#### 5.2 前端集成示例

**JavaScript客户端代码**:
```javascript
// 发起三人PK
function startThreePK(pkuid2, pkuid3) {
    var data = {
        msg: [{
            _method_: "LiveThreePK",
            action: "1",
            msgtype: "10",
            uid: currentUserId,
            uname: currentUserName,
            pkuid2: pkuid2,
            pkuid3: pkuid3
        }],
        token: userToken
    };
    socket.emit('broadcast', data);
}

// 接受三人PK
function acceptThreePK(uid, pkuid2, pkuid3) {
    var data = {
        msg: [{
            _method_: "LiveThreePK", 
            action: "2",
            msgtype: "10",
            uid: uid,
            pkuid2: pkuid2,
            pkuid3: pkuid3
        }],
        token: userToken
    };
    socket.emit('broadcast', data);
}

// 监听PK消息
socket.on('broadcastingListen', function(data) {
    var msg = JSON.parse(data[0]);
    if(msg.msg[0]._method_ === 'LiveThreePK') {
        switch(msg.msg[0].action) {
            case '1': // PK邀请
                showPKInvite(msg.msg[0]);
                break;
            case '4': // PK开始
                startPKTimer(msg.msg[0]);
                break;
            case '9': // PK结果
                showPKResult(msg.msg[0]);
                break;
        }
    }
});
```

## 6. 修改文件清单

### 6.1 后端文件
1. `phalapi/src/app/Api/Livepk.php` - 新增三人PK API接口
2. `phalapi/src/app/Model/Live.php` - 修改礼物发送逻辑，支持三人PK统计
3. `dspIM/s1.js` - 新增三人PK Socket处理逻辑

### 6.2 主要修改点
- **API层**: 新增 `setThreePK` 和 `endThreePK` 方法
- **Model层**: 在 `sendGift` 方法中增加三人PK检测和统计
- **Socket层**: 新增 `LiveThreePK` 消息处理和 `endThreePk` 函数

## 7. 兼容性说明

### 7.1 向后兼容
- 现有的一对一PK功能完全保持不变
- 现有的三人连麦功能完全保持不变
- 新增功能不影响现有业务逻辑

### 7.2 最小改动原则
- 复用现有的房间管理机制
- 复用现有的礼物发送机制
- 复用现有的Socket通信机制
- 仅在必要位置增加三人PK相关逻辑

## 8. 测试建议

### 8.1 功能测试
1. 三人连麦建立后发起PK
2. PK过程中礼物统计准确性
3. PK自动结束和手动结束
4. 异常情况处理（断线重连等）

### 8.2 性能测试
1. 多个三人PK房间同时进行
2. 高频礼物发送时的统计性能
3. Redis内存使用情况

### 8.3 兼容性测试
1. 确保一对一PK功能正常
2. 确保三人连麦功能正常
3. 确保普通礼物发送功能正常

## 9. 部署说明

### 9.1 部署步骤
1. 备份现有代码
2. 更新后端PHP文件
3. 重启Socket服务器
4. 更新前端代码（如需要）
5. 测试功能完整性

### 9.2 回滚方案
如果出现问题，可以快速回滚到备份版本，因为新功能是增量式的，不会破坏现有数据结构。

## 10. 总结

本次三人PK功能的实现严格遵循了最小改动原则，在现有架构基础上进行扩展，确保了：

1. **功能完整性**: 支持完整的三人PK流程
2. **向后兼容**: 不影响现有功能
3. **代码质量**: 遵循现有代码规范
4. **性能优化**: 复用现有机制，避免重复开发
5. **易于维护**: 代码结构清晰，便于后续维护

该实现方案可以直接部署使用，为平台增加更丰富的互动玩法。