# Schema迁移脚本使用指南

> **版本：** V1.0  
> **创建日期：** 2025-11-09  
> **迁移目标：** 从public schema迁移到10个隔离Schema

---

## 📋 脚本清单

| # | 脚本名称 | 说明 | 预计时间 | 前置依赖 |
|---|---------|------|---------|---------|
| 1 | `001-create-all-10-schemas.sql` | 创建10个Schema（3详细+7空） | 5秒 | 无 |
| 2 | `002-migrate-platform.sql` | 迁移platform_schema（1个表：users） | 15分钟 | 001 |
| 3 | `003-migrate-aia.sql` | 迁移aia_schema（5个表：对话相关） | 30分钟 | 001, 002 |
| 4 | `004-migrate-pkb.sql` | 迁移pkb_schema（5个表：知识库相关） | 30分钟 | 001, 002 |
| 5 | `005-validate-all.sql` | 全局验证和数据完整性检查 | 10分钟 | 001-004 |

**总计：** 约1.5小时

---

## 🚀 执行步骤

### 前置准备

1. **备份数据库（强烈建议）**
   ```bash
   pg_dump -U postgres -d your_database > backup_$(date +%Y%m%d_%H%M%S).sql
   ```

2. **确认数据库连接**
   ```bash
   # 确保DATABASE_URL环境变量正确
   echo $DATABASE_URL
   # 或查看 .env 文件
   ```

3. **确认当前表结构**
   ```sql
   SELECT tablename FROM pg_tables WHERE schemaname = 'public';
   ```

---

### 执行迁移

#### 方法1：使用psql命令（推荐）

```bash
# 进入脚本目录
cd AIclinicalresearch/docs/09-架构实施/migration-scripts

# 依次执行脚本
psql $DATABASE_URL -f 001-create-all-10-schemas.sql
psql $DATABASE_URL -f 002-migrate-platform.sql
psql $DATABASE_URL -f 003-migrate-aia.sql
psql $DATABASE_URL -f 004-migrate-pkb.sql
psql $DATABASE_URL -f 005-validate-all.sql
```

#### 方法2：一次性执行所有脚本

```bash
# 创建执行脚本
cat 001-create-all-10-schemas.sql \
    002-migrate-platform.sql \
    003-migrate-aia.sql \
    004-migrate-pkb.sql \
    005-validate-all.sql \
    | psql $DATABASE_URL
```

#### 方法3：使用数据库客户端（如DBeaver、pgAdmin）

1. 打开数据库客户端
2. 连接到目标数据库
3. 依次打开并执行每个SQL文件

---

## ✅ 验证清单

### 执行001后

- [ ] 10个Schema全部创建成功
- [ ] 每个Schema都有注释说明

```sql
-- 验证SQL
SELECT nspname, pg_catalog.obj_description(oid, 'pg_namespace')
FROM pg_namespace
WHERE nspname LIKE '%_schema'
ORDER BY nspname;
```

### 执行002后

- [ ] platform_schema.users表创建成功
- [ ] 数据从public.users完整迁移
- [ ] 4个索引创建成功

```sql
-- 验证SQL
SELECT COUNT(*) AS public_count FROM public.users;
SELECT COUNT(*) AS platform_count FROM platform_schema.users;
```

### 执行003后

- [ ] aia_schema的5个表创建成功
- [ ] 数据完整迁移
- [ ] 外键约束正确建立

```sql
-- 验证SQL
SELECT COUNT(*) FROM aia_schema.projects;
SELECT COUNT(*) FROM aia_schema.conversations;
```

### 执行004后

- [ ] pkb_schema的5个表创建成功
- [ ] 包含Phase 2全文阅读字段
- [ ] 数据完整迁移

```sql
-- 验证SQL
SELECT COUNT(*) FROM pkb_schema.knowledge_bases;
SELECT COUNT(*) FROM pkb_schema.documents;
```

### 执行005后

- [ ] 所有数据量对比一致
- [ ] 跨Schema外键引用有效
- [ ] 无数据丢失

---

## 📊 迁移后数据分布

### Platform Schema
```
platform_schema
└── users (1表)
```

### AIA Schema
```
aia_schema
├── projects
├── conversations
├── messages
├── general_conversations
└── general_messages (5表)
```

