# 音乐库唱歌视频功能 - 部署清单

## 📋 部署前检查

### 1. 文件完整性

- [x] `开发/2026年2月4日/音乐库唱歌视频数据库修改.sql` - 数据库修改脚本
- [x] `lover/models.py` - 数据模型已更新
- [x] `lover/routers/music_library.py` - 转换 API 已添加
- [x] `lover/routers/sing.py` - 导入已更新
- [x] `test_music_library_sing.py` - 测试脚本
- [ ] `xuniYou/pages/index/index.vue` - 前端代码（待修改）

### 2. 代码质量检查

- [x] Python 语法检查 - 无错误
- [x] 数据模型验证 - 正确
- [x] API 端点验证 - 正确
- [ ] 前端代码检查 - 待修改

## 🚀 部署步骤

### 步骤 1: 备份数据库 ⚠️ 重要

```bash
# 备份整个数据库
mysqldump -u root -p fastadmin > backup_before_music_sing_$(date +%Y%m%d_%H%M%S).sql

# 或者只备份相关表
mysqldump -u root -p fastadmin nf_sing_song_video nf_song_library nf_music_library > backup_music_sing_tables_$(date +%Y%m%d_%H%M%S).sql
```

- [ ] 数据库已备份
- [ ] 备份文件已验证

### 步骤 2: 执行数据库修改（可选但推荐）

```bash
mysql -u root -p fastadmin < "开发/2026年2月4日/音乐库唱歌视频数据库修改.sql"
```

**验证**:
```sql
-- 查看表结构
SHOW COLUMNS FROM nf_sing_song_video;

-- 应该看到新字段：
-- music_library_id
-- music_source
```

- [ ] SQL 执行成功
- [ ] 新字段已添加
- [ ] 索引已创建

### 步骤 3: 重启 Python 后端

```bash
# 停止现有服务
# Ctrl+C 或关闭终端

# 启动新服务
cd lover
python -m uvicorn main:app --host 0.0.0.0 --port 30101 --reload
```

**验证**:
- [ ] 服务启动成功
- [ ] 无错误日志
- [ ] 可以访问 http://localhost:30101/docs
- [ ] 可以看到新 API: `POST /music/convert-to-song`

### 步骤 4: 测试后端 API

#### 4.1 使用 Swagger UI 测试

1. 访问 http://localhost:30101/docs
2. 找到 `POST /music/convert-to-song`
3. 点击 "Try it out"
4. 输入 `music_id: 1`
5. 点击 "Execute"

**预期结果**:
```json
{
  "code": 1,
  "message": "success",
  "data": {
    "song_id": 123,
    "title": "Sunny",
    "from_cache": false
  }
}
```

- [ ] API 调用成功
- [ ] 返回 song_id
- [ ] 数据正确

#### 4.2 使用测试脚本

```bash
# 1. 编辑测试脚本，设置 TOKEN
notepad test_music_library_sing.py

# 2. 运行测试
python test_music_library_sing.py
```

- [ ] 转换音乐 - 成功
- [ ] 拒绝外部链接 - 成功
- [ ] 生成视频 - 成功
- [ ] 查询任务 - 成功
- [ ] 获取历史 - 成功

### 步骤 5: 修改前端代码

按照 `音乐库唱歌视频前端修改指南.md` 修改前端代码。

**修改位置**: `xuniYou/pages/index/index.vue`

1. 找到 `selectMusicFromLibrary` 方法（约第 2387 行）
2. 替换方法内容
3. 添加 `generateSingVideoFromLibrary` 方法
4. 添加 `generateSingVideoWithSongId` 方法

- [ ] 前端代码已修改
- [ ] 代码语法正确
- [ ] 方法添加完整

### 步骤 6: 前端测试

#### 6.1 基本功能测试

1. 打开应用
2. 进入"唱歌"页面
3. 切换到"音乐库" tab
4. 点击一首直链音乐（Bensound）
5. 确认生成

**预期结果**:
- [ ] 显示"准备中..."
- [ ] 显示"生成中..."
- [ ] 自动切换到"历史记录" tab
- [ ] 生成成功后显示视频

#### 6.2 外部链接测试

1. 点击一首外部链接音乐（网易云）
2. 查看提示

