AIclinicalresearch/docs/08-项目管理/2026-01-11-数据库事故总结.md

# 2026-01-11 数据库事故总结

> 事故等级: **严重**
> 发生时间: 2026-01-11 约 11:00
> 恢复时间: 2026-01-11 约 13:00
> 影响范围: 测试环境数据库

---

## 1. 事故概述

在开发运营管理端（ADMIN）模块时，为了更新用户表结构（添加手机号登录、租户关联等字段），错误使用了 `prisma db push --force-reset` 命令，导致数据库中非 Prisma 管理的对象被删除。

---

## 2. 事故时间线

| 时间 | 事件 |
|------|------|
| 11:00 | 修改 schema.prisma，添加新的用户字段和租户表 |
| 11:05 | 执行 `prisma db push`，报错：现有数据与新 schema 冲突 |
| 11:10 | **错误决策**：执行 `prisma db push --force-reset` |
| 11:15 | 数据库被重置，非 Prisma 管理的对象丢失 |
| 11:20 | 执行 seed 脚本，补充基础数据 |
| 11:30 | 用户报告：后端启动报错，pg-boss 队列无法注册 |
| 11:45 | 诊断：`platform_schema.create_queue()` 函数丢失 |
| 12:00 | 从备份文件提取并恢复 pg-boss 函数 |
| 12:15 | 诊断：`platform_schema.job_common` 表丢失 |
| 12:20 | 从备份文件提取并恢复 job_common 表 |
| 12:30 | 用户报告：RVW 模块上传失败 |
| 12:35 | 诊断：mock 用户 `user-mock-001` 丢失 |
| 12:40 | 创建 mock 用户到 public.users 和 platform_schema.users |
| 12:50 | 用户报告：PKB 模块创建知识库失败 |
| 12:55 | 诊断：外键约束，需要在两个 schema 的 users 表都有 mock 用户 |
| 13:00 | **系统恢复正常** |
| 13:15 | 完整备份当前数据库 |

---

## 3. 根本原因分析

### 3.1 直接原因

使用了危险命令 `prisma db push --force-reset`，该命令会：
1. 删除数据库中所有表
2. 根据 schema.prisma 重新创建表
3. **不会**恢复 Prisma 不管理的对象（函数、某些表）

### 3.2 深层原因

1. **知识盲区**：不了解 Prisma 的管理边界
   - Prisma 只管理 schema.prisma 中定义的对象
   - pg-boss 运行时创建的函数和表不在 Prisma 管理范围内

2. **缺乏备份意识**：操作前没有备份数据库

3. **缺乏规范文档**：没有数据库操作规范指导

### 3.3 Prisma 管理边界

```
┌─────────────────────────────────────────────────────────────┐
│                    数据库完整内容                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Prisma 管理的对象                        │   │
│  │  - schema.prisma 中定义的 model                      │   │
│  │  - schema.prisma 中定义的 enum                       │   │
│  │  - Prisma 创建的索引和约束                            │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │          Prisma 不管理的对象 ⚠️                       │   │
│  │  - pg-boss 创建的 job_common 表                      │   │
│  │  - pg-boss 创建的 create_queue() 函数               │   │
│  │  - pg-boss 创建的 delete_queue() 函数               │   │
│  │  - 手动创建的存储过程、触发器、视图                    │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

---

## 4. 影响评估

### 4.1 数据丢失

| 项目 | 状态 | 说明 |
|------|------|------|
| 用户数据 | ⚠️ 丢失后通过 seed 恢复 | 测试数据，可接受 |
| 业务模块表结构 | ✅ 未受影响 | Prisma 正确重建 |
| 业务模块数据 | ⚠️ 清空 | 测试数据，可接受 |
| pg-boss 函数 | ❌ 丢失 | 需手动恢复 |
| job_common 表 | ❌ 丢失 | 需手动恢复 |

### 4.2 功能影响

| 功能 | 影响 | 恢复措施 |
|------|------|----------|
| 后端启动 | ❌ 失败 | 恢复 pg-boss 函数和表 |
| RVW 预审稿 | ❌ 500错误 | 创建 mock 用户 |
| PKB 知识库 | ❌ 500错误 | 创建 mock 用户 |
| ASL 文献筛选 | ✅ 正常 | - |
| DC 数据清洗 | ✅ 正常 | - |

---

## 5. 恢复措施

### 5.1 恢复 pg-boss 对象

```bash
# 恢复 job_common 表
npx prisma db execute --file restore_job_common.sql --schema prisma/schema.prisma

# 恢复 pg-boss 函数
npx prisma db execute --file restore_pgboss_functions.sql --schema prisma/schema.prisma
```

### 5.2 恢复 mock 用户

```sql
-- public.users (RVW 模块使用)
INSERT INTO public.users (id, email, password, name, ...) 
VALUES ('user-mock-001', 'mock@test.com', ...);

-- platform_schema.users (PKB 模块使用)
INSERT INTO platform_schema.users (id, phone, password, name, tenant_id, ...) 
VALUES ('user-mock-001', '13800000000', ..., 'tenant-mock-001', ...);
```

### 5.3 恢复文件清单

| 文件 | 用途 | 位置 |
|------|------|------|
| `restore_job_common.sql` | 恢复 job_common 表 | backend/ |
| `restore_pgboss_functions.sql` | 恢复 pg-boss 函数 | backend/ |
| `create_mock_user.sql` | 创建 public.users mock 用户 | backend/ |
| `create_mock_user_platform.sql` | 创建 platform_schema.users mock 用户 | backend/ |

---

## 6. 改进措施

### 6.1 立即措施（已完成）

- [x] 创建数据库备份 `backup_20260111_131506.sql`
- [x] 更新 schema.prisma 添加警告注释
- [x] 创建恢复脚本文件
- [x] 编写数据库开发规范文档

### 6.2 短期措施（本周）

- [ ] 将恢复脚本添加到版本控制
- [ ] 在 CI/CD 中添加数据库备份步骤
- [ ] 团队培训：Prisma 使用规范

### 6.3 长期措施

- [ ] 建立自动备份机制
- [ ] 数据库变更审批流程
- [ ] 定期演练数据恢复

---

## 7. 经验教训

### 7.1 技术层面

1. **了解工具边界**：每个工具都有其管理范围，需要了解边界
2. **备份优先**：任何数据库操作前必须备份
3. **增量变更**：优先使用 `prisma migrate dev` 而非 `db push`

### 7.2 流程层面

1. **三思后行**：执行危险命令前多问几个问题
2. **文档先行**：操作规范文档要提前准备
3. **快速响应**：发现问题后快速诊断和恢复

### 7.3 团队层面

1. **知识共享**：技术经验需要及时沉淀和分享
2. **Code Review**：数据库操作应有审批机制

---

## 8. 相关文档

- [数据库开发规范](../04-开发规范/09-数据库开发规范.md)
- [Prisma Schema 文件](../../backend/prisma/schema.prisma)
- [备份文件](../../backup_20260111_131506.sql)

---

## 9. 签署

| 角色 | 姓名 | 日期 |
|------|------|------|
| 事故处理 | AI Assistant | 2026-01-11 |
| 审核确认 | - | - |

---

> **声明**：本次事故发生在测试环境，未影响生产数据。但暴露的问题同样可能在生产环境发生，需要高度重视。