# 发型更换H5项目API文档

## 1. 文档说明

本文档描述了发型更换H5项目的API接口规范，所有前后端交互都应遵循此文档。任何API变更都应先修改此文档，然后再进行代码实现。

### 1.1 文档版本

| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| v1.0 | 2026-01-18 | 初始版本 | 系统生成 |
| v1.1 | 2026-02-10 | 补充发色更换接口，修正数据格式 | 系统更新 |

### 1.2 基本信息

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

## 2. 响应格式

### 2.1 成功响应

```json
{
  "success": true,
  "data": {...}
}
```

### 2.2 失败响应

```json
{
  "success": false,
  "message": "错误信息"
}
```

## 3. API接口列表

| 接口路径 | 方法 | 功能描述 | 请求参数 | 成功响应数据 |
|---------|------|----------|---------|-------------|
| `/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. 详细接口说明

### 4.1 获取发型列表

#### 4.1.1 请求信息
- **路径**: `/api/hairstyles`
- **方法**: GET
- **参数**: 无

#### 4.1.2 响应信息
- **状态码**: 200 OK
- **响应示例**:

```json
{
  "success": true,
  "data": {
    "hairstyles": [
      {
        "id": "1953267161121464322",
        "name": "发型4322",
        "image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267161121464322.jpg"
      },
      {
        "id": "1953267288284372994",
        "name": "发型2994",
        "image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267288284372994.jpg"
      }
    ]
  }
}
```

#### 4.1.3 字段说明

| 字段名 | 类型 | 描述 |
|-------|------|------|
| `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` | File | 是 | 用户上传的图片文件（支持 png/jpg/jpeg/gif，最大16MB） |
| `hairstyle_id` | String | 是 | 要更换的发型ID |

#### 4.2.2 响应信息
- **状态码**: 200 OK
- **响应示例**:

```json
{
  "success": true,
  "data": {
    "result_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
  }
}
```

#### 4.2.3 字段说明

| 字段名 | 类型 | 描述 |
|-------|------|------|
| `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 | `/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,
  "message": "请上传图片"
}
```

## 6. API变更流程

1. **文档修改**: 先修改本API文档，记录变更内容、原因和影响范围
2. **代码实现**: 根据文档修改后端API实现
3. **前端适配**: 前端根据文档修改进行适配
4. **测试验证**: 测试新API的功能和兼容性
5. **部署上线**: 按计划部署变更

## 7. 附录

### 7.1 数据结构定义

#### 7.1.1 发型对象 (Hairstyle)

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

#### 7.1.2 更换发型请求 (ChangeHairRequest)

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

#### 7.1.3 更换发型响应 (ChangeHairResponse)

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

#### 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