# 生产数据库升级指南 (最终版)

## 重要改进

本方案使用 PostgreSQL 的 `session_replication_role` 特性，**彻底解决外键约束问题**：

### 优势
- ✅ **无需关心插入顺序** - 可以任意顺序导入数据
- ✅ **大幅提升速度** - 跳过外键检查，导入速度提升数倍
- ✅ **事务安全** - 失败自动回滚，数据一致性有保障
- ✅ **自动验证** - 完成后自动检查数据完整性

### 原理
```sql
-- 1. 开启"上帝模式"：暂时忽略外键和触发器
SET session_replication_role = 'replica';

-- 2. 执行所有数据操作（不受外键限制）
BEGIN;
  -- 随意导入数据
COMMIT;

-- 3. 恢复正常模式
SET session_replication_role = 'origin';

-- 4. 验证数据一致性
```

## 快速开始

### 方式1：一键自动升级（推荐）

```bash
cd /Users/jiliu/WorkSpace/cosmo/backend/scripts
./upgrade_final.sh
```

### 方式2：手动执行

```bash
# 1. 备份数据库
docker exec cosmo_postgres pg_dump -U postgres -d cosmo_db > backup_$(date +%Y%m%d_%H%M%S).sql

# 2. 执行升级（Navicat 或命令行均可）
cat upgrade_production_final.sql | docker exec -i cosmo_postgres psql -U postgres -d cosmo_db
```

## 关于 display_name 字段

脚本已适配 `roles` 表的 `display_name` 字段。如果你的生产环境没有这个字段，请：

1. 打开 `upgrade_production_final.sql`
2. 找到第 20-27 行（带 display_name 的版本）
3. 注释掉它们
4. 取消注释第 29-36 行（不带 display_name 的版本）

## 权限要求

**需要 superuser 权限**才能使用 `session_replication_role`。

如果你的数据库用户不是 superuser：

```sql
-- 由 superuser 执行
ALTER USER your_user WITH SUPERUSER;

-- 升级完成后可以撤销
ALTER USER your_user WITH NOSUPERUSER;
```

## 升级内容

1. ✅ 创建/更新 roles（admin、user）
2. ✅ 添加 celestial_bodies.short_name 字段
3. ✅ 完整导入 14 条 menus 记录
4. ✅ 完整导入 16 条 role_menus 记录
5. ✅ 清空 celestial_events（由定时任务重新生成）
6. ✅ 导入 2 条 scheduled_jobs
7. ✅ 导入/更新 3 条 system_settings
8. ✅ 为现有用户分配角色
9. ✅ 自动验证数据完整性

## 数据完整性保障

脚本在恢复约束后会自动执行以下验证：

- ✅ 检查 role_menus 的 role_id 引用
- ✅ 检查 role_menus 的 menu_id 引用
- ✅ 检查 menus 的 parent_id 引用

如果发现无效引用，会输出 WARNING 信息。

## 回滚方案

```bash
# 如果升级失败，使用备份恢复
cat backup_YYYYMMDD_HHMMSS.sql | docker exec -i cosmo_postgres psql -U postgres -d cosmo_db
```

## 为什么不迁移到 MySQL？

PostgreSQL 的优势：
- 更强的 JSON 支持（你的系统用到 JSONB）
- 更好的 GIS 扩展（PostGIS，适合天文坐标）
- 更完善的窗口函数和 CTE
- 更严格的数据完整性保障

使用 `session_replication_role` 后，外键约束不再是问题！

## 常见问题

### Q: 为什么需要 superuser 权限？
A: `session_replication_role` 是为数据库复制设计的特性，PostgreSQL 限制只有 superuser 可以修改它，以防止普通用户破坏数据一致性。

### Q: 会影响生产环境吗？
A: 不会。这个设置只影响当前会话，不影响其他连接。而且在事务中执行，失败自动回滚。

### Q: 如果我没有 superuser 权限怎么办？
A:
1. 联系 DBA 临时授予权限
2. 或者使用之前的 `upgrade_production_smart.sql`（会慢一些）

### Q: 数据一致性如何保证？
A: 脚本在恢复约束后会自动验证所有外键引用。如果有问题会立即报告。

## 性能对比

| 方案 | 导入速度 | 复杂度 | 推荐度 |
|------|---------|--------|--------|
| 传统方案（严格顺序） | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ |
| DISABLE TRIGGER | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| **session_replication_role** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ |

## 升级后操作

```bash
# 1. 重启后端服务
docker restart cosmo-backend

# 2. 验证前端功能
# - 登录系统
# - 检查菜单显示
# - 测试用户功能

# 3. 手动执行定时任务（可选）
# 在后台管理 -> 定时任务设置 -> 立即执行
```

## 联系支持

如有问题，请检查：
1. PostgreSQL 日志: `docker logs cosmo_postgres --tail 100`
2. 用户权限: `SELECT current_user, usesuper FROM pg_user WHERE usename = current_user;`
3. 数据一致性验证输出