docs: 拆分架构设计文档为多篇专项文档

docs/api.md

@@ -1,62 +1,77 @@
-# gen2d API 文档
+# gen2d API 设计
 
-Base URL: `http://localhost:8080`
-
-## 统一响应格式
-
-所有接口均返回以下 JSON 结构：
+所有接口统一前缀 `/api/v1/`，统一响应格式：
 
 ```json
-{
-  "code": 0,
-  "message": "ok",
-  "data": {}
-}
+{ "code": 0, "message": "ok", "data": {} }
 ```
 
-| 字段      | 类型   | 说明                                   |
-| --------- | ------ | -------------------------------------- |
-| `code`    | int    | 业务状态码。`0` 表示成功，非零为错误码 |
-| `message` | string | 状态描述                               |
-| `data`    | any    | 响应数据，错误时可能不返回此字段       |
+## 状态说明
 
-### 成功响应
-
-```json
-{
-  "code": 0,
-  "message": "ok",
-  "data": { ... }
-}
-```
-
-### 错误响应
-
-```json
-{
-  "code": 400,
-  "message": "error description"
-}
-```
+- [x] 已完成
+- [ ] 规划中
 
 ---
 
-## 接口列表
+## 基础设施
 
-### 健康检查
+| 状态 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| [x] | GET | `/api/v1/health` | 健康检查 |
 
-```
-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
 {
-  "code": 0,
-  "message": "ok",
-  "data": {
-    "status": "healthy"
+  "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` | 批量清除缓存 |