gongxiangp2/scripts/migrate-product-package-README.md
chenpei 4dba93c4e5 feat: 完成任务-详情素材迁移到新逻辑
- 迁移57个老素材到新逻辑(本地zip + S3预览图)
- 优化文件命名:SPU_作者_店铺_类型.zip
- PSD文件单独存储,不打包进all.zip
- 修复下载接口,优先使用本地zip文件
- 修复预览图重复问题
- 添加迁移脚本和验证脚本
- 更新文档和迁移计划

迁移统计:
- 总素材数:77个
- 成功迁移:57个
- 新逻辑上传:18个
- 空记录:2个
2026-01-21 10:16:28 +08:00

190 lines
4.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 任务-详情老素材迁移指南
## 概述
本脚本用于将"任务-详情"老素材(只有S3预览图)迁移到新逻辑(本地zip文件)。
## 安全措施
1. **保留老数据**:不删除原有的资产记录,只新增记录
2. **分批迁移**:每次处理5个素材,避免一次性迁移导致问题
3. **演练模式**:可以先运行演练模式,不实际修改数据库
4. **完整日志**:记录每个素材的迁移状态和错误信息
5. **错误处理**:单个素材失败不影响其他素材
## 使用步骤
### 1. 数据库备份(必须!)
```bash
# 在生产服务器上备份数据库
ssh root@192.168.58.20
docker exec gongxiangpan-postgres-1 pg_dump -U gongxiangpan lobechat > /root/backup/lobechat_before_migration_$(date +%Y%m%d_%H%M%S).sql
```
### 2. 演练模式测试
```bash
# 修改脚本配置
# CONFIG.dryRun = true
# CONFIG.batchSize = 2
# 运行演练
npx tsx scripts/migrate-product-package-old-materials.ts
```
### 3. 小批量测试
```bash
# 修改脚本配置
# CONFIG.dryRun = false
# CONFIG.batchSize = 2
# 迁移2个素材
npx tsx scripts/migrate-product-package-old-materials.ts
```
### 4. 验证测试结果
- 检查首页预览图是否正常显示
- 测试下载功能是否正常
- 检查详情页是否正常
- 检查外部接口是否正常
### 5. 批量迁移
```bash
# 修改脚本配置
# CONFIG.batchSize = 10
# 多次运行,每次迁移10个
npx tsx scripts/migrate-product-package-old-materials.ts
```
## 配置说明
```typescript
const CONFIG = {
batchSize: 5, // 每批处理的素材数量
dryRun: false, // 是否为演练模式(不实际修改数据库)
skipDownload: false, // 是否跳过下载(用于测试打包逻辑)
};
```
## 迁移流程
1. 查询需要迁移的素材(zipFilePath为空或zipFileSize=0)
2. 从S3下载预览图到临时目录
3. 将预览图打包成分类zip(main.zip、sku.zip、detail.zip)
4. 打包总zip(all.zip,包含三个分类zip)
5. 新增资产记录:
- `main-preview`/`sku-preview`/`detail-preview`(指向S3预览图)
- `main`/`sku`/`detail`(指向本地zip文件)
- `all`(指向总zip文件)
6. 更新素材记录(zipFilePath、zipFileName、zipFileSize)
7. 清理临时文件
## 数据变化
### 迁移前
```
materials 表:
- zipFilePath: NULL 或 ''
- zipFileSize: 0
material_assets 表:
- assetType: 'main' (S3预览图)
- assetType: 'sku' (S3预览图)
- assetType: 'detail' (S3预览图)
- assetType: 'psd' (本地文件)
```
### 迁移后
```
materials 表:
- zipFilePath: 'uploads/materials/xxx_all_xxx.zip'
- zipFileSize: 12345678
material_assets 表(新增,老记录保留):
- assetType: 'main-preview' (S3预览图,新增)
- assetType: 'sku-preview' (S3预览图,新增)
- assetType: 'detail-preview' (S3预览图,新增)
- assetType: 'main' (本地zip,新增)
- assetType: 'sku' (本地zip,新增)
- assetType: 'detail' (本地zip,新增)
- assetType: 'all' (本地zip,新增)
- assetType: 'psd' (本地文件,保留)
```
## 回滚方案
如果迁移后发现问题,可以执行回滚:
```sql
-- 1. 删除新增的资产记录
DELETE FROM material_assets
WHERE material_id IN (
SELECT id FROM materials
WHERE "materialType" = '任务-详情'
AND "zipFilePath" IS NOT NULL
AND "zipFilePath" != ''
)
AND asset_type IN ('main-preview', 'sku-preview', 'detail-preview', 'all')
AND created_at > '2026-01-20 14:00:00'; -- 迁移开始时间
-- 2. 恢复素材记录
UPDATE materials
SET
"zipFilePath" = '',
"zipFileName" = '',
"zipFileSize" = 0
WHERE "materialType" = '任务-详情'
AND "zipFilePath" IS NOT NULL
AND "zipFilePath" != ''
AND updated_at > '2026-01-20 14:00:00'; -- 迁移开始时间
```
## 注意事项
1. **必须先备份数据库**
2. **先小批量测试,验证无误后再批量迁移**
3. **迁移过程中不要停止脚本**
4. **保留迁移日志文件**
5. **迁移完成后验证功能**
## 监控指标
- 迁移成功率
- 下载失败的文件数
- 打包失败的素材数
- 数据库更新失败的素材数
- 平均迁移时间
## 常见问题
### Q: 迁移失败怎么办?
A: 单个素材失败不影响其他素材,可以查看日志文件了解失败原因,修复后重新运行脚本。
### Q: 迁移过程中可以停止吗?
A: 可以,但建议等当前素材处理完成后再停止。已迁移的素材不会重复迁移。
### Q: 如何验证迁移是否成功?
A:
1. 检查日志文件中的成功/失败统计
2. 在首页查看素材预览图是否正常
3. 测试下载功能
4. 检查数据库中的记录是否正确
### Q: 迁移后老数据会被删除吗?
A: 不会,老数据会被保留,只是新增了新的记录。
## 联系方式
如有问题,请联系开发团队。