stock-monitor/docs/guides/DATABASE_MIGRATION_GUIDE.md

# 股票监控系统数据库迁移指南

本指南将帮助您将股票监控系统从JSON文件存储迁移到MySQL数据库存储。

## 迁移概述

### 迁移前状态
- 监控列表：存储在 `config.json` 文件
- 股票缓存：存储在 `stock_cache.json` 文件
- AI分析结果：存储在各个目录的JSON文件中

### 迁移后状态
- 所有数据统一存储在 `stock_monitor` MySQL数据库中
- 支持数据查询、历史记录、缓存管理
- 更好的性能和数据一致性

## 数据库结构

### 主要数据表
1. **stocks** - 股票基础信息表
2. **stock_data** - 股票实时数据表
3. **watchlist** - 监控列表表
4. **ai_analysis** - AI分析结果表
5. **system_config** - 系统配置表
6. **data_update_log** - 数据更新日志表

详细的表结构请参考 `database_schema.sql` 文件。

## 迁移步骤

### 1. 准备数据库环境

确保MySQL服务已启动，并且数据库连接配置正确。

在 `app/config.py` 中检查数据库配置：
```python
MYSQL_HOST = os.getenv('MYSQL_HOST', 'localhost')
MYSQL_PORT = int(os.getenv('MYSQL_PORT', 3306))
MYSQL_USER = os.getenv('MYSQL_USER', 'root')
MYSQL_PASSWORD = os.getenv('MYSQL_PASSWORD', 'password')
MYSQL_DATABASE = os.getenv('MYSQL_DATABASE', 'stock_monitor')
```

### 2. 初始化数据库

运行数据库初始化脚本：

```bash
python init_database.py
```

该脚本将：
- 创建 `stock_monitor` 数据库
- 创建所有必要的数据表
- 插入系统默认配置
- 测试数据库连接

### 3. 执行数据迁移

运行数据迁移脚本：

```bash
python migrate_to_database.py
```

该脚本提供以下选项：
1. 执行完整迁移
2. 仅迁移监控列表
3. 仅迁移股票缓存
4. 仅迁移AI分析
5. 验证迁移结果

建议选择选项1执行完整迁移。

### 4. 备份原始数据

迁移脚本会自动创建原始JSON文件的备份，备份位置格式为：
```
json_backup_YYYYMMDD_HHMMSS/
```

## 系统更改

### 新增文件
- `app/database.py` - 数据库连接管理
- `app/dao/` - 数据访问对象层
- `app/services/stock_service_db.py` - 基于数据库的股票服务
- `app/services/ai_analysis_service_db.py` - 基于数据库的AI分析服务
- `init_database.py` - 数据库初始化脚本
- `migrate_to_database.py` - 数据迁移脚本

### 修改文件
- `app/api/stock_routes.py` - 更新为使用数据库服务
- `app/config.py` - 添加数据库配置

## 使用说明

### 启动系统
迁移完成后，正常启动系统即可：
```bash
uvicorn app.main:app --reload
```

### 验证迁移
1. 检查监控列表是否完整迁移
2. 验证股票数据是否正确加载
3. 确认AI分析功能正常工作
4. 测试新增和删除功能

### 功能对比
| 功能 | 迁移前 | 迁移后 |
|------|--------|--------|
| 监控列表 | JSON文件 | 数据库表 |
| 股票数据缓存 | JSON文件 | 数据库表 |
| AI分析结果 | 文件缓存 | 数据库表 |
| 历史记录 | 无 | 支持 |
| 数据查询 | 文件解析 | SQL查询 |
| 性能 | 文件I/O | 数据库优化 |
| 数据备份 | 手动 | 数据库工具 |

## 维护说明

### 数据备份
定期备份数据库：
```bash
mysqldump -u root -p stock_monitor > backup_$(date +%Y%m%d).sql
```

### 日志监控
查看 `data_update_log` 表了解数据更新状态：
```sql
SELECT * FROM data_update_log
WHERE update_status = 'failed'
ORDER BY created_at DESC;
```

### 性能优化
1. 定期清理过期的股票数据
2. 监控数据库连接池
3. 优化查询索引

## 回滚方案

如果需要回滚到JSON文件存储：

1. 恢复备份的JSON文件
2. 修改 `app/api/stock_routes.py` 中的导入：
   ```python
   # 注释掉数据库服务
   # from app.services.stock_service_db import StockServiceDB
   # from app.services.ai_analysis_service_db import AIAnalysisServiceDB

   # 恢复原始服务
   from app.services.stock_service import StockService
   from app.services.ai_analysis_service import AIAnalysisService
   ```

## 常见问题

### Q: 迁移过程中断怎么办？
A: 迁移脚本支持断点续传，重新运行会跳过已迁移的数据。

### Q: 数据库连接失败怎么解决？
A: 检查MySQL服务是否启动，连接配置是否正确，防火墙设置是否允许连接。

### Q: 迁移后数据不一致怎么办？
A: 使用验证功能检查迁移结果，或者重新执行迁移覆盖现有数据。

### Q: 如何清理测试数据？
A: 可以清空数据库表重新迁移，或者使用SQL语句删除特定数据。

## 技术支持

如果遇到迁移问题，请检查：
1. MySQL服务状态
2. 数据库权限设置
3. 网络连接
4. 日志文件中的错误信息

---

**迁移完成后，您的股票监控系统将具备更好的性能、可靠性和扩展性！**