ea9076df45
- 创建统一的下载错误处理模块 (lib/download-errors.ts) - 实现13种错误类型分类和中文错误消息 - 后端统一使用 createDownloadError 创建标准化错误响应 - 前端统一使用 parseDownloadError 解析错误并显示 - 修复正式系统数据库Schema，添加产品全案相关字段和表 - 执行数据库迁移：添加 task_no, task_status, task_fetched_at 字段 - 创建 material_assets, api_keys, api_call_logs 表
249 lines
5.9 KiB
Markdown
249 lines
5.9 KiB
Markdown
# 迁移执行计划 - 阶段一和阶段二
|
||
|
||
> **执行日期**: 2025-12-27
|
||
> **目标环境**: 影子系统（数据库：`lobechat_stage`）
|
||
> **执行阶段**: 阶段一（用户状态管理）+ 阶段二（部门外键关联）
|
||
|
||
---
|
||
|
||
## ✅ 准备工作检查
|
||
|
||
### 1. Schema 状态
|
||
- ✅ 阶段一字段已定义：`status`, `lastLoginAt`, `lastLoginIp`, `loginCount`, `archivedAt`
|
||
- ✅ 阶段二字段已定义：`departmentId`, `departmentRef`
|
||
- ✅ 迁移脚本已准备：`migrate-user-status-safe.ts`, `migrate-department-to-id-safe.ts`
|
||
- ✅ 验证脚本已准备：`verify-migration.ts`
|
||
|
||
### 2. 数据库信息
|
||
- **影子系统数据库**: `lobechat_stage` @ `192.168.58.20:5432`
|
||
- **数据库用户**: `gongxiangpan`
|
||
- **数据库密码**: `gongxiangpan123`
|
||
- **连接字符串**: `postgresql://gongxiangpan:gongxiangpan123@192.168.58.20:5432/lobechat_stage`
|
||
|
||
---
|
||
|
||
## 📋 执行步骤
|
||
|
||
### 步骤 1: 备份数据库 ⚠️ **重要**
|
||
|
||
```bash
|
||
# 在服务器上执行备份
|
||
ssh root@192.168.58.20 "docker exec gongxiangpan-postgres-1 pg_dump -U gongxiangpan -d lobechat_stage -Fc -f /tmp/lobechat_stage_backup_$(date +%Y%m%d_%H%M%S).dump"
|
||
|
||
# 或者从本地执行
|
||
pg_dump -h 192.168.58.20 -U gongxiangpan -d lobechat_stage > backup_shadow_$(date +%Y%m%d_%H%M%S).sql
|
||
```
|
||
|
||
**验证备份**:
|
||
```bash
|
||
# 检查备份文件大小（应该大于0）
|
||
ls -lh backup_shadow_*.sql
|
||
```
|
||
|
||
---
|
||
|
||
### 步骤 2: 配置环境变量
|
||
|
||
**在本地执行迁移脚本时，需要设置 DATABASE_URL**:
|
||
|
||
```bash
|
||
# Windows PowerShell
|
||
$env:DATABASE_URL="postgresql://gongxiangpan:gongxiangpan123@192.168.58.20:5432/lobechat_stage"
|
||
|
||
# 或者在服务器容器内执行（推荐）
|
||
ssh root@192.168.58.20 "docker exec -it youyidian-3d-shadow bash"
|
||
# 然后在容器内执行迁移脚本
|
||
```
|
||
|
||
---
|
||
|
||
### 步骤 3: 应用 Schema 变更（如果还未应用）
|
||
|
||
**检查 Schema 是否已应用到数据库**:
|
||
|
||
```bash
|
||
# 连接到数据库检查字段是否存在
|
||
psql -h 192.168.58.20 -U gongxiangpan -d lobechat_stage -c "\d users" | grep -E "status|departmentId"
|
||
```
|
||
|
||
**如果字段不存在，执行 Schema 更新**:
|
||
|
||
```bash
|
||
# 在项目根目录执行
|
||
cd d:\gongxiangp2
|
||
$env:DATABASE_URL="postgresql://gongxiangpan:gongxiangpan123@192.168.58.20:5432/lobechat_stage"
|
||
npx prisma db push
|
||
npx prisma generate
|
||
```
|
||
|
||
---
|
||
|
||
### 步骤 4: 阶段一迁移 - 用户状态管理
|
||
|
||
**4.1 运行迁移脚本**:
|
||
|
||
```bash
|
||
# 设置环境变量
|
||
$env:DATABASE_URL="postgresql://gongxiangpan:gongxiangpan123@192.168.58.20:5432/lobechat_stage"
|
||
|
||
# 运行迁移脚本
|
||
npx tsx scripts/migrate-user-status-safe.ts
|
||
```
|
||
|
||
**预期输出**:
|
||
```
|
||
🚀 开始用户状态迁移...
|
||
📊 当前用户统计:
|
||
总用户数: X
|
||
已激活 (isActive=true): X
|
||
未激活 (isActive=false): X
|
||
✅ 已激活用户迁移: X 个用户设置为 status='active'
|
||
✅ 未激活用户迁移: X 个用户设置为 status='pending'
|
||
🔍 验证数据一致性...
|
||
✅ 数据一致性验证通过
|
||
✅ 迁移完成
|
||
```
|
||
|
||
**4.2 验证迁移结果**:
|
||
|
||
```bash
|
||
npx tsx scripts/verify-migration.ts 1
|
||
```
|
||
|
||
---
|
||
|
||
### 步骤 5: 阶段二迁移 - 部门外键关联
|
||
|
||
**5.1 确保部门数据已同步** (可选，脚本会自动处理):
|
||
|
||
```bash
|
||
# 如果需要，先运行部门同步脚本
|
||
npx tsx scripts/migrate-departments-from-users.ts
|
||
```
|
||
|
||
**5.2 运行部门外键关联迁移脚本**:
|
||
|
||
```bash
|
||
# 设置环境变量（如果还没设置）
|
||
$env:DATABASE_URL="postgresql://gongxiangpan:gongxiangpan123@192.168.58.20:5432/lobechat_stage"
|
||
|
||
# 运行迁移脚本
|
||
npx tsx scripts/migrate-department-to-id-safe.ts
|
||
```
|
||
|
||
**预期输出**:
|
||
```
|
||
🚀 开始部门外键关联迁移...
|
||
📋 步骤1: 同步部门到 Department 表...
|
||
发现 X 个用户部门
|
||
✅ 所有部门都已存在于 Department 表中
|
||
📋 步骤2: 迁移用户部门关联...
|
||
需要迁移 X 个用户
|
||
✅ 成功迁移 X 个用户
|
||
✅ 迁移完成
|
||
```
|
||
|
||
**5.3 验证迁移结果**:
|
||
|
||
```bash
|
||
npx tsx scripts/verify-migration.ts 2
|
||
```
|
||
|
||
---
|
||
|
||
### 步骤 6: 完整验证
|
||
|
||
**验证所有阶段**:
|
||
|
||
```bash
|
||
npx tsx scripts/verify-migration.ts
|
||
```
|
||
|
||
**预期输出**:
|
||
```
|
||
🔍 验证阶段一：用户状态管理...
|
||
统计:
|
||
总用户数: X
|
||
active: X
|
||
pending: X
|
||
✅ 验证通过
|
||
|
||
🔍 验证阶段二：部门外键关联...
|
||
统计:
|
||
总用户数: X
|
||
有部门的用户: X
|
||
已设置 departmentId: X
|
||
✅ 验证通过
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 功能测试
|
||
|
||
### 测试 1: 用户登录
|
||
1. 访问影子系统：`http://192.168.58.20:5320/login`
|
||
2. 使用已激活用户登录
|
||
3. 检查登录是否成功
|
||
4. 验证 `lastLoginAt` 和 `loginCount` 是否更新
|
||
|
||
### 测试 2: 用户状态切换
|
||
1. 以管理员身份登录
|
||
2. 进入用户管理页面
|
||
3. 切换用户状态（激活/暂停/归档）
|
||
4. 验证状态切换正常
|
||
|
||
### 测试 3: 部门关联查询
|
||
1. 访问用户列表API：`/api/admin/users`
|
||
2. 检查返回数据是否包含 `departmentRef` 字段
|
||
3. 验证 `departmentRef.name` 与 `department` 字段一致
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. **数据库备份**: 执行前必须备份，这是不可逆操作
|
||
2. **环境变量**: 确保 `DATABASE_URL` 指向正确的数据库（影子系统）
|
||
3. **幂等性**: 迁移脚本可以重复执行，不会重复迁移
|
||
4. **向后兼容**: 旧字段（`isActive`, `department`）仍然保留，不会影响现有功能
|
||
|
||
---
|
||
|
||
## 🚨 回滚方案
|
||
|
||
如果迁移出现问题，可以使用备份恢复：
|
||
|
||
```bash
|
||
# 恢复数据库
|
||
pg_restore -h 192.168.58.20 -U gongxiangpan -d lobechat_stage backup_shadow_*.dump
|
||
|
||
# 或者
|
||
psql -h 192.168.58.20 -U gongxiangpan -d lobechat_stage < backup_shadow_*.sql
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 检查清单
|
||
|
||
迁移前：
|
||
- [ ] 数据库备份完成
|
||
- [ ] 环境变量配置正确
|
||
- [ ] Schema 已更新（如果未更新）
|
||
|
||
迁移中：
|
||
- [ ] 阶段一迁移脚本执行成功
|
||
- [ ] 阶段一验证通过
|
||
- [ ] 阶段二迁移脚本执行成功
|
||
- [ ] 阶段二验证通过
|
||
|
||
迁移后：
|
||
- [ ] 完整验证通过
|
||
- [ ] 功能测试通过
|
||
- [ ] 没有发现数据不一致
|
||
|
||
---
|
||
|
||
**文档版本**: 1.0
|
||
**创建日期**: 2025-12-27
|
||
**最后更新**: 2025-12-27
|
||
|