gongxiangp2/docs/migration-execution-plan.md

迁移执行计划 - 阶段一和阶段二

执行日期: 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: 备份数据库 ⚠️ 重要

# 在服务器上执行备份
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

验证备份:

# 检查备份文件大小（应该大于0）
ls -lh backup_shadow_*.sql

---

步骤 2: 配置环境变量

在本地执行迁移脚本时，需要设置 DATABASE_URL:

# 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 是否已应用到数据库:

# 连接到数据库检查字段是否存在
psql -h 192.168.58.20 -U gongxiangpan -d lobechat_stage -c "\d users" | grep -E "status|departmentId"

如果字段不存在，执行 Schema 更新:

# 在项目根目录执行
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 运行迁移脚本:

# 设置环境变量
$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 验证迁移结果:

npx tsx scripts/verify-migration.ts 1

---

步骤 5: 阶段二迁移 - 部门外键关联

5.1 确保部门数据已同步 (可选，脚本会自动处理):

# 如果需要，先运行部门同步脚本
npx tsx scripts/migrate-departments-from-users.ts

5.2 运行部门外键关联迁移脚本:

# 设置环境变量（如果还没设置）
$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 验证迁移结果:

npx tsx scripts/verify-migration.ts 2

---

步骤 6: 完整验证

验证所有阶段:

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）仍然保留，不会影响现有功能

---

🚨 回滚方案

如果迁移出现问题，可以使用备份恢复：

# 恢复数据库
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