FashionCraft API 接口文档

基本信息

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

认证说明

JWT Token 使用方式

Authorization: Bearer {token}

Token 有效期

访问令牌：2小时
刷新令牌：7天

通用响应格式

成功响应

{
  "code": 200,
  "message": "操作成功",
  "data": {}
}

错误响应

{
  "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

请求参数: 无

成功响应:

{
  "status": "OK",
  "timestamp": "2025-07-03T12:00:00.000Z",
  "uptime": 3600.123
}

请求示例:

curl -X GET https://ghiuoimfghor.sealoshzh.site/health

1.2 获取系统配置

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

请求参数: 无

成功响应:

{
  "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

请求参数:

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

成功响应:

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

错误响应:

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

请求示例:

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

请求参数:

{
  "username": "string (用户名/邮箱/手机号)",
  "password": "string",
  "login_type": "string (可选: username/email/phone)"
}

成功响应:

{
  "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
    }
  }
}

错误响应:

{
  "code": 400,
  "message": "用户不存在"
}

请求示例:

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}

成功响应:

{
  "code": 200,
  "message": "登出成功"
}

2.4 刷新令牌

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

请求参数:

{
  "refresh_token": "string"
}

成功响应:

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

3. 用户信息管理

3.1 获取用户个人信息

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

请求头: Authorization: Bearer {token}

成功响应:

{
  "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}

请求参数:

{
  "nickname": "string (可选，最多50字符)",
  "bio": "string (可选，最多500字符)",
  "location": "string (可选，最多100字符)",
  "avatar": "string (可选，头像URL)"
}

成功响应:

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

3.3 修改密码

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

请求头: Authorization: Bearer {token}

请求参数:

{
  "old_password": "string",
  "new_password": "string (6-20字符)"
}

成功响应:

{
  "code": 200,
  "message": "密码修改成功"
}

错误响应:

{
  "code": 400,
  "message": "原密码错误"
}

4. 设计模块

4.1 创建设计项目

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

请求头: Authorization: Bearer {token}

请求参数:

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

成功响应:

{
  "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)

成功响应:

{
  "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}

成功响应:

{
  "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}

请求参数:

{
  "title": "string (可选)",
  "description": "string (可选)",
  "design_data": "object (可选)",
  "preview_images": "array (可选)",
  "status": "string (可选: draft/published/archived)"
}

成功响应:

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

4.5 删除设计

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

请求头: Authorization: Bearer {token}

成功响应:

{
  "code": 200,
  "message": "设计删除成功"
}

4.6 获取可用颜色列表

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

请求头: Authorization: Bearer {token}

成功响应:

{
  "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}

成功响应:

{
  "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}

请求参数:

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

成功响应:

{
  "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}

请求参数:

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

成功响应:

{
  "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}

请求参数:

{
  "message": "string (必填，对话内容)",
  "context": "object (可选，上下文信息)"
}

成功响应:

{
  "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 (可选，是否压缩)

成功响应:

{
  "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
  }
}

错误响应:

{
  "code": 413,
  "message": "文件大小超出限制"
}

6.2 上传3D模型

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

请求头: Authorization: Bearer {token}

请求参数: multipart/form-data

file: 3D模型文件 (.obj, .fbx, .glb, .gltf)

成功响应:

{
  "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个)

成功响应:

{
  "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 示例

// 基础配置
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 示例

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 服务器状态: 正常运行

api.md 20 KB Pysyvä linkki Historia Raaka

FashionCraft API 接口文档

基本信息

认证说明

JWT Token 使用方式

Token 有效期

通用响应格式

成功响应

错误响应

错误码说明

1. 系统接口

1.1 健康检查

1.2 获取系统配置

2. 用户认证接口

2.1 用户注册

2.2 用户登录

2.3 用户登出

2.4 刷新令牌

3. 用户信息管理

3.1 获取用户个人信息

3.2 更新用户个人信息

3.3 修改密码

4. 设计模块

4.1 创建设计项目

4.2 获取设计列表

4.3 获取设计详情

4.4 更新设计

4.5 删除设计

4.6 获取可用颜色列表

4.7 获取可用材质列表

5. AI推荐模块

5.1 AI配色推荐

5.2 AI风格推荐

5.3 AI设计助手对话

6. 文件上传模块

6.1 上传图片

6.2 上传3D模型

6.3 批量上传

7. 前端对接示例

JavaScript/Axios 示例

React Hook 示例

8. 常见问题

Q: Token过期怎么处理？

Q: 文件上传有什么限制？

Q: 如何处理网络错误？

Q: API有请求频率限制吗？

api.md 20 KB

Pysyvä linkki Historia Raaka