save code

2026-02-10 18:22:21 +08:00
parent cf1cbbd597
commit f67f18dd39
4 changed files with 666 additions and 59 deletions
@@ -9,25 +9,24 @@
 | 版本 | 日期 | 描述 | 作者 |
 |------|------|------|------|
 | v1.0 | 2026-01-18 | 初始版本 | 系统生成 |
+| v1.1 | 2026-02-10 | 补充发色更换接口，修正数据格式 | 系统更新 |

 ### 1.2 基本信息

 - **API基础路径**: `/api`
+- **服务端口**: 5000（Flask）
 - **响应格式**: JSON
 - **字符编码**: UTF-8
 - **认证方式**: 无需认证

 ## 2. 响应格式

-所有API响应均采用统一的格式：
-
 ### 2.1 成功响应

 ```json
 {
  "success": true,
-  "data": {...},
-  "message": ""
+  "data": {...}
 }
 ```

@@ -36,7 +35,6 @@
 ```json
 {
  "success": false,
-  "data": null,
  "message": "错误信息"
 }
 ```
@@ -47,6 +45,7 @@
 |---------|------|----------|---------|-------------|
 | `/api/hairstyles` | GET | 获取发型列表 | 无 | `{ "hairstyles": [...] }` |
 | `/api/change-hair` | POST | 更换发型 | image: 文件<br>hairstyle_id: 字符串 | `{ "result_image": "data:image/jpeg;base64,..." }` |
+| `/api/change-hair-color` | POST | 更换头发颜色 | image: 文件<br>rgb: 字符串<br>ratio: 字符串 | `{ "result_image": "data:image/jpeg;base64,..." }` |

 ## 4. 详细接口说明

@@ -67,18 +66,17 @@
  "data": {
    "hairstyles": [
      {
-        "id": "hair_001",
-        "name": "发型1",
-        "image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267183426772993.jpg"
+        "id": "1953267161121464322",
+        "name": "发型4322",
+        "image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267161121464322.jpg"
      },
      {
-        "id": "hair_002",
-        "name": "发型2",
-        "image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267306382794754.jpg"
+        "id": "1953267288284372994",
+        "name": "发型2994",
+        "image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267288284372994.jpg"
      }
    ]
-  },
-  "message": ""
+  }
 }
 ```

@@ -86,18 +84,22 @@

 | 字段名 | 类型 | 描述 |
 |-------|------|------|
-| `id` | 字符串 | 发型唯一标识符 |
-| `name` | 字符串 | 发型名称 |
-| `image_url` | 字符串 | 发型图片的OSS URL |
+| `id` | 字符串 | 发型唯一标识符（长数字串，来源于 hairId2url.txt） |
+| `name` | 字符串 | 发型名称（格式为 "发型" + ID后4位） |
+| `image_url` | 字符串 | 发型图片的阿里云 OSS URL |

 ### 4.2 更换发型

 #### 4.2.1 请求信息
 - **路径**: `/api/change-hair`
 - **方法**: POST
+- **Content-Type**: `multipart/form-data`
 - **参数**:
-  - `image`: 文件 (必填) - 用户上传的图片文件
-  - `hairstyle_id`: 字符串 (必填) - 要更换的发型ID
+
+| 参数名 | 类型 | 必填 | 描述 |
+|-------|------|------|------|
+| `image` | File | 是 | 用户上传的图片文件（支持 png/jpg/jpeg/gif，最大16MB） |
+| `hairstyle_id` | String | 是 | 要更换的发型ID |

 #### 4.2.2 响应信息
 - **状态码**: 200 OK
@@ -108,8 +110,7 @@
  "success": true,
  "data": {
    "result_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
-  },
-  "message": ""
+  }
 }
 ```

@@ -117,23 +118,72 @@

 | 字段名 | 类型 | 描述 |
 |-------|------|------|
-| `result_image` | 字符串 | 发型更换后的图片，Base64编码格式 |
+| `result_image` | 字符串 | 发型更换后的图片，Base64 Data URL 格式 |
+
+#### 4.2.4 备注
+- 远程AI处理耗时较长，超时时间为120秒
+- 如果远程API调用失败，会返回原始图片作为降级处理
+
+### 4.3 更换头发颜色
+
+#### 4.3.1 请求信息
+- **路径**: `/api/change-hair-color`
+- **方法**: POST
+- **Content-Type**: `multipart/form-data`
+- **参数**:
+
+| 参数名 | 类型 | 必填 | 描述 |
+|-------|------|------|------|
+| `image` | File | 是 | 用户上传的图片文件（支持 png/jpg/jpeg/gif，最大16MB） |
+| `rgb` | String | 是 | RGB颜色值，格式为 `"[R, G, B]"`，例如 `"[255, 106, 0]"` |
+| `ratio` | String | 是 | 颜色替换强度，范围 0.0 ~ 1.0，例如 `"0.9"` |
+
+#### 4.3.2 响应信息
+- **状态码**: 200 OK
+- **响应示例**:
+
+```json
+{
+  "success": true,
+  "data": {
+    "result_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
+  }
+}
+```
+
+#### 4.3.3 字段说明
+
+| 字段名 | 类型 | 描述 |
+|-------|------|------|
+| `result_image` | 字符串 | 发色更换后的图片，Base64 Data URL 格式 |
+
+#### 4.3.4 备注
+- 远程AI处理耗时较长，超时时间为120秒
+- 如果远程API调用失败，会返回原始图片作为降级处理
+- ratio 值越大，颜色替换效果越明显

 ## 5. 错误处理

 ### 5.1 常见错误状态码

