cosmo/backend/scripts/UPGRADE_GUIDE.md

# 生产环境数据库升级指南

## 概述
此升级脚本包含以下变更：
1. 在 `celestial_bodies` 表增加 `short_name` 字段
2. 完整导入 `menus` 和 `role_menus` 表
3. 清空 `celestial_events` 表（将由定时任务重新生成）
4. 完整导入 `scheduled_jobs` 表
5. 导入/更新 `system_settings` 表
6. 保留 `user_follows` 表的现有数据

## 升级前准备

### 1. 备份数据库
```bash
# 在生产服务器上执行
pg_dump -U postgres -d cosmo_db > backup_$(date +%Y%m%d_%H%M%S).sql
```

### 2. 测试升级脚本（推荐）
```bash
# 在测试环境先运行
psql -U postgres -d cosmo_db_test < upgrade_production.sql
```

## 执行升级

### 方式1：直接执行SQL文件
```bash
psql -U postgres -d cosmo_db < upgrade_production.sql
```

### 方式2：通过Docker容器执行
```bash
docker cp upgrade_production.sql <container_name>:/tmp/
docker exec -it <container_name> psql -U postgres -d cosmo_db -f /tmp/upgrade_production.sql
```

### 方式3：交互式执行（推荐，便于观察）
```bash
psql -U postgres -d cosmo_db
\i upgrade_production.sql
```

## 升级后验证

脚本会自动输出验证信息，检查以下内容：

1. **celestial_bodies.short_name 字段**：应该存在
2. **menus 数量**：应该是 14 条
3. **role_menus 数量**：应该是 16 条
4. **scheduled_jobs 数量**：应该是 2 条
5. **system_settings 数量**：应该至少 3 条

### 手动验证命令
```sql
-- 检查 short_name 字段
\d celestial_bodies

-- 检查菜单数据
SELECT id, name, title, path FROM menus ORDER BY parent_id NULLS FIRST, sort_order;

-- 检查角色菜单关联
SELECT r.name as role, m.title as menu
FROM role_menus rm
JOIN roles r ON rm.role_id = r.id
JOIN menus m ON rm.menu_id = m.id
ORDER BY r.name, m.sort_order;

-- 检查定时任务
SELECT id, name, is_active, predefined_function FROM scheduled_jobs;

-- 检查系统设置
SELECT key, value, value_type FROM system_settings;
```

## 升级详情

### 1. celestial_bodies 表升级
- 增加 `short_name VARCHAR(50)` 字段
- 如果字段已存在，则跳过

### 2. menus 和 role_menus 导入
- **重要**：会清空现有菜单数据
- 导入 14 条菜单记录
- 导入 16 条角色-菜单关联记录
- 管理员可访问所有菜单
- 普通用户只能访问：个人资料、我的天体

### 3. celestial_events 清空
- 清空所有现有天体事件
- 数据会由定时任务 `calculate_planetary_events` 自动重新生成

### 4. scheduled_jobs 导入
导入2个定时任务：
- **每日更新天体位置数据**（已禁用）
  - Cron: `0 2 * * *`（每天凌晨2点）
  - 可通过后台管理界面手动执行

- **获取主要天体事件**（已启用）
  - Cron: `0 3 1 * *`（每月1日凌晨3点）
  - 自动计算未来一年的天文事件

### 5. system_settings 导入
导入3个系统设置：
- `view_mode`: solar（默认视图模式）
- `nasa_api_timeout`: 120（NASA API超时时间）
- `auto_download_positions`: False（自动下载位置数据开关）

使用 `ON CONFLICT` 策略，如果键已存在则更新值。

### 6. user_follows 保留
- **不会修改此表**
- 保留所有用户关注数据

## 回滚方案

如果升级失败，使用备份恢复：

```bash
# 方式1：完整恢复
psql -U postgres -d cosmo_db < backup_YYYYMMDD_HHMMSS.sql

# 方式2：选择性回滚
# 如果只是某些表有问题，可以只恢复特定表
pg_restore -U postgres -d cosmo_db -t menus -t role_menus backup.dump
```

## 注意事项

1. **事务安全**：整个脚本在一个事务中执行，失败会自动回滚
2. **外键约束**：menus 表有自引用外键，脚本已处理
3. **数据清空**：menus、role_menus、celestial_events、scheduled_jobs 会被清空
4. **用户数据**：user_follows 不会被修改
5. **定时任务**：位置数据下载任务默认禁用，需要手动执行或启用

## 升级后操作

1. **重启应用服务**
   ```bash
   # 重启后端服务
   systemctl restart cosmo-backend
   # 或 docker restart cosmo-backend
   ```

2. **手动执行位置数据下载**（如需要）
   - 登录后台管理系统
   - 进入"定时任务设置"
   - 找到"每日更新天体位置数据"
   - 点击"立即执行"

3. **验证前端功能**
   - 登录系统
   - 检查菜单是否正确显示
   - 测试个人资料页面
   - 测试我的天体页面

## 常见问题

### Q: 升级过程中断怎么办？
A: 由于使用了事务，中断会自动回滚。使用备份重新开始。

### Q: 如何只导入某个表？
A: 从脚本中复制对应表的部分，单独执行。

### Q: 线上已有自定义菜单怎么办？
A: 脚本会清空菜单，请在升级前导出自定义菜单，升级后手动添加。

### Q: 定时任务什么时候开始执行？
A: 天体事件任务会在下个月1日凌晨3点执行。位置数据任务需手动启用或执行。

## 联系支持

如遇问题，请检查：
1. 数据库日志
2. 应用程序日志
3. 脚本执行输出