- 创建统一的下载错误处理模块 (lib/download-errors.ts) - 实现13种错误类型分类和中文错误消息 - 后端统一使用 createDownloadError 创建标准化错误响应 - 前端统一使用 parseDownloadError 解析错误并显示 - 修复正式系统数据库Schema,添加产品全案相关字段和表 - 执行数据库迁移:添加 task_no, task_status, task_fetched_at 字段 - 创建 material_assets, api_keys, api_call_logs 表
257 lines
5.7 KiB
Markdown
257 lines
5.7 KiB
Markdown
# 用户无感升级方案 - 快速参考
|
||
|
||
> **核心原则**: 新旧字段并存,双写双读,逐步迁移,零数据丢失
|
||
|
||
---
|
||
|
||
## 🎯 核心策略
|
||
|
||
### 1. 双写双读原则
|
||
|
||
**所有字段变更都遵循这个原则**:
|
||
|
||
```typescript
|
||
// ✅ 双写:同时更新新旧字段
|
||
await prisma.user.update({
|
||
where: { id: userId },
|
||
data: {
|
||
department: departmentName, // 旧字段(保持兼容)
|
||
departmentId: departmentId, // 新字段(逐步迁移)
|
||
}
|
||
});
|
||
|
||
// ✅ 双读:优先使用新字段,回退到旧字段
|
||
const department = user.departmentRef?.name || user.department;
|
||
```
|
||
|
||
### 2. 数据迁移流程
|
||
|
||
```
|
||
1. Schema变更(添加新字段,保留旧字段)
|
||
↓
|
||
2. 运行迁移脚本(同步数据到新字段)
|
||
↓
|
||
3. 更新代码(双写双读)
|
||
↓
|
||
4. 验证数据一致性
|
||
↓
|
||
5. 逐步迁移前端(可选)
|
||
↓
|
||
6. 保留旧字段至少3个月
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 各阶段实施要点
|
||
|
||
### 阶段一:用户状态管理
|
||
|
||
**Schema变更**:
|
||
```prisma
|
||
model User {
|
||
// ✅ 新增字段
|
||
status String @default("pending")
|
||
lastLoginAt DateTime?
|
||
lastLoginIp String?
|
||
loginCount Int @default(0)
|
||
archivedAt DateTime?
|
||
|
||
// ✅ 保留旧字段
|
||
isActive Boolean @default(false)
|
||
}
|
||
```
|
||
|
||
**迁移脚本**: `scripts/migrate-user-status-safe.ts`
|
||
|
||
**代码更新示例**:
|
||
```typescript
|
||
// 登录API:记录审计字段
|
||
await prisma.user.update({
|
||
where: { id: userId },
|
||
data: {
|
||
lastLoginAt: new Date(),
|
||
lastLoginIp: ipAddress,
|
||
loginCount: { increment: 1 },
|
||
status: 'active', // 新字段
|
||
isActive: true, // 旧字段(保持兼容)
|
||
}
|
||
});
|
||
|
||
// 用户激活:双写
|
||
await prisma.user.update({
|
||
where: { id: userId },
|
||
data: {
|
||
status: 'active', // 新字段
|
||
isActive: true, // 旧字段(保持兼容)
|
||
}
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
### 阶段二:部门外键关联
|
||
|
||
**Schema变更**:
|
||
```prisma
|
||
model User {
|
||
// ✅ 保留旧字段
|
||
department String @default("")
|
||
|
||
// ✅ 新增字段
|
||
departmentId String?
|
||
departmentRef Department? @relation("UserDepartment", ...)
|
||
}
|
||
|
||
model Department {
|
||
id String @id @default(uuid())
|
||
name String @unique
|
||
|
||
// ✅ 新增关联
|
||
users User[] @relation("UserDepartment")
|
||
}
|
||
```
|
||
|
||
**迁移脚本**: `scripts/migrate-department-to-id-safe.ts`
|
||
|
||
**代码更新示例**:
|
||
```typescript
|
||
// 更新用户部门:双写
|
||
async function updateUserDepartment(userId: string, departmentName: string) {
|
||
const dept = await prisma.department.findUnique({
|
||
where: { name: departmentName }
|
||
});
|
||
|
||
await prisma.user.update({
|
||
where: { id: userId },
|
||
data: {
|
||
department: departmentName, // 旧字段(保持兼容)
|
||
departmentId: dept.id, // 新字段(逐步迁移)
|
||
}
|
||
});
|
||
}
|
||
|
||
// 获取用户部门:双读
|
||
async function getUserDepartment(userId: string): Promise<string | null> {
|
||
const user = await prisma.user.findUnique({
|
||
where: { id: userId },
|
||
include: { departmentRef: true }
|
||
});
|
||
|
||
// 优先使用新字段,回退到旧字段
|
||
return user.departmentRef?.name || user.department || null;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔒 安全保障
|
||
|
||
### 1. 数据库备份
|
||
|
||
**每个阶段前必须备份**:
|
||
```bash
|
||
# PostgreSQL 备份
|
||
pg_dump -h 192.168.58.20 -U username -d lobechat > backup_$(date +%Y%m%d_%H%M%S).sql
|
||
```
|
||
|
||
### 2. 迁移验证
|
||
|
||
**每个阶段后运行验证**:
|
||
```bash
|
||
# 验证所有阶段
|
||
npx tsx scripts/verify-migration.ts
|
||
|
||
# 验证特定阶段
|
||
npx tsx scripts/verify-migration.ts 1 # 阶段一
|
||
npx tsx scripts/verify-migration.ts 2 # 阶段二
|
||
```
|
||
|
||
### 3. 回滚方案
|
||
|
||
**如果出现问题,可以回滚**:
|
||
- 阶段一:将 `status` 同步回 `isActive`
|
||
- 阶段二:删除 `departmentId` 字段(保留 `department`)
|
||
- 阶段三:删除层级字段(保留 `name`)
|
||
- 阶段四:将 `SYSTEM_ADMIN` 改回 `ADMIN`
|
||
|
||
---
|
||
|
||
## 📅 实施时间表
|
||
|
||
| 阶段 | 内容 | 预计时间 | 风险 |
|
||
|------|------|---------|------|
|
||
| 阶段一 | 用户状态管理 | 1周 | 🟢 低 |
|
||
| 阶段二 | 部门外键关联 | 1-2周 | 🟡 中 |
|
||
| 阶段三 | 部门层级结构 | 1-2周 | 🟡 中 |
|
||
| 阶段四 | 角色枚举扩展 | 1周 | 🟡 中 |
|
||
|
||
**总计**: 4-6周
|
||
|
||
---
|
||
|
||
## ✅ 检查清单
|
||
|
||
### 每个阶段都需要:
|
||
|
||
- [ ] 数据库备份完成
|
||
- [ ] Schema变更已应用(`npx prisma db push`)
|
||
- [ ] 迁移脚本已执行
|
||
- [ ] 数据验证通过(`npx tsx scripts/verify-migration.ts`)
|
||
- [ ] 代码已更新(双写双读)
|
||
- [ ] 功能测试通过
|
||
- [ ] 性能测试通过
|
||
|
||
---
|
||
|
||
## 🚨 注意事项
|
||
|
||
### 绝对不能做的:
|
||
|
||
1. ❌ **删除旧字段** - 至少保留3个月
|
||
2. ❌ **修改现有字段类型** - 只添加新字段
|
||
3. ❌ **强制迁移** - 使用双写双读,逐步迁移
|
||
|
||
### 必须做的:
|
||
|
||
1. ✅ **备份数据库** - 每个阶段前必须备份
|
||
2. ✅ **验证数据** - 每个阶段后必须验证
|
||
3. ✅ **双写双读** - 所有代码更新都要双写双读
|
||
4. ✅ **保留旧字段** - 至少保留3个月
|
||
|
||
---
|
||
|
||
## 📝 快速命令参考
|
||
|
||
```bash
|
||
# 1. 备份数据库
|
||
pg_dump -h 192.168.58.20 -U username -d lobechat > backup.sql
|
||
|
||
# 2. 更新 Schema
|
||
npx prisma db push
|
||
|
||
# 3. 运行迁移脚本
|
||
npx tsx scripts/migrate-user-status-safe.ts # 阶段一
|
||
npx tsx scripts/migrate-department-to-id-safe.ts # 阶段二
|
||
|
||
# 4. 验证迁移结果
|
||
npx tsx scripts/verify-migration.ts
|
||
|
||
# 5. 生成 Prisma Client
|
||
npx prisma generate
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
- [安全迁移方案](./safe-migration-plan.md) - 详细迁移方案
|
||
- [实现情况评估](./organization-implementation-assessment.md) - 当前实现情况
|
||
- [设计方案](./organization-architecture-design.md) - 完整设计方案
|
||
|
||
---
|
||
|
||
**文档版本**: 1.0
|
||
**创建日期**: 2025-12-27
|
||
**最后更新**: 2025-12-27
|
||
|