# FashionCraft API 接口文档

## 基本信息

- **服务器地址**: `https://ghiuoimfghor.sealoshzh.site/`
- **API版本**: v1.0
- **数据格式**: JSON
- **字符编码**: UTF-8
- **认证方式**: JWT Bearer Token

## 认证说明

### JWT Token 使用方式
```http
Authorization: Bearer {token}
```

### Token 有效期
- 访问令牌：2小时
- 刷新令牌：7天

## 通用响应格式

### 成功响应
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {}
}
```

### 错误响应
```json
{
  "code": 400,
  "message": "错误信息",
  "errors": []
}
```

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未认证或Token无效 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 413 | 文件过大 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |
| 1001 | 用户名已存在 |
| 1002 | 邮箱已注册 |
| 1003 | 验证码错误 |
| 2001 | 设计保存失败 |
| 2002 | 文件上传失败 |
| 3001 | AI服务暂时不可用 |

---

## 1. 系统接口

### 1.1 健康检查

**接口地址**: `GET /health`

**请求参数**: 无

**成功响应**:
```json
{
  "status": "OK",
  "timestamp": "2025-07-03T12:00:00.000Z",
  "uptime": 3600.123
}
```

**请求示例**:
```bash
curl -X GET https://ghiuoimfghor.sealoshzh.site/health
```

### 1.2 获取系统配置

**接口地址**: `GET /api/system/config`

**请求参数**: 无

**成功响应**:
```json
{
  "code": 200,
  "data": {
    "app_version": "1.0.0",
    "features": {
      "ai_enabled": true,
      "3d_fitting_enabled": true,
      "community_enabled": true,
      "payment_enabled": false,
      "advanced_design_tools": true
    },
    "limits": {
      "max_designs": 100,
      "max_file_size": 52428800,
      "max_images_per_work": 10,
      "max_upload_files_batch": 10
    },
    "supported_formats": {
      "images": ["jpg", "jpeg", "png", "gif", "webp"],
      "3d_models": ["obj", "fbx", "glb", "gltf"],
      "designs": ["json"]
    }
  }
}
```

---

## 2. 用户认证接口

### 2.1 用户注册

**接口地址**: `POST /api/auth/register`

**请求参数**:
```json
{
  "username": "string (3-20字符，字母数字下划线)",
  "email": "string (邮箱格式)",
  "password": "string (6-20字符)",
  "phone": "string (可选，手机号格式)"
}
```

**成功响应**:
```json
{
  "code": 200,
  "message": "注册成功",
  "data": {
    "user_id": "686675d25ae926efd83830da",
    "username": "testuser123",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200
  }
}
```

**错误响应**:
```json
{
  "code": 400,
  "message": "输入数据验证失败",
  "errors": [
    {
      "type": "field",
      "msg": "用户名长度必须在3-20字符之间",
      "path": "username",
      "location": "body"
    }
  ]
}
```

**请求示例**:
```bash
curl -X POST https://ghiuoimfghor.sealoshzh.site/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser123",
    "email": "user@example.com",
    "password": "password123",
    "phone": "13888888888"
  }'
```

### 2.2 用户登录

**接口地址**: `POST /api/auth/login`

**请求参数**:
```json
{
  "username": "string (用户名/邮箱/手机号)",
  "password": "string",
  "login_type": "string (可选: username/email/phone)"
}
```

**成功响应**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user_id": "686675d25ae926efd83830da",
    "username": "testuser123",
    "avatar": "",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200,
    "user_info": {
      "nickname": "testuser123",
      "bio": "",
      "location": "",
      "level": 1,
      "experience": 0
    }
  }
}
```

**错误响应**:
```json
{
  "code": 400,
  "message": "用户不存在"
}
```

**请求示例**:
```bash
curl -X POST https://ghiuoimfghor.sealoshzh.site/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser123",
    "password": "password123"
  }'
```

### 2.3 用户登出

**接口地址**: `POST /api/auth/logout`

**请求头**: `Authorization: Bearer {token}`

**成功响应**:
```json
{
  "code": 200,
  "message": "登出成功"
}
```

### 2.4 刷新令牌

**接口地址**: `POST /api/auth/refresh-token`

**请求参数**:
```json
{
  "refresh_token": "string"
}
```

**成功响应**:
```json
{
  "code": 200,
  "message": "令牌刷新成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200
  }
}
```

---

## 3. 用户信息管理

### 3.1 获取用户个人信息

**接口地址**: `GET /api/user/profile`

**请求头**: `Authorization: Bearer {token}`

**成功响应**:
```json
{
  "code": 200,
  "data": {
    "user_id": "686675d25ae926efd83830da",
    "username": "testuser123",
    "nickname": "testuser123",
    "avatar": "",
    "bio": "",
    "location": "",
    "email": "test@example.com",
    "phone": "13888888888",
    "level": 1,
    "experience": 0,
    "followers_count": 0,
    "following_count": 0,
    "works_count": 1,
    "created_at": "2025-07-03T12:21:38.650Z"
  }
}
```

