# MiniMax 图生图 API 集成设计方案

## 概述

前端传递参数 → 后端异步调用 MiniMax 图生图 API → 前端轮询任务状态 → 返回结果

## 现有架构

| 层级 | 技术栈 | 说明 |
|------|--------|------|
| 前端 | uni-app (Vue 3) | 使用 `uni.request` 发起请求，已有 loading 页面 |
| 后端 | Go + Gin | API Gateway 模式，Dubbo RPC 调用微服务 |
| 微服务 | Go | `assetService` 等独立服务 |
| 配置 | `.env` 文件 | API keys 等敏感配置 |

## API 设计

### 1. 创建图生图任务

```
POST /api/v1/assets/mints/image/generation
```

**请求头:**
```
Authorization: Bearer <token>
Content-Type: application/json
```

**请求体:**
```json
{
  "model": "image-01",
  "prompt": "描述文本",
  "aspect_ratio": "16:9",
  "subject_reference": [
    {
      "type": "character",
      "image_file": "https://..."
    }
  ],
  "n": 2
}
```

**响应 (202 Accepted):**
```json
{
  "code": 202,
  "message": "任务已创建",
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "PROCESSING",
    "created_at": "2026-04-07T12:00:00Z"
  }
}
```

### 2. 查询任务状态

```
GET /api/v1/assets/mints/image/generation/:job_id
```

**响应 (PROCESSING):**
```json
{
  "code": 200,
  "message": "处理中",
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "PROCESSING",
    "progress": 50,
    "created_at": "2026-04-07T12:00:00Z"
  }
}
```

**响应 (COMPLETED):**
```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "progress": 100,
    "images": [
      "https://api.minimaxi.com/v1/images/xxx.png"
    ],
    "created_at": "2026-04-07T12:00:00Z",
    "completed_at": "2026-04-07T12:01:30Z"
  }
}
```

**响应 (FAILED):**
```json
{
  "code": 200,
  "message": "失败",
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "FAILED",
    "progress": 0,
    "error_msg": "MiniMax API 调用失败: timeout",
    "created_at": "2026-04-07T12:00:00Z"
  }
}
```

## 数据模型

### Job 状态 (内存存储)

```go
// ImageGenerationJob 图生图任务
type ImageGenerationJob struct {
    JobID      string    `json:"job_id"`
    UserID     int64     `json:"user_id"`
    StarID     int64     `json:"star_id"`
    Status     string    `json:"status"`   // PENDING, PROCESSING, COMPLETED, FAILED
    Progress   int       `json:"progress"` // 0-100
    Images     []string  `json:"images,omitempty"`
    ErrorMsg   string    `json:"error_msg,omitempty"`
    Request    *ImageGenerationRequest `json:"request,omitempty"`
    CreatedAt  time.Time `json:"created_at"`
    UpdatedAt  time.Time `json:"updated_at"`
}
```

### DTO

```go
// ImageGenerationRequest MiniMax 图生图请求
type ImageGenerationRequest struct {
    Model            string              `json:"model" binding:"required"`
    Prompt           string              `json:"prompt" binding:"required"`
    AspectRatio      string              `json:"aspect_ratio"`
    SubjectReference []SubjectReference  `json:"subject_reference"`
    N                int                 `json:"n"`
}

type SubjectReference struct {
    Type      string `json:"type"`
    ImageFile string `json:"image_file"`
}

// ImageJobResponse 图生图任务响应
type ImageJobResponse struct {
    JobID      string   `json:"job_id"`
    Status     string   `json:"status"`
    Progress   int      `json:"progress"`
    Images     []string `json:"images,omitempty"`
    ErrorMsg   string   `json:"error_msg,omitempty"`
    CreatedAt  int64    `json:"created_at"`
    UpdatedAt  int64    `json:"updated_at"`
}
```

## 后端实现

### 文件结构

```
backend/
├── services/assetService/
│   └── service/
│       └── minimax_service.go      # MiniMax API 转发服务
└── gateway/
    ├── controller/
    │   └── asset_controller.go     # 新增 ImageGeneration, GetImageJob
    ├── dto/
    │   └── image_dto.go            # 请求/响应 DTO
    └── router/
        └── router.go               # 注册路由
```

### 核心逻辑

1. **创建任务**: 生成 job_id，存储任务到内存，返回 202
2. **异步处理**: goroutine 调用 MiniMax API，图片压缩，更新 job 状态
3. **查询状态**: 从内存读取 job 状态返回

### 前端改动

**generation-loading.vue**:
- 调用 `POST /generation` 获取 job_id
- 轮询 `GET /generation/:job_id` 直到 `status === 'COMPLETED'` 或 `'FAILED'`
- 进度可通过 `progress` 字段模拟更新

## 错误处理

| 场景 | 处理方式 |
|------|----------|
| MiniMax API 超时 | 标记 job 为 FAILED，error_msg 包含原因 |
| 图片压缩失败 | 使用原图，继续处理 |
| Job 不存在 | 返回 404 |
| 无权访问 job | 返回 403 |

## 文件修改清单

| 操作 | 文件路径 | 说明 |
|------|----------|------|
| 新增 | `backend/gateway/dto/image_dto.go` | 请求/响应 DTO |
| 新增 | `backend/services/assetService/service/minimax_service.go` | MiniMax API 转发 + 图片压缩 + 任务管理 |
| 修改 | `backend/gateway/controller/asset_controller.go` | 新增 ImageGeneration, GetImageJob |
| 修改 | `backend/gateway/router/router.go` | 注册路由 |
| 修改 | `frontend/pages/discover/generation-loading.vue` | 改为轮询模式 |

## 依赖

```bash
cd backend/services/assetService && go get github.com/nfnt/resize
```

## 验证方案

1. 启动后端服务
2. 获取 JWT token
3. 测试创建任务:
   ```bash
   curl -X POST http://localhost:8080/api/v1/assets/mints/image/generation \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"model":"image-01","prompt":"test","aspect_ratio":"16:9","n":1,"subject_reference":[]}'
   ```
4. 使用返回的 job_id 轮询状态:
   ```bash
   curl http://localhost:8080/api/v1/assets/mints/image/generation/<job_id> \
     -H "Authorization: Bearer <token>"
   ```