-| 状态码 | 描述 | 示例消息 |
-|-------|------|---------|
-| 400 | 请求参数错误 | "请上传图片"、"请选择发型" |
-| 500 | 服务器内部错误 | "获取发型列表失败: [错误信息]" |
+| 状态码 | 接口 | 描述 | 示例消息 |
+|-------|------|------|---------|
+| 400 | `/api/change-hair` | 缺少图片 | "请上传图片" |
+| 400 | `/api/change-hair` | 缺少发型ID | "请选择发型" |
+| 400 | `/api/change-hair` | 文件类型不合法 | "不支持的文件类型，请上传图片文件" |
+| 400 | `/api/change-hair-color` | 缺少图片 | "请上传图片" |
+| 400 | `/api/change-hair-color` | 缺少颜色值 | "请选择颜色" |
+| 400 | `/api/change-hair-color` | 缺少替换比例 | "请设置更换比例" |
+| 400 | `/api/change-hair-color` | 文件类型不合法 | "不支持的文件类型，请上传图片文件" |
+| 500 | `/api/hairstyles` | 服务器内部错误 | "获取发型列表失败: [错误信息]" |
+| 500 | `/api/change-hair` | 处理失败 | "处理图片失败: [错误信息]" |
+| 500 | `/api/change-hair-color` | 处理失败 | "处理图片失败: [错误信息]" |

 ### 5.2 错误响应示例

 ```json
 {
  "success": false,
-  "data": null,
  "message": "请上传图片"
 }
 ```
@@ -146,60 +196,71 @@
 4. **测试验证**: 测试新API的功能和兼容性
 5. **部署上线**: 按计划部署变更

-## 7. 版本控制
+## 7. 附录

-当API需要重大变更时，应采用版本控制机制：
+### 7.1 数据结构定义

-1. **URL版本控制**: 在API路径中添加版本号，如 `/api/v2/hairstyles`
-2. **向后兼容**: 保留旧版本API一段时间，确保前端有足够时间迁移
-3. **弃用通知**: 在响应中添加弃用警告，提示开发者使用新API
-
-## 8. 最佳实践
-
-1. **使用标准HTTP方法**: GET用于获取数据，POST用于提交数据
-2. **保持接口幂等性**: 相同请求应产生相同结果
-3. **合理设置缓存**: 对频繁访问的数据进行缓存，提高性能
-4. **限流保护**: 对API调用进行限流，防止滥用
-5. **日志记录**: 记录API调用日志，便于问题排查
-
-## 9. 附录
-
-### 9.1 数据结构定义
-
-#### 9.1.1 发型对象 (Hairstyle)
+#### 7.1.1 发型对象 (Hairstyle)

 ```json
 {
-  "id": "string",
-  "name": "string",
-  "image_url": "string"
+  "id": "1953267161121464322",
+  "name": "发型4322",
+  "image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267161121464322.jpg"
 }
 ```

-#### 9.1.2 更换发型请求 (ChangeHairRequest)
+#### 7.1.2 更换发型请求 (ChangeHairRequest)

 ```
 FormData:
 - image: File
- hairstyle_id: string
+- hairstyle_id: string (例: "1953267161121464322")
 ```

-#### 9.1.3 更换发型响应 (ChangeHairResponse)
+#### 7.1.3 更换发型响应 (ChangeHairResponse)

 ```json
 {
-  "result_image": "string"
+  "success": true,
+  "data": {
+    "result_image": "data:image/jpeg;base64,..."
+  }
 }
 ```

-### 9.2 开发工具推荐
+#### 7.1.4 更换发色请求 (ChangeHairColorRequest)
+
+```
+FormData:
+- image: File
+- rgb: string (例: "[255, 106, 0]")
+- ratio: string (例: "0.9")
+```
+
+#### 7.1.5 更换发色响应 (ChangeHairColorResponse)
+
+```json
+{
+  "success": true,
+  "data": {
+    "result_image": "data:image/jpeg;base64,..."
+  }
+}
+```
+
+### 7.2 支持的图片格式
+
+| 格式 | MIME类型 |
+|------|----------|
+| PNG | image/png |
+| JPG/JPEG | image/jpeg |
+| GIF | image/gif |
+
+文件大小限制：16MB
+
+### 7.3 开发工具推荐

 - **API测试**: Postman, Insomnia
 - **文档生成**: Swagger, ReDoc
 - **代码生成**: OpenAPI Generator
-
-### 9.3 相关链接
-
- [RESTful API设计指南](https://restfulapi.net/)
- [OpenAPI规范](https://swagger.io/specification/)
- [HTTP状态码](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)