baoxiang/mysql/init/README.md

# MySQL 数据库初始化脚本

## 概述

本目录包含完整的 MySQL 数据库初始化脚本，用于初始化互动竞猜开宝箱系统的数据库。

## 文件说明

### 执行顺序

初始化脚本需要按以下顺序执行：

```
1. 00-quick-init.sql      # 快速初始化（仅表结构）
2. 01-init-database.sql   # 数据库配置
3. 02-create-tables.sql   # 完整表结构（推荐）
4. 03-sample-data.sql     # 示例测试数据
```

### 文件详情

#### 1. `00-quick-init.sql` - 快速初始化
- **用途**: 快速创建基本表结构，用于开发和测试
- **内容**: 4个核心表（users, transactions, chests, bets）
- **特点**: 无外键约束，无索引，初始化速度快
- **适用场景**: 快速原型开发、功能测试

#### 2. `01-init-database.sql` - 数据库配置
- **用途**: 数据库基础配置和用户授权
- **内容**:
  - 设置时区为 UTC
  - 创建应用用户 `treasure_box`
  - 授权所有权限
  - 设置字符集为 UTF8MB4
- **注意**: 此文件在 Docker 容器启动时自动执行

#### 3. `02-create-tables.sql` - 完整初始化（推荐）
- **用途**: 生产级完整数据库初始化
- **内容**:
  - 4个核心表的完整结构
  - 所有索引和外键约束
  - 2个视图（活跃宝箱、用户排行）
  - 1个存储过程（获取交易历史）
  - 1个触发器（自动记录余额变化）
  - 初始数据（1个管理员、1个主播、3个用户）
- **特点**: 包含完整的业务逻辑和优化
- **适用场景**: 生产环境、完整功能测试

#### 4. `03-sample-data.sql` - 示例数据
- **用途**: 插入丰富的测试数据
- **内容**:
  - 1个管理员用户
  - 3个主播用户
  - 7个普通用户
  - 多个已完成的宝箱
  - 活跃宝箱
  - 下注记录
  - 交易流水
- **特点**: 覆盖各种业务场景
- **适用场景**: 功能演示、UI测试、数据分析

## 使用方法

### 方法 1: Docker 自动初始化（推荐）

Docker Compose 会自动按顺序执行所有脚本：

```bash
docker-compose up -d
```

脚本执行顺序：
1. MySQL 容器启动
2. 执行 `01-init-database.sql`
3. 后端服务启动
4. 执行 `02-create-tables.sql`
5. （可选）手动执行 `03-sample-data.sql`

### 方法 2: 手动执行 SQL

如果你使用本地 MySQL 或需要手动初始化：

```bash
# 1. 登录 MySQL
mysql -u root -p

# 2. 创建数据库
CREATE DATABASE treasure_box_game CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE treasure_box_game;

# 3. 执行初始化脚本
source /path/to/00-quick-init.sql;
source /path/to/02-create-tables.sql;
source /path/to/03-sample-data.sql;
```

或者直接使用 MySQL 命令行：

```bash
mysql -u root -p treasure_box_game < 00-quick-init.sql
mysql -u root -p treasure_box_game < 02-create-tables.sql
mysql -u root -p treasure_box_game < 03-sample-data.sql
```

### 方法 3: 仅插入测试数据

如果表已存在，只想添加测试数据：

```bash
mysql -u root -p treasure_box_game < 03-sample-data.sql
```

## 测试账户

执行 `02-create-tables.sql` 或 `03-sample-data.sql` 后创建的测试账户：

### 管理员账户
```
用户名: admin
邮箱: admin@treasurebox.com
密码: password123
角色: admin
余额: 1,000,000 喵币
```

### 主播账户
```
用户名: streamer_lisa
邮箱: lisa@treasurebox.com
密码: password123
角色: streamer
余额: 500,000 喵币

用户名: streamer_john
邮箱: john@treasurebox.com
密码: password123
角色: streamer
余额: 300,000 喵币
```

### 普通用户账户
```
用户名: user001
邮箱: user001@example.com
密码: password123
角色: user
余额: 100,000 喵币

用户名: rich_user
邮箱: rich@example.com
密码: password123
角色: user
余额: 1,000,000 喵币（富豪榜第一）

用户名: poor_user
邮箱: poor@example.com
密码: password123
角色: user
余额: 500 喵币（可领取低保）
```

