docs: complete documentation system (250+ files)
- System architecture and design documentation - Business module docs (ASL/AIA/PKB/RVW/DC/SSA/ST) - ASL module complete design (quality assurance, tech selection) - Platform layer and common capabilities docs - Development standards and API specifications - Deployment and operations guides - Project management and milestone tracking - Architecture implementation reports - Documentation templates and guides
This commit is contained in:
325
docs/09-架构实施/migration-scripts/README.md
Normal file
325
docs/09-架构实施/migration-scripts/README.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# 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
|
||||
|
||||
**核心理念：可重复执行 + 事务保护 + 完整验证 = 安全迁移** ⭐⭐⭐
|
||||
Reference in New Issue
Block a user