fischerX/docs/development/migration-guide.md

# 迁移指南

> **文档版本**: v1.0.0
> **创建日期**: 2026-05-25
> **适用范围**: FischerX 项目开发人员

## 目录

- [v1.x → v2.x 迁移](#v1x--v2x-迁移)
- [破坏性变更说明](#破坏性变更说明)
- [迁移步骤](#迁移步骤)
- [常见问题](#常见问题)

---

## v1.x → v2.x 迁移

### 概述

v2.0 带来了以下重大改进：
- 升级到 Next.js 16
- 升级到 NestJS 11
- 升级到 Prisma 6
- 引入 Monorepo 架构
- 重构了认证系统

---

## 破坏性变更说明

### Next.js 变更

#### Pages Router → App Router

**v1.x**:
```tsx
// pages/index.tsx
export default function Home() {
  return <div>Home</div>;
}
```

**v2.x**:
```tsx
// app/page.tsx
export default function HomePage() {
  return <div>Home</div>;
}
```

#### 图片组件变更

**v1.x**:
```tsx
import Image from 'next/image';

<Image src="/logo.png" width={100} height={100} />
```

**v2.x**:
```tsx
import Image from 'next/image';

<Image src="/logo.png" width={100} height={100} alt="Logo" />
```

### Prisma 变更

#### 枚举值变更

**v1.x**:
```prisma
enum Role {
  ADMIN
  USER
}
```

**v2.x**:
```prisma
enum Role {
  ADMIN
  USER
  GUEST @default(USER)
}
```

### API 变更

#### 认证端点

**v1.x**:
```
POST /auth/login
POST /auth/register
```

**v2.x**:
```
POST /api/v1/auth/login
POST /api/v1/auth/register
POST /api/v1/auth/refresh
```

---

## 迁移步骤

### 1. 备份数据

```bash
# 备份数据库
pg_dump fischerx > backup_v1.sql
```

### 2. 更新代码

```bash
# 拉取新版本
git fetch origin
git checkout v2.0.0
```

### 3. 更新依赖

```bash
# 安装新依赖
pnpm install
```

### 4. 数据库迁移

```bash
# 运行新迁移
cd services/api
pnpm prisma migrate deploy
```

### 5. 更新环境变量

```env
# 添加新的环境变量
NEXT_PUBLIC_API_URL=http://localhost:4000/api/v1
```

### 6. 测试

```bash
# 运行测试
pnpm test
```

---

## 常见问题

### Q: 我的自定义 Hooks 需要改吗？

A: 大部分不需要，除非它们依赖旧的 Next.js API。

### Q: 数据库迁移会丢失数据吗？

A: 我们的迁移是安全的，但建议先备份。

### Q: 旧的 API 端点还能用吗？

A: 我们提供了向后兼容层，但建议尽快迁移。

---

## 下一步

- [常见问题](./troubleshooting.md) - 查看更多问题

---

> **文档维护**: 本文档由开发团队维护，如有问题或建议请提交 Issue。
> **最后更新**: 2026-05-25