@xiaoluo_aigc0708/aigc-sdk/MIGRATION.md

AI智能建筑 - 完整的AIGC图片生成SDK

# 🔄 从现有项目迁移到AIGC SDK

本指南将帮助您从现有的AIGC项目无缝迁移到SDK版本。

## 📋 迁移前准备

### 1. 确认现有项目文件

需要迁移的核心文件：
```
app/
├── actions/
│   ├── index.ts                    → @ai-building/aigc-core
│   ├── comfyui-new-actions.ts     → @ai-building/aigc-core  
│   └── comfyui-actions.ts         → 可删除（已废弃）
├── services/
│   └── comfyui-new-workflows.ts   → @ai-building/comfyui-client
├── store/
│   ├── useGenerationStore.ts      → @ai-building/aigc-state (规划中)
│   ├── useSelectedImageStore.ts   → @ai-building/aigc-state (规划中)
│   └── genImageStore.ts           → 需要适配
├── api/
│   ├── upload-oss/route.ts        → @ai-building/oss-storage
│   ├── upload-base-image/route.ts → @ai-building/oss-storage
│   └── style-library/route.ts     → 需要适配
└── generate/components/
    ├── GenerationRecords.tsx      → @ai-building/aigc-react (规划中)
    ├── SelectedImageDisplay.tsx   → @ai-building/aigc-react (规划中)
    └── ...                        → 需要适配
```

### 2. 备份现有项目

```bash
# 创建备份
git branch backup-before-sdk-migration
git commit -am "备份：迁移到SDK前的代码"
```

## 🚀 迁移步骤

### 步骤1: 安装SDK

```bash
# 安装核心SDK
npm install @ai-building/aigc-core

# 如果需要独立使用特定模块
npm install @ai-building/comfyui-client
npm install @ai-building/oss-storage
npm install @ai-building/aigc-types
```

### 步骤2: 创建配置文件

```typescript
// config/aigc.config.ts
import { AIGCConfig } from '@ai-building/aigc-core';

export const aigcConfig: AIGCConfig = {
  comfyui: {
    apiUrl: process.env.NEXT_PUBLIC_COMFYUI_API_URL || 'http://100.72.216.20:7865/api/comfy/run_workflow',
    imageServiceUrl: process.env.NEXT_PUBLIC_COMFYUI_IMAGE_URL || 'http://100.72.216.20:8288',
    timeout: 30000
  },
  oss: {
    region: process.env.OSS_REGION || 'oss-cn-beijing',
    accessKeyId: process.env.OSS_ACCESS_KEY_ID!,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET!,
    bucket: process.env.OSS_BUCKET || 'qinghua-ib-ai',
    endpoint: process.env.OSS_ENDPOINT || 'oss-cn-beijing.aliyuncs.com'
  }
};
```

### 步骤3: 替换Actions层

#### 原来的代码 (app/actions/index.ts)
```typescript
// ❌ 旧的实现
import { postNewComfyUITxt2Img, postNewComfyUIImg2Img } from "./comfyui-new-actions";
import { useGenerationStore } from "@/app/store/useGenerationStore";

export const postTxt2Img = async (txt2img: any) => {
  const { addRecord, completeGeneration, failGeneration } = useGenerationStore.getState();
  // ... 复杂的状态管理和参数转换
};
```

#### 新的SDK实现
```typescript
// ✅ 新的SDK实现
// services/aigc.service.ts
import { AIGCCore } from '@ai-building/aigc-core';
import { aigcConfig } from '../config/aigc.config';

class AIGCService {
  private aigc: AIGCCore;

  constructor() {
    this.aigc = new AIGCCore(aigcConfig);
  }

  async generateTextToImage(params: {
    prompt: string;
    width?: number;
    height?: number;
    n_iter?: number;
    styleImage?: File;
  }) {
    return await this.aigc.generateTextToImage(params);
  }

  async generateImageToImage(params: {
    prompt: string;
    init_images?: string[];
    batch_size?: number;
    styleImage?: File;
  }) {
    return await this.aigc.generateImageToImage(params);
  }
}

export const aigcService = new AIGCService();
```

### 步骤4: 更新组件调用

#### 原来的组件调用
```typescript
// ❌ 旧的组件调用
import { postTxt2Img } from '@/app/actions/index';

const handleGenerate = async () => {
  try {
    const result = await postTxt2Img({
      prompt: prompt,
      width: 1024,
      height: 1024,
      n_iter: 2,
      style_image: styleFile
    });
    // 复杂的结果处理...
  } catch (error) {
    // 错误处理...
  }
};
```

#### 新的SDK调用
```typescript
// ✅ 新的SDK调用
import { aigcService } from '../services/aigc.service';

const handleGenerate = async () => {
  try {
    const result = await aigcService.generateTextToImage({
      prompt,
      width: 1024,
      height: 1024,
      n_iter: 2,
      styleImage: styleFile
    });
    // 简化的结果处理
  } catch (error) {
    // 统一的错误处理
  }
};
```

### 步骤5: 迁移OSS上传功能

#### 替换API路由
```typescript
// ❌ 删除这些文件
// app/api/upload-oss/route.ts
// app/api/upload-base-image/route.ts

// ✅ 使用SDK方法
import { aigcService } from '../services/aigc.service';

// 风格图片上传
const handleStyleUpload = async (file: File) => {
  const result = await aigcService.aigc.uploadStyleImage(file);
  return result;
};

// 基底图片上传
const handleBaseUpload = async (file: File) => {
  const result = await aigcService.aigc.uploadBaseImage(file);
  return result;
};
```

