# 迁移脚本整理与归档

**日期**: 2026-01-24  
**类型**: 项目维护  
**影响范围**: 开发工具

## 变更概述

整理了项目中的数据库迁移脚本和调试工具，明确了迁移策略，归档了临时调试脚本。

## 变更内容

### 1. 保留的迁移工具

#### `migrate_db.sh`
- **保留原因**: 提供友好的命令行界面
- **功能**: 
  - 增量迁移（安全）
  - 清空迁移（危险操作，需确认）
  - 自动检查 Docker 容器状态
  - 显示迁移结果统计
- **使用场景**: 开发环境快速迁移

#### `run_migration.py`
- **保留原因**: 支持版本化迁移管理
- **功能**:
  - 迁移版本追踪（schema_migrations 表）
  - 执行指定版本的迁移
  - 查看迁移状态和列表
  - 支持复杂的数据转换
- **使用场景**: 生产环境迁移、复杂数据转换

### 2. 归档的调试工具

#### `debug_cors.sh` → `server/.archive/debug_cors.sh`
- **归档原因**: 临时调试工具，CORS 配置已稳定
- **功能**: 诊断 CORS 配置问题
- **保留期限**: 3 个月（如无问题可删除）

### 3. 迁移策略说明

项目当前使用**双轨制迁移策略**：

#### 开发环境（自动迁移）
- 使用 `init_db()` 自动创建表
- 优点: 快速、简单
- 缺点: 不支持版本控制
- 触发时机: 应用启动时

#### 生产环境（版本化迁移）
- 使用 `app/migrations/*.py` 脚本
- 优点: 版本控制、可回滚、支持复杂转换
- 缺点: 需要手动管理
- 执行方式: `./migrate_db.sh` 或 `python run_migration.py`

## 文档更新

### 更新的文档
- `server/README.md`: 补充了迁移策略说明
- `server/.archive/README.md`: 新增归档文件说明

### 引用这些脚本的文档（无需修改）
- `docs/server/DEPLOYMENT.md`
- `docs/server/guides/troubleshooting-database.md`
- `.claude/skills/jointo-tech-stack/references/database.md`
- `.claude/skills/jointo-tech-stack/references/infrastructure.md`

## 后续建议

### 短期（1-2 周）
- [ ] 验证自动迁移在开发环境的稳定性
- [ ] 测试版本化迁移脚本的完整性

### 中期（1 个月）
- [ ] 统一迁移策略（选择自动或版本化）
- [ ] 如果 CORS 配置稳定，删除 `debug_cors.sh`

### 长期（3 个月）
- [ ] 如果选择版本化迁移，更新 `migrate_db.sh` 调用 `run_migration.py`
- [ ] 如果选择自动迁移，删除版本化迁移相关代码
- [ ] 清理 `.archive/` 目录中的过期文件

## 影响评估

- ✅ 无破坏性变更
- ✅ 保留了所有功能性脚本
- ✅ 文档保持一致性
- ✅ 归档了临时工具

## 相关文档

- [部署指南](../DEPLOYMENT.md)
- [数据库故障排查](../guides/troubleshooting-database.md)
- [技术栈规范](../../architecture/tech-stack.md)