zhibo/礼物系统完整开发文档.md

# 礼物系统完整开发文档

## 📋 目录

1. [系统概述](#系统概述)
2. [数据库设计](#数据库设计)
3. [后端API接口](#后端api接口)
4. [前端页面](#前端页面)
5. [APP端集成](#app端集成)
6. [部署指南](#部署指南)
7. [测试验证](#测试验证)

---

## 系统概述

### 功能简介

礼物系统是直播平台的核心功能之一，支持用户在直播间送礼物给主播，包含以下核心功能：

- **礼物管理**：后台管理员可以添加、编辑、删除、启用/禁用礼物
- **打赏记录**：记录所有用户的礼物打赏行为
- **统计分析**：礼物数量、启用/禁用状态、总价值统计
- **APP集成**：移动端获取礼物列表并发送礼物

### 技术栈

- **后端**：Java + Spring Boot + MyBatis + MySQL
- **前端管理**：Vue.js + Element UI
- **移动端**：Android (Java)
- **数据库**：MySQL 5.7+

### 核心数据表

- `eb_gift` - 礼物主数据表（20个礼物）
- `eb_gift_record` - 礼物打赏记录表

---

## 数据库设计

### 1. eb_gift 表（礼物主数据表）

```sql
CREATE TABLE `eb_gift` (
  `id` int(11) NOT NULL AUTO_INCREMENT COMMENT '礼物ID',
  `name` varchar(50) NOT NULL COMMENT '礼物名称',
  `image` varchar(255) DEFAULT NULL COMMENT '礼物图片URL',
  `diamond_price` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '钻石价格',
  `intimacy` int(11) NOT NULL DEFAULT '0' COMMENT '亲密度',
  `is_heartbeat` tinyint(1) NOT NULL DEFAULT '0' COMMENT '是否心动礼物 0-否 1-是',
  `level` int(11) NOT NULL DEFAULT '1' COMMENT '礼物等级',
  `sort` int(11) NOT NULL DEFAULT '0' COMMENT '排序',
  `status` tinyint(1) NOT NULL DEFAULT '1' COMMENT '状态 0-禁用 1-启用',
  `is_deleted` tinyint(1) NOT NULL DEFAULT '0' COMMENT '是否删除 0-否 1-是',
  `buy_type` varchar(20) DEFAULT 'diamond' COMMENT '购买类型',
  `belong` varchar(20) DEFAULT 'common' COMMENT '归属',
  `remark` varchar(255) DEFAULT NULL COMMENT '备注',
  `create_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  KEY `idx_status` (`status`),
  KEY `idx_sort` (`sort`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='礼物表';
```

**字段说明：**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 礼物唯一标识 |
| name | varchar(50) | 礼物名称，如"玫瑰花"、"钻戒" |
| image | varchar(255) | 礼物图片URL |
| diamond_price | decimal(10,2) | 钻石价格 |
| intimacy | int | 赠送礼物增加的亲密度 |
| is_heartbeat | tinyint | 是否为心动礼物（特殊标记） |
| level | int | 礼物等级 |
| sort | int | 显示排序 |
| status | tinyint | 启用状态（0-禁用，1-启用） |
| is_deleted | tinyint | 软删除标记 |
| buy_type | varchar(20) | 购买类型（diamond-钻石） |
| belong | varchar(20) | 归属（common-通用，live-直播专属） |
| remark | varchar(255) | 备注信息 |

### 2. eb_gift_record 表（打赏记录表）

```sql
CREATE TABLE `eb_gift_record` (
  `id` int(11) NOT NULL AUTO_INCREMENT COMMENT '记录ID',
  `sender_id` int(11) NOT NULL COMMENT '送礼用户ID',
  `sender_nickname` varchar(50) DEFAULT NULL COMMENT '送礼用户昵称',
  `receiver_id` int(11) NOT NULL COMMENT '收礼用户ID',
  `receiver_nickname` varchar(50) DEFAULT NULL COMMENT '收礼用户昵称',
  `gift_id` int(11) NOT NULL COMMENT '礼物ID',
  `gift_count` int(11) NOT NULL DEFAULT '1' COMMENT '礼物数量',
  `total_price` decimal(10,2) NOT NULL COMMENT '总价格',
  `room_id` int(11) DEFAULT NULL COMMENT '直播间ID',
  `create_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  PRIMARY KEY (`id`),
  KEY `idx_sender` (`sender_id`),
  KEY `idx_receiver` (`receiver_id`),
  KEY `idx_gift` (`gift_id`),
  KEY `idx_room` (`room_id`),
  KEY `idx_create_time` (`create_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='礼物打赏记录表';
```

**字段说明：**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 记录唯一标识 |
| sender_id | int | 送礼用户ID |
| sender_nickname | varchar(50) | 送礼用户昵称 |
| receiver_id | int | 收礼用户ID（主播） |
| receiver_nickname | varchar(50) | 收礼用户昵称 |
| gift_id | int | 礼物ID（关联eb_gift表） |
| gift_count | int | 礼物数量 |
| total_price | decimal(10,2) | 总价格（单价×数量） |
| room_id | int | 直播间ID |
| create_time | timestamp | 打赏时间 |

### 3. 初始化数据

系统预置了20个礼物：

1. 玫瑰花 - 10钻石
2. 爱心 - 20钻石
3. 火箭 - 100钻石
4. 皇冠 - 500钻石
5. 跑车 - 1000钻石
6. 城堡 - 5000钻石
7. 棒棒糖 - 5钻石
8. 啤酒 - 15钻石
9. 蛋糕 - 50钻石
10. 钻戒 - 2000钻石
11-20. 其他礼物...

---

## 后端API接口

### 基础路径

```
http://your-server.com/api/admin/gift
```

### 1. 礼物列表（管理端）

**接口地址：** `GET /list`

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| limit | int | 否 | 每页数量，默认10 |
| name | string | 否 | 礼物名称（模糊搜索） |
| status | int | 否 | 状态（0-禁用，1-启用） |

**响应示例：**

```json
{
  "code": 200,
  "message": null,
  "data": {
    "page": 1,
    "limit": 10,
    "totalPage": 2,
    "total": 20,
    "list": [
      {
        "id": 1,
        "name": "玫瑰花",
        "image": "https://example.com/gifts/rose.png",
        "diamondPrice": "10.00",
        "intimacy": 10,
        "status": true,
        "isHeartbeat": false,
        "buyType": "diamond",
        "belong": "common",
        "remark": "浪漫玫瑰",
        "level": 1,
        "sort": 0,
        "createTime": "2025-12-30 20:25:16",
        "updateTime": "2025-12-30 20:25:16"
      }
    ]
  }
}
```

### 2. 添加礼物

**接口地址：** `POST /add`

**请求体：**

```json
{
  "name": "新礼物",
  "image": "https://example.com/gift.png",
  "diamondPrice": 100,
  "intimacy": 100,
  "isHeartbeat": false,
  "level": 1,
  "sort": 0,
  "status": true,
  "buyType": "diamond",
  "belong": "common",
  "remark": "备注信息"
}
```

**响应示例：**

```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

### 3. 编辑礼物

**接口地址：** `POST /update`

**请求体：**

```json
{
  "id": 1,
  "name": "更新后的名称",
  "image": "https://example.com/new-gift.png",
  "diamondPrice": 150,
  "intimacy": 150,
  "isHeartbeat": true,
  "level": 2,
  "sort": 1,
  "status": true,
  "buyType": "diamond",
  "belong": "live",
  "remark": "更新后的备注"
}
```

### 4. 删除礼物

**接口地址：** `POST /delete/{id}`

**路径参数：**
- `id`: 礼物ID

**响应示例：**

```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

### 5. 修改礼物状态

**接口地址：** `POST /status/{id}`

**路径参数：**
- `id`: 礼物ID

**请求参数：**
- `status`: 状态（0-禁用，1-启用）

**响应示例：**

```json
{
  "code": 200,
  "message": "状态修改成功",
  "data": null
}
```

### 6. 打赏记录列表

**接口地址：** `GET /records`

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| limit | int | 否 | 每页数量，默认20 |
| senderName | string | 否 | 送礼用户昵称（模糊搜索） |
| receiverName | string | 否 | 收礼用户昵称（模糊搜索） |
| giftName | string | 否 | 礼物名称（模糊搜索） |

**响应示例：**