# 迁移脚本清理

**日期**: 2026-01-27  
**类型**: 清理  
**影响范围**: 开发工具

## 变更概述

归档旧的自定义迁移脚本 `run_migration.py`，统一使用 Alembic 迁移系统。

## 变更详情

### 归档文件

- `server/run_migration.py` → `server/.archive/run_migration.py.bak`

### 原因

1. **功能重复**: 旧脚本与 Alembic 功能重复
2. **维护成本**: 维护两套迁移系统增加复杂度
3. **标准化**: Alembic 是 Python 生态的标准迁移工具
4. **已完成迁移**: 项目已全面切换到 Alembic

### 当前迁移系统

**推荐使用**：

```bash
# 方式 1: 使用封装脚本（推荐）
docker exec jointo-server-app python scripts/db_migrate.py upgrade
docker exec jointo-server-app python scripts/db_migrate.py create "描述" --autogenerate
docker exec jointo-server-app python scripts/db_migrate.py current

# 方式 2: 直接使用 Alembic
docker exec jointo-server-app alembic upgrade head
docker exec jointo-server-app alembic revision --autogenerate -m "描述"
docker exec jointo-server-app alembic current
```

### 保留文件

**继续使用**：
- `server/scripts/db_migrate.py` - Alembic 友好封装脚本
- `server/alembic/` - Alembic 迁移系统
- `server/alembic.ini` - Alembic 配置

**归档保留**：
- `server/.archive/run_migration.py.bak` - 旧迁移脚本（历史参考）
- `server/app/migrations/*.py` - 旧迁移文件（历史参考）
- `server/app/migrations/sql/*.sql` - 旧 SQL 迁移（历史参考）

## 影响评估

### 开发者影响

- ✅ **无破坏性变更**: 旧脚本已不再使用
- ✅ **统一接口**: 所有迁移操作通过 Alembic 完成
- ✅ **文档完善**: 提供完整的 Alembic 使用指南

### 数据库影响

- ✅ **无影响**: 数据库状态不受影响
- ✅ **版本管理**: 使用 `alembic_version` 表管理版本
- ✅ **历史保留**: 旧的 `schema_migrations` 表保留（不再使用）

## 相关文档

- [Alembic 迁移指南](../guides/alembic-migration-guide.md)
- [Alembic 迁移系统实施](./2026-01-27-alembic-migration-system.md)
- [迁移系统规范](.claude/skills/jointo-tech-stack/references/migration.md)

## 后续计划

1. ✅ 归档旧迁移脚本
2. ⏳ 3 个月后评估是否删除归档文件
3. ⏳ 考虑添加 Makefile 简化命令（可选）

## 验证步骤

```bash
# 1. 确认旧脚本已归档
ls server/.archive/run_migration.py.bak

# 2. 确认 Alembic 正常工作
docker exec jointo-server-app alembic current

# 3. 确认封装脚本可用
docker exec jointo-server-app python scripts/db_migrate.py current
```

## 注意事项

⚠️ **不要使用旧脚本**: `run_migration.py` 已废弃，使用会导致版本管理混乱

⚠️ **容器内执行**: 所有迁移命令必须在 Docker 容器内执行

⚠️ **生产环境**: 执行迁移前务必备份数据库