# 数据库迁移执行指南

## 📋 迁移前检查清单

- [x] ✅ 迁移文件已创建：`prisma/migrations/20251206000000_add_soft_delete_and_favorites/migration.sql`
- [x] ✅ 迁移脚本已准备：`scripts/apply-migration.sh` 和 `scripts/apply-migration.ps1`
- [x] ✅ 安全性已确认：所有操作都是添加操作，不会影响现有素材数据
- [ ] ⏳ 数据库备份（强烈推荐）
- [ ] ⏳ 在影子系统测试迁移
- [ ] ⏳ 在生产系统执行迁移
- [ ] ⏳ 重新生成 Prisma Client

## 🚀 执行步骤

### 步骤 1：备份数据库（强烈推荐）

在服务器上执行：

```bash
# SSH 到服务器
ssh root@192.168.58.20

# 备份数据库
pg_dump "postgresql://gongxiangpan:gongxiangpan123@192.168.58.20:5432/lobechat" \
  -Fc -f "/mnt/PoolOne/backups/lobechat_before_migration_$(date +%Y%m%d_%H%M%S).dump"

# 验证备份文件
ls -lh /mnt/PoolOne/backups/lobechat_before_migration_*.dump
```

### 步骤 2：在影子系统测试迁移

**方式一：使用迁移脚本（推荐）**

```bash
# SSH 到服务器
ssh root@192.168.58.20

# 进入影子系统目录
cd /mnt/PoolOne/apps/youyidian-3d-shadow

# 确保迁移脚本有执行权限
chmod +x scripts/apply-migration.sh

# 执行迁移（确保 DATABASE_URL 指向 stage 库 lobechat_stage）
./scripts/apply-migration.sh
```

**方式二：直接执行 Prisma 迁移**

```bash
# SSH 到服务器
ssh root@192.168.58.20

# 进入影子系统目录
cd /mnt/PoolOne/apps/youyidian-3d-shadow

# 执行迁移
docker compose exec app npx prisma migrate deploy
```

### 步骤 3：验证迁移结果

在影子系统中验证新字段和表是否存在：

```bash
# 在容器内执行验证 SQL
docker compose exec app npx prisma db execute --stdin <<EOF
-- 检查 deletedAt 字段是否存在
SELECT column_name, data_type, is_nullable 
FROM information_schema.columns 
WHERE table_name = 'materials' AND column_name = 'deletedAt';

-- 检查新表是否存在
SELECT table_name 
FROM information_schema.tables 
WHERE table_name IN ('material_favorites', 'material_logs', 'material_download_logs');
EOF
```

**预期结果：**
- `deletedAt` 字段应该存在，类型为 `timestamp without time zone`，`is_nullable` 为 `YES`
- 三个新表都应该存在

### 步骤 4：测试影子系统功能

1. 访问影子系统：`http://192.168.58.20:5320`
2. 验证素材列表正常显示
3. 测试收藏功能（如果已实现 UI）
4. 检查是否有错误日志

### 步骤 5：在生产系统执行迁移

**确认测试通过后，在生产系统执行：**

```bash
# SSH 到服务器
ssh root@192.168.58.20

# 进入生产系统目录
cd /mnt/PoolOne/apps/youyidian-3d

# 执行迁移（确保 DATABASE_URL 指向生产库 lobechat）
docker compose exec app npx prisma migrate deploy
```

### 步骤 6：重新生成 Prisma Client

迁移后必须重新生成 Prisma Client：

```bash
# 在生产系统容器内执行
docker compose exec app npx prisma generate

# 重启应用容器以确保使用新的 Prisma Client
docker compose restart app
```

### 步骤 7：验证生产系统

1. 访问生产系统：`http://192.168.58.20:4320`
2. 验证素材列表正常显示
3. 测试新功能（收藏、个人中心等）
4. 检查应用日志是否有错误

## ⚠️ 注意事项

1. **执行时机**：建议在低峰时段执行，避免影响用户使用
2. **备份优先**：执行前务必备份数据库
3. **先测试后生产**：先在影子系统测试，确认无误后再在生产系统执行
4. **监控日志**：执行过程中注意观察应用日志，如有错误及时处理

## 🔄 回滚方案（如果需要）

如果迁移后出现问题，可以回滚：

```sql
-- 删除新字段（可选，不影响数据）
ALTER TABLE "materials" DROP COLUMN IF EXISTS "deletedAt";

-- 删除新表（可选，不影响 materials 表）
DROP TABLE IF EXISTS "material_favorites";
DROP TABLE IF EXISTS "material_logs";
DROP TABLE IF EXISTS "material_download_logs";
```

或者使用数据库备份恢复：

```bash
# 恢复数据库备份
pg_restore -d "postgresql://gongxiangpan:gongxiangpan123@192.168.58.20:5432/lobechat" \
  /mnt/PoolOne/backups/lobechat_before_migration_YYYYMMDD_HHMMSS.dump
```

## ✅ 迁移完成检查清单

- [ ] 数据库备份已完成
- [ ] 影子系统迁移执行成功
- [ ] 影子系统功能测试通过
- [ ] 生产系统迁移执行成功
- [ ] Prisma Client 已重新生成
- [ ] 生产系统功能测试通过
- [ ] 应用日志无错误