# gen2d API 设计

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

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

## 状态说明

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

---

## 基础设施

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

## 素材生成

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

请求体示例 (POST /api/v1/generate)：

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

- `prompt`：用户原始文本，后端 PromptBuilder 负责三段式重写
- `taskStyle`：可选，任务级别风格覆盖（同名键覆盖工程风格）

## 工程风格

| 状态 | 方法 | 路径 | 说明 |
|------|------|------|------|
| [ ] | 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"
  }
}
```

## 缓存管理

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