## 数据库结构

### 表列表

1. **users** - 用户表
   - 用户基本信息
   - 角色（user/streamer/admin）
   - 余额和版本号（乐观锁）

2. **transactions** - 交易流水表
   - 所有资金变动记录
   - 类型（下注、获胜、低保等）
   - 关联ID和描述

3. **chests** - 宝箱表
   - 宝箱信息（标题、选项）
   - 状态（下注中、已封盘、已完成等）
   - 奖池金额和下注次数

4. **bets** - 下注表
   - 用户下注记录
   - 选项和金额
   - 状态和奖金

### 视图

1. **v_active_chests** - 活跃宝箱视图
   - 显示所有可下注或已封盘的宝箱
   - 包含主播信息

2. **v_user_ranking** - 用户排行视图
   - 按余额排序
   - 包含排名信息

### 存储过程

1. **sp_get_user_transactions** - 获取用户交易历史
   ```sql
   CALL sp_get_user_transactions(1, 10, 0);
   -- 获取用户ID为1的交易记录，limit 10，offset 0
   ```

### 触发器

1. **tr_users_balance_update** - 自动记录余额变化
   - 当用户余额更新时，自动记录到交易流水

## 常用查询

### 查看所有表
```sql
SHOW TABLES;
```

### 查看表结构
```sql
DESCRIBE users;
```

### 查看活跃宝箱
```sql
SELECT * FROM v_active_chests;
```

### 查看富豪榜
```sql
SELECT * FROM v_user_ranking LIMIT 10;
```

### 查看用户交易历史
```sql
SELECT * FROM transactions WHERE user_id = 1 ORDER BY created_at DESC LIMIT 20;
```

### 查看宝箱下注详情
```sql
SELECT b.*, u.username
FROM bets b
JOIN users u ON b.user_id = u.id
WHERE b.chest_id = 1;
```

## 性能优化

### 索引

已创建的索引：
- 主键索引（自动）
- 用户名、邮箱唯一索引
- 外键索引（user_id, chest_id, streamer_id）
- 状态索引（status, role）
- 时间索引（created_at）

### 连接池配置

在 `backend/app/core/config.py` 中配置：
```python
DB_POOL_SIZE = 20          # 连接池大小
DB_MAX_OVERFLOW = 30       # 最大溢出连接
DB_POOL_TIMEOUT = 30       # 超时时间（秒）
DB_POOL_RECYCLE = 3600     # 连接回收时间（秒）
```

## 字符集和排序规则

- **字符集**: UTF8MB4（完整 Unicode 支持，包括 emoji）
- **排序规则**: utf8mb4_unicode_ci
- **时区**: UTC (+00:00)

## 注意事项

1. **执行顺序**: 必须按顺序执行脚本，否则可能出现依赖错误
2. **数据清理**: 如需重新初始化，先执行 `DROP TABLE IF EXISTS`
3. **外键约束**: 完整版脚本启用了外键约束，确保数据一致性
4. **密码哈希**: 所有示例密码已使用 bcrypt 加密
5. **字符集**: 必须使用 UTF8MB4，否则可能出现编码问题

## 故障排除

### 问题 1: 外键约束错误
**解决方案**: 确保按正确顺序执行脚本，或暂时禁用外键检查：
```sql
SET FOREIGN_KEY_CHECKS = 0;
-- 执行脚本
SET FOREIGN_KEY_CHECKS = 1;
```

### 问题 2: 字符集错误
**解决方案**: 确保数据库创建时指定了正确的字符集：
```sql
CREATE DATABASE treasure_box_game
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
```

### 问题 3: 权限错误
**解决方案**: 确保使用 root 用户或有足够权限的用户执行脚本

## 备份和恢复

### 备份
```bash
mysqldump -u root -p treasure_box_game > backup.sql
```

### 恢复
```bash
mysql -u root -p treasure_box_game < backup.sql
```

## 联系信息

如有问题，请参考：
- `MYSQL_迁移指南.md` - 完整迁移文档
- `QUICKSTART.md` - 快速启动指南
- `项目完成报告.md` - 项目文档