gen2d/docs/api.md

# gen2d API 设计

所有接口统一前缀 `/api/v1/`，统一响应格式：

```json
{ "code": 0, "message": "ok", "data": {} }
```

## 状态说明

- [x] 已完成
- [ ] 规划中

---

## 基础设施

| 状态 | 方法 | 路径 | 说明 |
|------|------|------|------|
| [x] | GET | `/api/v1/health` | 健康检查 |

## 工程管理

| 状态 | 方法 | 路径 | 说明 |
|------|------|------|------|
| [ ] | POST | `/api/v1/projects` | 创建工程 |
| [ ] | GET | `/api/v1/projects/:projectId` | 获取工程信息 |
| [ ] | GET | `/api/v1/projects/:projectId/tasks` | 获取工程下的任务列表 |

### POST /api/v1/projects

```json
{
  "name": "我的像素游戏"
}
```

响应：

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "proj_abc123",
    "name": "我的像素游戏",
    "style": { "kvPairs": {} },
    "createdAt": "2026-05-24T10:00:00Z"
  }
}
```

### GET /api/v1/projects/:projectId/tasks

| 参数 | 类型 | 说明 |
|------|------|------|
| `page` | int | 页码，默认 1 |
| `pageSize` | int | 每页条数，默认 20 |

响应：

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "total": 42,
    "tasks": [
      {
        "id": "task_xyz789",
        "prompt": "一个拿剑的小人",
        "assetType": "sprite",
        "status": "completed",
        "createdAt": "2026-05-24T10:05:00Z"
      }
    ]
  }
}
```

## 工程风格

| 状态 | 方法 | 路径 | 说明 |
|------|------|------|------|
| [ ] | GET | `/api/v1/projects/:projectId/style` | 获取工程风格 |
| [ ] | PUT | `/api/v1/projects/:projectId/style` | 更新工程风格 |

请求体示例 (PUT /api/v1/projects/:projectId/style)：

```json
{
  "kvPairs": {
    "artStyle": "pixel",
    "palette": "warm",
    "lineWeight": "thin",
    "lighting": "bright"
  }
}
```

## 素材生成

| 状态 | 方法 | 路径 | 说明 |
|------|------|------|------|
| [ ] | POST | `/api/v1/generate` | 提交生成任务，返回 taskId |
| [ ] | GET | `/api/v1/tasks/:taskId` | 查询任务状态与进度 |
| [ ] | GET | `/api/v1/tasks/:taskId/assets` | 获取生成结果（素材列表 + 元数据） |
| [ ] | WS | `/api/v1/tasks/:taskId/ws` | WebSocket 实时进度推送 |

### POST /api/v1/generate

请求体对应后端 `PipelineInput`：

```json
{
  "projectId": "proj_abc123",
  "prompt": "一个拿剑的小人",
  "assetType": "sprite",
  "taskStyle": {
    "scene": "dungeon",
    "mood": "dark"
  },
  "params": {
    "resolution": 64,
    "frames": { "directions": 8, "framesPerDirection": 4 },
    "format": "spritesheet"
  }
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `projectId` | string | 是 | 工程 ID，用于获取工程风格 |
| `prompt` | string | 是 | 用户原始文本，后端 PromptBuilder 负责三段式重写 |
| `assetType` | string | 是 | 素材类型：`sprite` / `background` / `ui` / `animation` |
| `taskStyle` | object | 否 | 任务级别风格覆盖（同名键覆盖工程风格） |
| `params.resolution` | int | 否 | 分辨率，默认 64 |
| `params.frames` | object | 否 | 帧参数（仅 sprite/animation） |
| `params.frames.directions` | int | 否 | 方向数，默认 4 |
| `params.frames.framesPerDirection` | int | 否 | 每方向帧数，默认 4 |
| `params.format` | string | 否 | 输出格式：`spritesheet` / `individual`，默认 `spritesheet` |

响应：

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "task_xyz789",
    "status": "pending"
  }
}
```

### GET /api/v1/tasks/:taskId

响应：

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "task_xyz789",
    "projectId": "proj_abc123",
    "prompt": "一个拿剑的小人",
    "assetType": "sprite",
    "status": "running",
    "stage": "asset_generator",
    "progress": 45,
    "retryCount": 0,
    "createdAt": "2026-05-24T10:05:00Z",
    "updatedAt": "2026-05-24T10:05:30Z"
  }
}
```

任务状态机：

```mermaid
stateDiagram-v2
    [*] --> pending
    pending --> running : 管线开始执行
    running --> completed : 四阶段全部通过
    running --> failed : 节点执行失败 / 超过重试次数
    completed --> [*]
    failed --> [*]
```

管线阶段（对应 Eino Graph 节点）：

| 阶段 | 说明 |
|------|------|
| `prompt_builder` | 合并风格，生成三段式提示词 |
| `asset_generator` | 调用 AI 推理 API 出图 |
| `quality_supervisor` | 视觉模型质检（可能触发重试回到 prompt_builder） |
| `format_adapter` | 格式转换、spritesheet 打包 |

### GET /api/v1/tasks/:taskId/assets

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "assets": [
      {
        "id": "asset_001",
        "url": "/files/tasks/task_xyz789/spritesheet.png",
        "format": "png",
        "width": 256,
        "height": 64,
        "metadata": {
          "frameWidth": 64,
          "frameHeight": 64,
          "frameCount": 4,
          "directions": 1
        }
      }
    ]
  }
}
```

### WebSocket 消息格式

连接路径：`ws://host/api/v1/tasks/:taskId/ws`

```typescript
interface PipelineProgress {
  stage: 'prompt_builder' | 'asset_generator' | 'quality_supervisor' | 'format_adapter';
  status: 'running' | 'completed' | 'failed';
  progress: number;       // 0-100
  message?: string;       // 阶段描述
  retryCount?: number;    // 质检重试次数（仅 quality_supervisor 阶段）
  rejectReason?: string;  // 质检不通过原因（仅 quality_supervisor fail 时）
  result?: {              // 仅在 format_adapter completed 时返回
    assets: Asset[];
  };
  error?: string;         // 仅在 failed 时返回
}
```

消息示例（正常流程）：

```json
{"stage":"prompt_builder","status":"running","progress":0}
{"stage":"prompt_builder","status":"completed","progress":100}
{"stage":"asset_generator","status":"running","progress":0}
{"stage":"asset_generator","status":"completed","progress":100}
{"stage":"quality_supervisor","status":"completed","progress":100}
{"stage":"format_adapter","status":"running","progress":0}
{"stage":"format_adapter","status":"completed","progress":100,"result":{"assets":[...]}}
```

消息示例（质检重试）：

```json
{"stage":"quality_supervisor","status":"running","progress":0}
{"stage":"quality_supervisor","status":"failed","progress":100,"retryCount":1,"rejectReason":"风格不一致"}
{"stage":"prompt_builder","status":"running","progress":0}
{"stage":"asset_generator","status":"running","progress":0}
{"stage":"quality_supervisor","status":"completed","progress":100}
{"stage":"format_adapter","status":"completed","progress":100,"result":{"assets":[...]}}
```

## 缓存管理

| 状态 | 方法 | 路径 | 说明 |
|------|------|------|------|
| [ ] | DELETE | `/api/v1/cache/:key` | 清除特定缓存 |
| [ ] | POST | `/api/v1/cache/clear` | 批量清除缓存 |