**预期结果**:
- [ ] 显示"外部平台音乐无法生成视频"提示
- [ ] 不会开始生成

#### 6.3 历史记录测试

1. 切换到"历史记录" tab
2. 查看生成的视频

**预期结果**:
- [ ] 显示新生成的视频
- [ ] 可以播放视频
- [ ] 显示正确的标题

#### 6.4 缓存测试

1. 再次点击相同的音乐
2. 确认生成

**预期结果**:
- [ ] 立即生成成功（有缓存）
- [ ] 不需要等待
- [ ] 复用之前的视频

## ✅ 部署后验证

### 1. 功能验证

- [ ] 可以转换音乐为系统歌曲
- [ ] 可以生成唱歌视频
- [ ] 可以查看历史记录
- [ ] 外部链接被正确拒绝
- [ ] 缓存机制正常工作

### 2. 数据验证

```sql
-- 查询转换的系统歌曲
SELECT id, title, artist, gender, audio_hash
FROM nf_song_library
WHERE createtime > UNIX_TIMESTAMP(NOW() - INTERVAL 1 DAY)
ORDER BY id DESC
LIMIT 10;

-- 查询生成的视频
SELECT id, user_id, song_id, music_library_id, music_source, status
FROM nf_sing_song_video
WHERE created_at > NOW() - INTERVAL 1 DAY
ORDER BY id DESC
LIMIT 10;

-- 查询生成任务
SELECT id, user_id, task_type, status, payload
FROM nf_generation_tasks
WHERE task_type = 'video'
AND created_at > NOW() - INTERVAL 1 DAY
ORDER BY id DESC
LIMIT 10;
```

- [ ] 数据正确
- [ ] 无重复记录
- [ ] 关联正确

### 3. 性能验证

- [ ] API 响应时间 < 500ms
- [ ] 视频生成时间正常
- [ ] 无内存泄漏
- [ ] 无数据库连接泄漏

### 4. 日志检查

```bash
# 查看后端日志
tail -f lover/logs/app.log

# 查看数据库日志
tail -f /var/log/mysql/error.log
```

- [ ] 无错误日志
- [ ] 无警告日志
- [ ] API 调用正常

## 🔄 回滚计划

如果部署失败，按以下步骤回滚：

### 1. 恢复数据库

```bash
# 恢复备份
mysql -u root -p fastadmin < backup_before_music_sing_YYYYMMDD_HHMMSS.sql
```

### 2. 恢复代码

```bash
# 使用 Git 回滚
git checkout HEAD~1 lover/models.py
git checkout HEAD~1 lover/routers/music_library.py
git checkout HEAD~1 lover/routers/sing.py
git checkout HEAD~1 xuniYou/pages/index/index.vue
```

### 3. 重启服务

```bash
cd lover
python -m uvicorn main:app --host 0.0.0.0 --port 30101 --reload
```

## 📊 部署结果

### 成功标准

- ✅ 所有测试通过
- ✅ 无错误日志
- ✅ 性能正常
- ✅ 数据完整
- ✅ 用户体验良好

### 部署记录

- **部署日期**: ___________
- **部署人员**: ___________
- **部署结果**: [ ] 成功 [ ] 失败
- **问题记录**: ___________
- **解决方案**: ___________

## 📞 问题处理

### 常见问题

**问题 1: 转换 API 返回 404**
```
解决方案：
1. 检查后端是否重启
2. 检查 API 路由是否正确
3. 查看后端日志
```

**问题 2: 生成视频失败**
```
解决方案：
1. 检查视频生成次数
2. 检查音乐 URL 是否可访问
3. 检查恋人形象是否存在
4. 查看任务错误信息
```

**问题 3: 前端无法调用 API**
```
解决方案：
1. 检查 TOKEN 是否有效
2. 检查 API 地址是否正确
3. 检查网络连接
4. 查看浏览器控制台
```

**问题 4: 历史记录不显示**
```
解决方案：
1. 刷新页面
2. 检查 API 返回数据
3. 检查数据库记录
4. 查看前端日志
```

## 📝 部署签名

- **部署人员**: ___________
- **审核人员**: ___________
- **部署日期**: ___________
- **签名**: ___________

---

**部署清单版本**: 1.0  
**更新时间**: 2026-02-04  
**状态**: 待部署