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

礼物系统完整开发文档

📋 目录

1. 系统概述
2. 数据库设计
3. 后端API接口
4. 前端页面
5. 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 表（礼物主数据表）

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 表（打赏记录表）

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-启用）

响应示例：

{
  "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

请求体：

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

响应示例：

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

3. 编辑礼物

接口地址： POST /update

请求体：

{
  "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

响应示例：

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

5. 修改礼物状态

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

路径参数：

• id: 礼物ID

请求参数：

• status: 状态（0-禁用，1-启用）

响应示例：

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

6. 打赏记录列表

接口地址： GET /records

请求参数：

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

响应示例：