### 3.2 更新用户个人信息

**接口地址**: `PUT /api/user/profile`

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "nickname": "string (可选，最多50字符)",
  "bio": "string (可选，最多500字符)",
  "location": "string (可选，最多100字符)",
  "avatar": "string (可选，头像URL)"
}
```

**成功响应**:
```json
{
  "code": 200,
  "message": "个人信息更新成功",
  "data": {
    "user_id": "686675d25ae926efd83830da",
    "username": "testuser123",
    "nickname": "新昵称",
    "bio": "新的个人简介",
    // ... 其他字段
  }
}
```

### 3.3 修改密码

**接口地址**: `POST /api/user/change-password`

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "old_password": "string",
  "new_password": "string (6-20字符)"
}
```

**成功响应**:
```json
{
  "code": 200,
  "message": "密码修改成功"
}
```

**错误响应**:
```json
{
  "code": 400,
  "message": "原密码错误"
}
```

---

## 4. 设计模块

### 4.1 创建设计项目

**接口地址**: `POST /api/design/create`

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "title": "string (必填，最多100字符)",
  "description": "string (可选，最多1000字符)",
  "category": "string (必填: shirt/jacket/dress/pants/skirt/coat/sweater/other)",
  "is_public": "boolean (可选，默认false)"
}
```

**成功响应**:
```json
{
  "code": 200,
  "data": {
    "design_id": "686675d25ae926efd83830df",
    "title": "测试设计",
    "created_at": "2025-07-03T12:21:38.785Z"
  }
}
```

### 4.2 获取设计列表

**接口地址**: `GET /api/design/list`

**请求头**: `Authorization: Bearer {token}`

**查询参数**:
- `page`: number (页码，默认1)
- `page_size`: number (每页数量，默认20，最大100)
- `category`: string (可选，分类筛选)
- `status`: string (可选: draft/published/archived)

**成功响应**:
```json
{
  "code": 200,
  "data": {
    "designs": [
      {
        "stats": {
          "views": 0,
          "likes": 0,
          "forks": 0,
          "downloads": 0
        },
        "_id": "686675d25ae926efd83830df",
        "title": "测试设计",
        "description": "这是一个测试设计",
        "category": "shirt",
        "status": "draft",
        "preview_images": [],
        "createdAt": "2025-07-03T12:21:38.785Z",
        "updatedAt": "2025-07-03T12:21:38.785Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 1,
      "total_pages": 1,
      "has_next": false
    }
  }
}
```

### 4.3 获取设计详情

**接口地址**: `GET /api/design/{design_id}`

**请求头**: `Authorization: Bearer {token}`

**成功响应**:
```json
{
  "code": 200,
  "data": {
    "design_id": "686675d25ae926efd83830df",
    "title": "测试设计",
    "description": "这是一个测试设计",
    "category": "shirt",
    "status": "draft",
    "design_data": {
      "colors": {},
      "materials": {},
      "patterns": {},
      "embroidery": {},
      "accessories": {},
      "measurements": {}
    },
    "preview_images": [],
    "3d_model_url": null,
    "tags": [],
    "stats": {
      "views": 0,
      "likes": 0,
      "forks": 0,
      "downloads": 0
    },
    "author": {
      "user_id": "686675d25ae926efd83830da",
      "username": "testuser123",
      "nickname": "testuser123",
      "avatar": ""
    },
    "created_at": "2025-07-03T12:21:38.785Z",
    "updated_at": "2025-07-03T12:21:38.785Z"
  }
}
```

### 4.4 更新设计

**接口地址**: `PUT /api/design/{design_id}`

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "title": "string (可选)",
  "description": "string (可选)",
  "design_data": "object (可选)",
  "preview_images": "array (可选)",
  "status": "string (可选: draft/published/archived)"
}
```

**成功响应**:
```json
{
  "code": 200,
  "message": "设计更新成功",
  "data": {
    // 更新后的设计对象
  }
}
```

### 4.5 删除设计

**接口地址**: `DELETE /api/design/{design_id}`

**请求头**: `Authorization: Bearer {token}`

**成功响应**:
```json
{
  "code": 200,
  "message": "设计删除成功"
}
```

### 4.6 获取可用颜色列表

**接口地址**: `GET /api/design/colors`

**请求头**: `Authorization: Bearer {token}`

**成功响应**:
```json
{
  "code": 200,
  "data": [
    {
      "color_id": "red",
      "color_name": "红色",
      "color_code": "#FF0000",
      "color_category": "warm",
      "preview_url": "/colors/red.jpg"
    },
    {
      "color_id": "blue",
      "color_name": "蓝色",
      "color_code": "#0000FF",
      "color_category": "cool",
      "preview_url": "/colors/blue.jpg"
    }
  ]
}
```

### 4.7 获取可用材质列表

**接口地址**: `GET /api/design/materials`

**请求头**: `Authorization: Bearer {token}`

**成功响应**:
```json
{
  "code": 200,
  "data": [
    {
      "material_id": "cotton",
      "material_name": "棉质",
      "description": "舒适透气",
      "category": "natural",
      "preview_url": "/materials/cotton.jpg"
    },
    {
      "material_id": "silk",
      "material_name": "丝绸",
      "description": "光滑柔软",
      "category": "natural",
      "preview_url": "/materials/silk.jpg"
    }
  ]
}
```

---

## 5. AI推荐模块

### 5.1 AI配色推荐

**接口地址**: `POST /api/ai/recommend/colors`

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "style": "string (必填: business/casual/party/elegant)",
  "base_color": "string (必填，基础颜色)",
  "season": "string (可选: spring/summer/autumn/winter)",
  "occasion": "string (可选，场合描述)"
}
```

**成功响应**:
```json
{
  "code": 200,
  "data": {
    "recommendations": [
      {
        "scheme_id": "scheme_1",
        "scheme_name": "经典商务配色",
        "colors": {
          "s1": "#1E3A8A",
          "t1": "#FFFFFF",
          "y1": "#000000",
          "z1": "#C0C0C0"
        },
        "confidence": 0.95,
        "theory": {
          "color_psychology": "蓝色传达专业和信任，白色增加清洁感",
          "harmony_type": "单色调和",
          "description": "适合商务场合的经典配色方案"
        }
      }
    ],
    "analysis": {
      "color_theory": "基于色彩心理学和服装美学原理",
      "style_analysis": "business风格强调专业性和权威感",
      "suggestions": [
        "建议在主色调基础上添加少量对比色",
        "注意颜色的明度和饱和度平衡"
      ]
    }
  }
}
```

### 5.2 AI风格推荐

**接口地址**: `POST /api/ai/recommend/style`

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "user_preferences": "object (必填，用户偏好)",
  "occasion": "string (可选，场合)",
  "body_type": "string (可选，体型)",
  "skin_tone": "string (可选，肤色)"
}
```

