mini-starter/docs/prd/epic-007-database-migration-fixes.md

史诗007：数据库迁移问题修复与web集成

史诗状态

进度: 0/3 故事完成 (0%) 最近更新: 2025-12-16 (史诗重写) 当前状态: 所有故事待开始

史诗目标

修复当前数据库迁移脚本问题，使server包提供可用的迁移功能，web包能够正确调用并集成到启动流程。

史诗描述

当前问题

1. server包TypeORM脚本问题：

   • packages/server/package.json中的迁移脚本路径错误（指向./src/server/data-source.ts但不存在）
   • 缺少tsx依赖，脚本无法执行
   • 已创建packages/server/src/data-source.ts但脚本未更新

2. web包迁移脚本缺失：

   • web/package.json中的db:migrate脚本指向不存在的scripts/migrate.ts文件
   • pnpm start启动流程未集成数据库迁移
   • web包无法使用server包的迁移功能

3. 迁移功能未封装：

   • 没有统一的迁移工具模块
   • 无法在程序化代码中调用迁移
   • 缺少错误处理和日志

解决方案

1. 修复server包基础配置：修正脚本路径，添加依赖，使TypeORM命令可工作
2. 实现迁移工具模块：在server包中创建可导出的迁移工具，支持API和CLI调用
3. 集成web包启动流程：修复web脚本，集成自动迁移到pnpm start

故事

故事1：修复server包TypeORM基础配置

目标：使packages/server中的TypeORM命令能够正确执行

具体任务：

1. 修正packages/server/package.json中的脚本路径：
   • 当前：./src/server/data-source.ts → 修正为：./src/data-source.ts
2. 确保tsx依赖已添加（已添加）
3. 验证基础命令可工作：
   • pnpm db:migrate - 运行迁移
   • pnpm db:migrate:generate - 生成迁移文件
   • pnpm db:migrate:revert - 回滚迁移

成功标准：

• ✅ pnpm db:migrate能够正确连接到数据库
• ✅ TypeORM能够找到数据源配置
• ✅ 迁移相关命令无路径错误

故事2：实现server包迁移工具模块

目标：在server包中创建可导出的迁移工具，供其他包调用

具体任务：

1. 创建迁移工具模块：packages/server/src/migration-runner.ts
   • 导出runMigrations()函数：运行所有待处理迁移
   • 导出getMigrationStatus()函数：查看迁移状态
   • 支持错误处理和详细日志
2. 创建CLI入口：packages/server/src/cli/migrate.ts
   • 支持命令行调用：tsx packages/server/src/cli/migrate.ts run
   • 支持状态查看：tsx packages/server/src/cli/migrate.ts status
3. 更新package.json导出配置：
   • 确保迁移工具可以被其他包导入
   • 添加必要的TypeScript类型导出

成功标准：

• ✅ 可以从其他包导入@d8d/server的迁移工具
• ✅ runMigrations()函数可以程序化调用
• ✅ CLI工具能够执行迁移操作
• ✅ 错误处理完善，日志清晰

故事3：修复web包脚本并集成自动迁移

目标：修复web包缺失的迁移脚本，集成自动迁移到启动流程

具体任务：

1. 修复web包迁移脚本：
   • 创建web/scripts/migrate.ts文件
   • 调用server包的runMigrations()函数
   • 修复web/package.json中的db:migrate脚本路径
2. 集成自动迁移到启动流程：
   • 更新web/package.json中的start脚本
   • 在启动服务器前自动运行迁移
   • 支持环境变量控制：AUTO_MIGRATE=true/false
3. 错误处理：
   • 迁移失败时阻止应用启动
   • 显示清晰的错误信息
   • 保持现有数据库管理脚本（备份、恢复等）正常工作

成功标准：

• ✅ pnpm db:migrate在web包中能够正确执行
• ✅ pnpm start在启动前自动运行数据库迁移（可配置）
• ✅ 迁移失败时应用启动流程终止并显示错误
• ✅ 现有数据库管理脚本继续正常工作

技术实现细节

数据源配置

// packages/server/src/data-source.ts (已存在)
import { initializeDataSource } from '@d8d/shared-utils'
// 导入所有实体并初始化

迁移工具接口

// packages/server/src/migration-runner.ts
export async function runMigrations(): Promise<void>
export async function getMigrationStatus(): Promise<MigrationStatus>

web包集成

// web/package.json
{
  "scripts": {
    "db:migrate": "tsx scripts/migrate.ts",
    "start": "AUTO_MIGRATE=true tsx scripts/migrate.ts && PORT=8080 cross-env NODE_ENV=production node server"
  }
}

依赖关系

• 故事1 → 故事2：需要基础TypeORM配置正常工作才能实现迁移工具
• 故事2 → 故事3：需要server包迁移工具完成才能集成到web包

验收标准

1. ✅ server包TypeORM命令可正确执行
2. ✅ web包db:migrate脚本可正常工作
3. ✅ pnpm start自动运行数据库迁移（可配置）
4. ✅ 迁移失败时应用不启动，显示清晰错误

后续优化（非本史诗范围）

1. 完整的迁移目录结构和TypeORM配置文件
2. 数据库创建/删除脚本
3. 种子数据管理
4. 迁移使用指南和集成测试

本史诗专注于解决最紧急的数据库迁移问题，确保生产环境部署时数据库架构可以正确更新。