### PKB Schema
```
pkb_schema
├── knowledge_bases
├── documents
├── batch_tasks
├── batch_results
└── task_templates (5表)
```

### 空Schema（7个）
```
asl_schema      (AI智能文献 - Week 3设计)
common_schema   (通用能力层)
dc_schema       (数据清洗)
rvw_schema      (审稿系统)
admin_schema    (运营管理)
ssa_schema      (智能统计分析)
st_schema       (统计分析工具)
```

---

## ⚠️ 注意事项

### 1. 事务保护

所有迁移脚本都使用了事务（BEGIN/COMMIT）：
- 成功：全部提交
- 失败：自动回滚，无部分迁移

### 2. 幂等性

所有脚本支持重复执行：
- 使用 `IF NOT EXISTS` 创建对象
- 使用 `ON CONFLICT DO NOTHING` 插入数据

### 3. public schema保留

迁移后**不会删除** public schema中的原表：
- 原因：方便回滚和对比验证
- 清理：待所有验证通过后，再决定是否删除

### 4. 外键约束

支持跨Schema外键：
- 所有业务表引用 `platform_schema.users(id)`
- PostgreSQL原生支持，无需特殊配置

---

## 🔧 故障排查

### 问题1：连接被拒绝

**错误：** `connection refused`

**解决：**
```bash
# 检查PostgreSQL服务
sudo systemctl status postgresql

# 启动服务
sudo systemctl start postgresql
```

### 问题2：权限不足

**错误：** `permission denied to create schema`

**解决：**
```sql
-- 授予权限
GRANT CREATE ON DATABASE your_database TO your_user;
```

### 问题3：外键约束失败

**错误：** `violates foreign key constraint`

**解决：**
- 确保先执行 002（platform）再执行 003/004（aia/pkb）
- 检查是否有孤立的user_id

### 问题4：数据量不一致

**错误：** 验证脚本报告数据量不一致

**解决：**
1. 检查是否有迁移过程中新增的数据
2. 使用ID对比检查具体差异：
   ```sql
   -- 找出差异的ID
   SELECT id FROM public.users
   EXCEPT
   SELECT id FROM platform_schema.users;
   ```

---

## 📝 回滚方案

### 快速回滚（推荐）

```sql
-- 删除所有新建的Schema（会级联删除所有表和数据）
DROP SCHEMA IF EXISTS platform_schema CASCADE;
DROP SCHEMA IF EXISTS aia_schema CASCADE;
DROP SCHEMA IF EXISTS pkb_schema CASCADE;
DROP SCHEMA IF EXISTS asl_schema CASCADE;
DROP SCHEMA IF EXISTS common_schema CASCADE;
DROP SCHEMA IF EXISTS dc_schema CASCADE;
DROP SCHEMA IF EXISTS rvw_schema CASCADE;
DROP SCHEMA IF EXISTS admin_schema CASCADE;
DROP SCHEMA IF EXISTS ssa_schema CASCADE;
DROP SCHEMA IF EXISTS st_schema CASCADE;
```

### 从备份恢复

```bash
# 恢复备份
psql $DATABASE_URL < backup_20251109_100000.sql
```

---

## 📂 后续步骤

迁移完成后，需要：

1. **更新Prisma配置** → 见任务9
   - 更新 `backend/prisma/schema.prisma`
   - 添加 `multiSchema` 预览特性
   - 为3个Schema定义模型

2. **生成Prisma Client**
   ```bash
   cd backend
   npx prisma generate
   ```

3. **更新代码** → 见任务12
   - 所有数据库查询使用新Schema
   - 测试现有功能

4. **运行测试** → 见任务8
   - 测试AI智能问答
   - 测试知识库功能

---

## 📞 获取帮助

如果遇到问题：

1. **查看日志** - psql会输出详细的执行信息和错误
2. **检查文档** - 参考 `09-架构实施/01-Schema隔离架构设计（10个）.md`
3. **验证数据** - 运行 `005-validate-all.sql`

---

**创建人：** AI助手  
**最后更新：** 2025-11-09  
**版本：** V1.0

**核心理念：可重复执行 + 事务保护 + 完整验证 = 安全迁移** ⭐⭐⭐