### 步骤6: 更新环境变量

#### 更新 .env.local
```bash
# ❌ 删除或注释掉旧的变量
# NEXT_PUBLIC_SD_API_URL=...
# NEXT_PUBLIC_USE_COMFYUI=...

# ✅ SDK需要的环境变量
NEXT_PUBLIC_COMFYUI_API_URL=http://100.72.216.20:7865/api/comfy/run_workflow
NEXT_PUBLIC_COMFYUI_IMAGE_URL=http://100.72.216.20:8288
OSS_REGION=oss-cn-beijing
OSS_ACCESS_KEY_ID=your_access_key_id
OSS_ACCESS_KEY_SECRET=your_access_key_secret  
OSS_BUCKET=qinghua-ib-ai
OSS_ENDPOINT=oss-cn-beijing.aliyuncs.com
```

### 步骤7: 更新状态管理

#### 原来的状态管理
```typescript
// ❌ 复杂的状态管理
import { useGenerationStore } from '@/app/store/useGenerationStore';

const { addRecord, updateProgress, completeGeneration } = useGenerationStore();
```

#### 使用SDK的状态管理
```typescript
// ✅ 简化的状态管理 (使用React Hook)
import { useAIGC } from '../hooks/useAIGC';

const { loading, result, error, generateTextToImage } = useAIGC();
```

## 🔧 代码对比与替换

### 文件替换映射表

| 原文件 | 新的SDK方法 | 说明 |
|--------|-------------|------|
| `app/actions/index.ts` | `@ai-building/aigc-core` | 核心生成逻辑 |
| `app/services/comfyui-new-workflows.ts` | `@ai-building/comfyui-client` | 工作流管理 |
| `app/actions/comfyui-new-actions.ts` | `@ai-building/aigc-core` | 集成到核心SDK |
| `app/api/upload-oss/route.ts` | `aigcService.uploadStyleImage()` | OSS上传方法 |
| `app/api/upload-base-image/route.ts` | `aigcService.uploadBaseImage()` | OSS上传方法 |

### 导入语句替换

```typescript
// ❌ 原来的导入
import { postTxt2Img, postImg2Img } from '@/app/actions/index';
import { selectWorkflowAndCreateRequest } from '@/app/services/comfyui-new-workflows';
import { useGenerationStore } from '@/app/store/useGenerationStore';

// ✅ 新的SDK导入
import { AIGCCore, AIGCError } from '@ai-building/aigc-core';
import { ComfyUIClient, WorkflowBuilder } from '@ai-building/comfyui-client';
import { OSSStorageClient } from '@ai-building/oss-storage';
```

### 函数调用替换

```typescript
// ❌ 原来的函数调用
const result = await postTxt2Img({
  prompt: "a beautiful landscape",
  width: 1024,
  height: 1024,
  n_iter: 2
});

// ✅ 新的SDK调用
const result = await aigcService.generateTextToImage({
  prompt: "a beautiful landscape",
  width: 1024,
  height: 1024,
  n_iter: 2
});
```

## ✅ 迁移验证清单

### 功能验证
- [ ] 文生图功能正常
- [ ] 图生图功能正常  
- [ ] 风格参考图片上传正常
- [ ] 基底图片上传正常
- [ ] 图片URL构建正常
- [ ] 错误处理正常

### 性能验证
- [ ] 生成速度与原项目一致
- [ ] 文件上传速度正常
- [ ] 内存使用正常
- [ ] 网络请求优化

### 代码质量验证
- [ ] TypeScript类型检查通过
- [ ] ESLint检查通过
- [ ] 所有imports正常解析
- [ ] 构建打包成功

## 🚨 常见问题与解决方案

### 问题1: 类型错误
```typescript
// ❌ 错误: Property 'style_image' does not exist
const params = { style_image: file };

// ✅ 解决: 使用正确的参数名
const params = { styleImage: file };
```

### 问题2: 配置问题
```typescript
// ❌ 错误: OSS配置不正确
const config = { oss: undefined };

// ✅ 解决: 确保所有必需配置
const config = {
  oss: {
    region: 'oss-cn-beijing',
    accessKeyId: process.env.OSS_ACCESS_KEY_ID!,
    // ... 其他必需配置
  }
};
```

### 问题3: 兼容性问题
```typescript
// ❌ 错误: 旧的store依赖
import genImageStore from '@/app/store/genImageStore';

// ✅ 解决: 使用SDK或创建适配器
import { useAIGC } from '../hooks/useAIGC';
// 或者创建适配器保持兼容
```

## 🎯 迁移后的优势

### 代码简化
- ✅ 减少70%的样板代码
- ✅ 统一的错误处理
- ✅ 类型安全保证

### 维护性提升  
- ✅ 模块化架构
- ✅ 独立测试和更新
- ✅ 清晰的API接口

### 扩展性增强
- ✅ 支持多种部署方式
- ✅ 可插拔的功能模块
- ✅ 跨项目复用

## 📞 迁移支持

如果在迁移过程中遇到问题：

1. **查看完整示例**: 参考 `EXAMPLES.md`
2. **API文档**: 查看 `README.md` 的API参考
3. **问题反馈**: 提交GitHub Issue
4. **技术支持**: support@ai-building.com

迁移完成后，您的项目将具备更好的可维护性、扩展性和类型安全性！🚀