api

generateServer.API.md

@@ -0,0 +1,338 @@
+# 图片生成接口文档
+
+## 接口概述
+
+轻量级 HTTP 图片生成服务，用于根据画布配置和商品数据生成营销图片。该接口返回 base64 格式的图片数据，不做文件落地，便于外部（如 Python）直接调用获取图片切片。
+
+**运行环境**: 仅在 Electron 渲染进程中可用（需要 Node.js 能力）
+
+---
+
+## 接口信息
+
+### 基本信息
+
+- **接口地址**: `http://localhost:3001/generate`
+- **请求方法**: `POST`
+- **Content-Type**: `application/json`
+- **请求体大小限制**: 最大 50MB
+
+### 接口路径
+
+```
+POST /generate
+```
+
+---
+
+## 请求参数
+
+### 请求体结构
+
+```json
+{
+  "canvasList": [],  // 画布配置数组（必填）
+  "goodsList": []    // 商品数据数组（必填）
+}
+```
+
+### 参数说明
+
+#### 1. canvasList（画布配置数组）
+
+画布配置数组，每个元素代表一个画布模板。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| index | number | 是 | 画布索引，从 0 开始 |
+| canvas_json | string | 是 | Fabric.js 画布配置的 JSON 字符串，或特殊值 `"scene"`（场景图） |
+| width | number | 是 | 画布宽度（像素） |
+| height | number | 是 | 画布高度（像素） |
+| bg_color | string | 是 | 背景色，如 `"#fff"` |
+| name | string | 否 | 画布名称 |
+| preview | string | 否 | 预览图 URL |
+| tpl_url | string | 否 | 模板 URL |
+| image_path | string | 否 | 图片路径 |
+| canvas_type | string | 否 | 画布类型：`"normal"`（普通）、`"model"`（模特图）、`"scene"`（场景图） |
+| multi_goods_mode | string | 否 | 多商品模式 |
+| max_goods_count | number \| null | 否 | 最大商品数量 |
+
+**canvas_json 说明**:
+- 普通画布：Fabric.js 格式的 JSON 字符串，包含 `version`、`objects`、`background` 等字段
+- 场景图：直接传入字符串 `"scene"`
+
+#### 2. goodsList（商品数据数组）
+
+商品数据数组，每个元素是一个对象，键为款号（styleKey），值为商品信息。
+
+**数据结构**:
+
+```json
+{
+  "款号（styleKey）": {
+    "款号": "string",           // 款号，如 "E305-01003"
+    "设计理念": "string",        // 设计理念文案（可选，款级）
+    "货号资料": [                // 货号数组
+      {
+        "货号": "string",        // 货号，如 "A596351"
+        "颜色": "string",        // 颜色，如 "黑色"
+        "设计理念": "string",    // 设计理念文案（可选，货号级，优先级高于款级）
+        "pics": {                // 图片路径对象
+          "视角名称": "string"   // 键为视角名称（如"俯视"、"侧视"、"后跟"等），值为图片路径
+        }
+      }
+    ]
+  }
+}
+```
+
+**pics 对象说明**:
+- 键：视角名称，如 `"俯视"`、`"侧视"`、`"后跟"`、`"鞋底"`、`"内里"` 等
+- 值：图片文件路径（支持本地路径，如 `"C:\\Users\\...\\image.png"`）
+
+---
+
+## 响应格式
+
+### 成功响应
+
+**HTTP 状态码**: `200`
+
+**响应体**:
+
+```json
+{
+  "code": 0,
+  "images": [
+    {
+      "canvasIndex": 0,                    // 画布索引
+      "dataUrl": "data:image/png;base64,..."  // base64 格式的图片数据
+    }
+  ],
+  "plans": []  // 渲染计划数组（内部使用）
+}
+```
+
+**响应字段说明**:
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| code | number | 响应码，0 表示成功 |
+| images | array | 生成的图片数组 |
+| images[].canvasIndex | number | 对应的画布索引 |
+| images[].dataUrl | string | base64 格式的图片数据，可直接用于 `<img src="...">` |
+| plans | array | 渲染计划数组（内部数据结构） |
+
+### 失败响应
+
+**HTTP 状态码**: `500`
+
+**响应体**:
+
+```json
+{
+  "code": 1,
+  "msg": "error message"
+}
+```
+
+**响应字段说明**:
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| code | number | 响应码，1 表示失败 |
+| msg | string | 错误信息 |
+
+### 其他错误响应
+
+| HTTP 状态码 | 说明 | 响应体 |
+|------------|------|--------|
+| 404 | 路径或方法错误 | `"Not Found"` |
+| 413 | 请求体过大（>50MB） | `"Payload Too Large"` |
+
+---
+
+## 调用示例
+
+### JavaScript/TypeScript 示例
+
+```javascript
+const response = await fetch('http://localhost:3001/generate', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    canvasList: [
+      {
+        index: 0,
+        canvas_json: '{"version":"5.2.1","objects":[{"type":"image","src":"...","left":0,"top":0}],"background":"#fff"}',
+        width: 395,
+        height: 618,
+        bg_color: "#fff",
+        name: "画布_1",
+        canvas_type: "normal"
+      }
+    ],
+    goodsList: [
+      {
+        "AC5120913": {
+          "款号": "E305-01003",
+          "设计理念": "平衡舒适性、美观性、功能性和工艺品质",
+          "货号资料": [
+            {
+              "货号": "A596351",
+              "颜色": "黑色",
+              "设计理念": "满足现代消费者在不同场景下的需求",
+              "pics": {
+                "俯视": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\1.png",
+                "侧视": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\2.png",
+                "后跟": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\3.png",
+                "鞋底": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\4.png",
+                "内里": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\5.png"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  })
+})
+
+const result = await response.json()
+if (result.code === 0) {
+  console.log('生成成功，共', result.images.length, '张图片')
+  result.images.forEach(img => {
+    console.log(`画布 ${img.canvasIndex} 的图片:`, img.dataUrl.substring(0, 50) + '...')
+  })
+} else {
+  console.error('生成失败:', result.msg)
+}
+```
+
+### Python 示例
+
+```python
+import requests
+import json
+
+url = "http://localhost:3001/generate"
+
+payload = {
+    "canvasList": [
+        {
+            "index": 0,
+            "canvas_json": '{"version":"5.2.1","objects":[],"background":"#fff"}',
+            "width": 395,
+            "height": 618,
+            "bg_color": "#fff",
+            "name": "画布_1",
+            "canvas_type": "normal"
+        }
+    ],
+    "goodsList": [
+        {
+            "AC5120913": {
+                "款号": "E305-01003",
+                "货号资料": [
+                    {
+                        "货号": "A596351",
+                        "颜色": "黑色",
+                        "pics": {
+                            "俯视": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\1.png",
+                            "侧视": "C:\\Users\\Administrator\\Desktop\\img\\A596351\\2.png"
+                        }
+                    }
+                ]
+            }
+        }
+    ]
+}
+
+response = requests.post(url, json=payload)
+
+if response.status_code == 200:
+    result = response.json()
+    if result.get("code") == 0:
+        print(f"生成成功，共 {len(result['images'])} 张图片")
+        for img in result["images"]:
+            print(f"画布 {img['canvasIndex']} 的图片已生成")
+            # 可以保存 base64 图片
+            # data_url = img["dataUrl"]
+            # base64_data = data_url.split(",")[1]
+            # with open(f"output_{img['canvasIndex']}.png", "wb") as f:
+            #     f.write(base64.b64decode(base64_data))
+    else:
+        print(f"生成失败: {result.get('msg')}")
+else:
+    print(f"请求失败，状态码: {response.status_code}")
+```
+
+### cURL 示例
+
+```bash
+curl -X POST http://localhost:3001/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "canvasList": [
+      {
+        "index": 0,
+        "canvas_json": "{\"version\":\"5.2.1\",\"objects\":[],\"background\":\"#fff\"}",
+        "width": 395,
+        "height": 618,
+        "bg_color": "#fff",
+        "name": "画布_1",
+        "canvas_type": "normal"
+      }
+    ],
+    "goodsList": [
+      {
+        "AC5120913": {
+          "款号": "E305-01003",
+          "货号资料": [
+            {
+              "货号": "A596351",
+              "颜色": "黑色",
+              "pics": {
+                "俯视": "C:\\\\Users\\\\Administrator\\\\Desktop\\\\img\\\\A596351\\\\1.png",
+                "侧视": "C:\\\\Users\\\\Administrator\\\\Desktop\\\\img\\\\A596351\\\\2.png"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }'
+```
+
+---
+
+## 注意事项
+
+1. **运行环境限制**: 该接口仅在 Electron 渲染进程中可用，需要 Node.js 集成能力。在普通浏览器环境中无法使用。
+
+2. **端口占用**: 接口默认监听 `3001` 端口，确保该端口未被占用。
+
+3. **请求体大小**: 请求体大小限制为 50MB，超过此限制将返回 `413` 错误。
+
+4. **图片路径**: 
+   - 支持本地文件路径（Windows 路径格式：`C:\\Users\\...`）
+   - 确保图片文件存在且可访问
+
+5. **canvas_json 格式**: 
+   - 普通画布必须是有效的 Fabric.js JSON 字符串
+   - 场景图使用特殊值 `"scene"`
+
+6. **错误处理**: 建议在调用时捕获异常，并根据 `code` 字段判断请求是否成功。
+
+7. **base64 图片使用**: 
+   - 返回的 `dataUrl` 可直接用于 HTML `<img>` 标签的 `src` 属性
+   - 如需保存为文件，需要提取 base64 数据部分（去掉 `data:image/png;base64,` 前缀）
+
+---
+
+## 版本信息
+
+- **接口版本**: v1.0
+- **最后更新**: 2024-12-09
+