**成功响应**:
```json
{
  "code": 200,
  "data": {
    "recommendations": [
      {
        "style_id": "minimalist",
        "style_name": "简约风格",
        "description": "简洁线条，经典剪裁，注重质感",
        "suitability_score": 0.92,
        "reasons": ["符合您的简约偏好", "适合多种场合"],
        "suggestions": {
          "colors": ["黑色", "白色", "灰色", "驼色"],
          "materials": ["羊毛", "棉质", "丝绸"],
          "cuts": ["直筒", "A字型", "修身"]
        }
      }
    ],
    "analysis": {
      "body_type_analysis": "体型分析建议",
      "skin_tone_analysis": "肤色分析建议",
      "occasion_tips": "场合建议"
    }
  }
}
```

### 5.3 AI设计助手对话

**接口地址**: `POST /api/ai/chat`

**请求头**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "message": "string (必填，对话内容)",
  "context": "object (可选，上下文信息)"
}
```

**成功响应**:
```json
{
  "code": 200,
  "data": {
    "response": "很高兴为您提供设计建议！针对配色问题...",
    "suggestions": [
      {
        "type": "color",
        "content": {
          "colors": ["#1E3A8A", "#FFFFFF", "#EF4444"]
        },
        "reason": "基于您的询问推荐的经典商务配色"
      }
    ],
    "conversation_id": "conv_1751545123_686675d25ae926efd83830da"
  }
}
```

---

## 6. 文件上传模块

### 6.1 上传图片

**接口地址**: `POST /api/upload/image`

**请求头**: `Authorization: Bearer {token}`

**请求参数**: multipart/form-data
- `file`: 图片文件
- `category`: string (可选: avatar/design/pattern/texture)
- `compress`: boolean (可选，是否压缩)

**成功响应**:
```json
{
  "code": 200,
  "data": {
    "file_id": "550e8400-e29b-41d4-a716-446655440000",
    "file_url": "/uploads/general/filename.jpg",
    "file_size": 1024000,
    "mime_type": "image/jpeg",
    "width": null,
    "height": null
  }
}
```

**错误响应**:
```json
{
  "code": 413,
  "message": "文件大小超出限制"
}
```

### 6.2 上传3D模型

**接口地址**: `POST /api/upload/3d-model`

**请求头**: `Authorization: Bearer {token}`

**请求参数**: multipart/form-data
- `file`: 3D模型文件 (.obj, .fbx, .glb, .gltf)

**成功响应**:
```json
{
  "code": 200,
  "data": {
    "file_id": "550e8400-e29b-41d4-a716-446655440000",
    "file_url": "/uploads/general/model.obj",
    "file_size": 2048000,
    "mime_type": "application/octet-stream",
    "file_type": "3d_model"
  }
}
```

### 6.3 批量上传

**接口地址**: `POST /api/upload/batch`

**请求头**: `Authorization: Bearer {token}`

**请求参数**: multipart/form-data
- `files`: 文件数组 (最多10个)

**成功响应**:
```json
{
  "code": 200,
  "data": {
    "files": [
      {
        "file_id": "550e8400-e29b-41d4-a716-446655440000",
        "file_url": "/uploads/general/file1.jpg",
        "file_size": 1024000,
        "mime_type": "image/jpeg",
        "original_name": "photo1.jpg",
        "width": null,
        "height": null
      }
    ],
    "total": 1
  }
}
```

---

## 7. 前端对接示例

### JavaScript/Axios 示例

```javascript
// 基础配置
const API_BASE_URL = 'https://ghiuoimfghor.sealoshzh.site/api';
let authToken = localStorage.getItem('token');

