# 红包功能实现方案

## 功能概述
实现类似微信的抢红包功能，包括：
- 发送红包（普通红包、拼手气红包）
- 领取红包
- 查看红包详情和领取记录
- 红包过期处理

## 需要修改的文件清单

### 1. 消息类型定义
**文件**: `../protocol/constant/constant.go`
- 添加 `RedPacket = 123` 消息类型常量
- 在 `ContentType2PushContent` 映射中添加红包推送内容

### 2. 数据库模型
**新建文件**: `pkg/common/storage/model/redpacket.go`
- `RedPacket` - 红包主表
- `RedPacketReceive` - 红包领取记录表

### 3. 数据库操作接口
**新建文件**: `pkg/common/storage/database/redpacket.go`
- 定义红包数据库操作接口

### 4. MongoDB实现
**新建文件**: `pkg/common/storage/database/mgo/redpacket.go`
- 实现红包数据库操作

### 5. RPC服务
**新建目录**: `internal/rpc/redpacket/`
- `redpacket.go` - 红包RPC服务实现
- `server.go` - RPC服务注册

### 6. API接口
**新建文件**: `internal/api/redpacket.go`
- 发送红包接口
- 领取红包接口
- 查询红包详情接口
- 查询红包领取记录接口

### 7. 消息类型处理
**修改文件**: 
- `internal/api/msg.go` - 添加红包消息解析
- `internal/rpc/msg/verify.go` - 添加红包消息封装
- `pkg/apistruct/msg.go` - 添加红包消息结构体

### 8. 推送处理
**修改文件**: `internal/push/offlinepush_handler.go`
- 添加红包消息的离线推送内容

### 9. 路由注册
**修改文件**: `internal/api/router.go`
- 注册红包相关路由

## 数据库表设计

### red_packets 表
```go
type RedPacket struct {
    RedPacketID    string    `bson:"red_packet_id"`    // 红包ID
    SendUserID     string    `bson:"send_user_id"`     // 发送者ID
    GroupID        string    `bson:"group_id"`         // 群ID（群红包）
    ConversationID string    `bson:"conversation_id"`  // 会话ID
    SessionType    int32     `bson:"session_type"`     // 会话类型
    RedPacketType  int32     `bson:"red_packet_type"` // 红包类型：1-普通红包，2-拼手气红包
    TotalAmount    int64     `bson:"total_amount"`     // 总金额（分）
    TotalCount     int32     `bson:"total_count"`      // 总个数
    RemainAmount   int64     `bson:"remain_amount"`    // 剩余金额（分）
    RemainCount    int32     `bson:"remain_count"`     // 剩余个数
    Blessing       string    `bson:"blessing"`         // 祝福语
    Status         int32     `bson:"status"`           // 状态：0-进行中，1-已领完，2-已过期
    ExpireTime     time.Time `bson:"expire_time"`     // 过期时间
    CreateTime     time.Time `bson:"create_time"`     // 创建时间
    Ex             string    `bson:"ex"`              // 扩展字段
}
```

### red_packet_receives 表
```go
type RedPacketReceive struct {
    ReceiveID      string    `bson:"receive_id"`      // 领取记录ID
    RedPacketID    string    `bson:"red_packet_id"`   // 红包ID
    ReceiveUserID  string    `bson:"receive_user_id"` // 领取者ID
    Amount         int64     `bson:"amount"`           // 领取金额（分）
    ReceiveTime    time.Time `bson:"receive_time"`    // 领取时间
    Ex             string    `bson:"ex"`              // 扩展字段
}
```

## API接口设计

### 1. 发送红包 ✅ 已实现
```
POST /redpacket/send_redpacket
Request:
{
    "groupID": "group123",        // 群ID（必填）
    "redPacketType": 1,           // 红包类型：1-普通红包，2-拼手气红包（必填）
    "totalAmount": 10000,         // 总金额（分）（必填）
    "totalCount": 10,             // 总个数（必填）
    "blessing": "恭喜发财"        // 祝福语（可选）
}
Response:
{
    "redPacketID": "rp123",       // 红包ID
    "serverMsgID": "msg123",      // 服务器消息ID
    "clientMsgID": "client123",   // 客户端消息ID
    "sendTime": 1234567890         // 发送时间戳（毫秒）
}
```

**特性**:
- 只支持群聊
- 发送用户默认为群主（自动获取）
- 自动创建数据库记录
- 自动发送红包消息到群聊

### 2. 领取红包
```
POST /redpacket/receive
Request:
{
    "redPacketID": "rp123"
}
Response:
{
    "amount": 1000,  // 领取金额（分）
    "remainAmount": 9000,
    "remainCount": 9,
    "status": 0  // 0-进行中，1-已领完
}
```

### 3. 查询红包详情
```
GET /redpacket/detail?redPacketID=rp123
Response:
{
    "redPacketID": "rp123",
    "sendUserID": "user123",
    "totalAmount": 10000,
    "totalCount": 10,
    "remainAmount": 9000,
    "remainCount": 9,
    "blessing": "恭喜发财",
    "status": 0,
    "receiveList": [...]
}
```

### 4. 查询红包领取记录
```
GET /redpacket/receives?redPacketID=rp123
Response:
{
    "total": 1,
    "receives": [
        {
            "receiveUserID": "user456",
            "amount": 1000,
            "receiveTime": "2024-01-01T10:00:00Z"
        }
    ]
}
```

## 业务逻辑

### 发送红包流程
1. 验证参数（金额、个数、类型）
2. 创建红包记录
3. 发送红包消息（ContentType=RedPacket）
4. 返回红包ID和消息ID

### 领取红包流程
1. 验证红包是否存在且可领取
2. 检查用户是否已领取
3. 计算领取金额（普通红包平均分配，拼手气红包随机）
4. 更新红包记录（剩余金额、剩余个数）
5. 创建领取记录
6. 如果领完，更新红包状态
7. 发送领取通知消息

### 红包过期处理
- 建议使用定时任务检查过期红包
- 过期红包状态更新为已过期
- 剩余金额退回（如需要）

## 注意事项

1. **并发控制**：领取红包需要使用分布式锁，防止重复领取
2. **金额计算**：拼手气红包需要保证最后一个红包能领完剩余金额
3. **消息推送**：红包消息需要特殊推送内容
4. **数据一致性**：红包金额和领取记录需要事务保证一致性
5. **性能优化**：红包详情查询需要缓存优化

## 实现步骤

1. ✅ 定义消息类型常量
2. ✅ 创建数据库模型
3. ✅ 实现数据库操作
4. ✅ 实现RPC服务
5. ✅ 实现API接口
6. ✅ 添加消息类型处理
7. ✅ 添加推送处理
8. ✅ 测试和优化