// 设置请求拦截器
const api = axios.create({
  baseURL: API_BASE_URL,
  timeout: 10000
});

api.interceptors.request.use(config => {
  if (authToken) {
    config.headers.Authorization = `Bearer ${authToken}`;
  }
  return config;
});

// 用户注册
async function register(userData) {
  try {
    const response = await api.post('/auth/register', userData);
    if (response.data.code === 200) {
      authToken = response.data.data.token;
      localStorage.setItem('token', authToken);
      return response.data;
    }
  } catch (error) {
    console.error('注册失败:', error.response.data);
    throw error;
  }
}

// 用户登录
async function login(credentials) {
  try {
    const response = await api.post('/auth/login', credentials);
    if (response.data.code === 200) {
      authToken = response.data.data.token;
      localStorage.setItem('token', authToken);
      return response.data;
    }
  } catch (error) {
    console.error('登录失败:', error.response.data);
    throw error;
  }
}

// 获取用户信息
async function getUserProfile() {
  try {
    const response = await api.get('/user/profile');
    return response.data.data;
  } catch (error) {
    console.error('获取用户信息失败:', error.response.data);
    throw error;
  }
}

// 创建设计
async function createDesign(designData) {
  try {
    const response = await api.post('/design/create', designData);
    return response.data.data;
  } catch (error) {
    console.error('创建设计失败:', error.response.data);
    throw error;
  }
}

// 上传文件
async function uploadImage(file, category = 'general') {
  try {
    const formData = new FormData();
    formData.append('file', file);
    formData.append('category', category);
    
    const response = await api.post('/upload/image', formData, {
      headers: {
        'Content-Type': 'multipart/form-data'
      }
    });
    return response.data.data;
  } catch (error) {
    console.error('文件上传失败:', error.response.data);
    throw error;
  }
}
```

### React Hook 示例

```javascript
import { useState, useEffect } from 'react';

// 自定义Hook - 用户认证
export function useAuth() {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const token = localStorage.getItem('token');
    if (token) {
      getUserProfile().then(setUser).catch(() => {
        localStorage.removeItem('token');
      }).finally(() => setLoading(false));
    } else {
      setLoading(false);
    }
  }, []);

  const login = async (credentials) => {
    const result = await api.post('/auth/login', credentials);
    setUser(result.data.data);
    return result.data;
  };

  const logout = () => {
    localStorage.removeItem('token');
    setUser(null);
  };

  return { user, loading, login, logout };
}

// 自定义Hook - 设计管理
export function useDesigns() {
  const [designs, setDesigns] = useState([]);
  const [loading, setLoading] = useState(false);

  const fetchDesigns = async (params = {}) => {
    setLoading(true);
    try {
      const response = await api.get('/design/list', { params });
      setDesigns(response.data.data.designs);
    } catch (error) {
      console.error('获取设计列表失败:', error);
    } finally {
      setLoading(false);
    }
  };

  const createDesign = async (designData) => {
    const response = await api.post('/design/create', designData);
    await fetchDesigns(); // 刷新列表
    return response.data.data;
  };

  return { designs, loading, fetchDesigns, createDesign };
}
```

---

## 8. 常见问题

### Q: Token过期怎么处理？
A: 收到401错误时，使用refresh_token刷新或重新登录

### Q: 文件上传有什么限制？
A: 单文件最大50MB，批量上传最多10个文件

### Q: 如何处理网络错误？
A: 建议添加重试机制和错误提示

### Q: API有请求频率限制吗？
A: 是的，登录用户1000次/小时，未登录100次/小时

---

**文档更新时间**: 2025-07-03
**API版本**: v1.0
**服务器状态**: 正常运行