5e35532dbb
- 添加 FloorOption 结构体字段支持尺寸、描述和变体信息 - 优化 loadFloorOptions 函数，实现按品牌和花色名称去重并附带多尺寸变体 - 区分木材、瓷砖、乙烯基和层压板产品，并分类返回 - 更新室内铺装纹理选项，完善图案描述和名称本地化 - 丰富Floor Options API响应数据，包含尺寸、变体、描述等字段 - 增强AI换地板功能，支持尺寸变体SKU，自动调整物理尺寸比例 - 完善地板替换的AI提示词，增加材质锁定、尺寸说明和纹理一致性要求 - 改进地板识别蒙版生成逻辑，确保精准分割地板区域 - Redis任务状态查询接口增加耗时统计字段，提供更细粒度进度信息 - 更新go.mod依赖，新增redis和gorm相关包支持
2455 lines
73 KiB
JSON
2455 lines
73 KiB
JSON
{
|
||
"openapi": "3.0.3",
|
||
"info": {
|
||
"title": "FloorVisualizer API",
|
||
"description": "FloorVisualizer 后端接口文档\n\n## 全局响应格式\n所有 API 统一返回 JSON 信封格式：\n```\n成功: {\"code\": 200, \"data\": {...}}\n失败: {\"code\": 400, \"error\": \"错误描述\"}\n```\n\n认证方式：注册/登录获取 JWT token，在需要认证的接口中设置 Header: Authorization: Bearer {token}\n\n---\n## 产品筛选层层递进说明\n产品列表支持 category / material / color_tone / finish / wood_species / brand / series_name 多维度组合筛选。\n前端实现层层递进：用户每选一个筛选项，将已选参数传给 /products 获取结果，再根据返回的 filter_options 动态更新其他筛选项的可选范围。\n\n---\n## AI换地板对接说明\n1. GET /floor/options 获取可用的地板样式（从产品库动态加载，每个样式对应真实SKU）\n2. POST /floor/generate 上传图片 + floor_id（产品SKU）+ pattern_code（1-9）+ room_code（0-7）→ 返回 job_id\n3. GET /floor/progress?job_id=xxx（SSE）跟踪进度 → check → mask → inpaint → done\n4. 生成完成后保存到用户项目：POST /user/projects\n\n---\n## 数字编码对照\n\n### 铺设方式 (pattern_code)\n| code | 木地板 | 瓷砖 |\n|------|--------|------|\n| 1 | Straight Lay | — |\n| 2 | Horizontal Lay | — |\n| 3 | Herringbone | — |\n| 4 | Chevron | — |\n| 5 | — | Straight Grid |\n| 6 | — | Running Bond |\n| 7 | — | 1/3 Offset |\n| 8 | — | Hexagonal |\n| 9 | — | Diagonal (45°) |\n\n### 房间类型 (room_code)\n| code | 房间 |\n|------|------|\n| 0 | Auto Detect（不传房间信息给AI） |\n| 1 | Living Room |\n| 2 | Bedroom |\n| 3 | Kitchen |\n| 4 | Dining Room |\n| 5 | Bathroom |\n| 6 | Study Room |\n| 7 | Hallway |\n\n---\n## 静态文件路径\n- 上传图片: /static/images/\n- 知识图片: /knowledge_images/ 或 /images/knowledge/\n- 生成结果: /outputs/\n- 用户上传: /uploads/",
|
||
"version": "1.0.0"
|
||
},
|
||
"servers": [
|
||
{
|
||
"url": "http://localhost:8099",
|
||
"description": "本地开发环境"
|
||
}
|
||
],
|
||
"components": {
|
||
"securitySchemes": {
|
||
"BearerAuth": {
|
||
"type": "http",
|
||
"scheme": "bearer",
|
||
"bearerFormat": "JWT",
|
||
"description": "注册或登录后获取的 JWT token"
|
||
}
|
||
},
|
||
"schemas": {
|
||
"AuthResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"token": {
|
||
"type": "string",
|
||
"description": "JWT token，后续请求放 Authorization header"
|
||
},
|
||
"user": {
|
||
"$ref": "#/components/schemas/User"
|
||
}
|
||
},
|
||
"example": {
|
||
"username": "demo",
|
||
"password": "123456",
|
||
"name": "Demo User"
|
||
}
|
||
},
|
||
"User": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "用户唯一ID (UUID)"
|
||
},
|
||
"username": {
|
||
"type": "string",
|
||
"description": "用户名"
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "显示名称"
|
||
},
|
||
"avatar_url": {
|
||
"type": "string",
|
||
"description": "头像URL"
|
||
},
|
||
"created_at": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"description": "注册时间"
|
||
},
|
||
"updated_at": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"description": "更新时间"
|
||
}
|
||
}
|
||
},
|
||
"Favorite": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "integer",
|
||
"description": "收藏记录ID"
|
||
},
|
||
"user_id": {
|
||
"type": "string",
|
||
"description": "用户ID"
|
||
},
|
||
"sku": {
|
||
"type": "string",
|
||
"description": "产品SKU编码"
|
||
},
|
||
"brand": {
|
||
"type": "string",
|
||
"description": "品牌"
|
||
},
|
||
"series_name": {
|
||
"type": "string",
|
||
"description": "系列名称"
|
||
},
|
||
"style_name": {
|
||
"type": "string",
|
||
"description": "花色/款式名称"
|
||
},
|
||
"main_image_url": {
|
||
"type": "string",
|
||
"description": "产品主图URL"
|
||
},
|
||
"category": {
|
||
"type": "string",
|
||
"description": "分类"
|
||
},
|
||
"material": {
|
||
"type": "string",
|
||
"description": "材质"
|
||
},
|
||
"color_tone": {
|
||
"type": "string",
|
||
"description": "色调"
|
||
},
|
||
"price_per_sqft": {
|
||
"type": "number",
|
||
"description": "每平方英尺价格"
|
||
},
|
||
"created_at": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"description": "收藏时间"
|
||
}
|
||
}
|
||
},
|
||
"Project": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "项目唯一ID (UUID)"
|
||
},
|
||
"user_id": {
|
||
"type": "string",
|
||
"description": "用户ID"
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "项目名称"
|
||
},
|
||
"original_image_url": {
|
||
"type": "string",
|
||
"description": "换地板前的原图URL"
|
||
},
|
||
"generated_image_url": {
|
||
"type": "string",
|
||
"description": "AI生成后的效果图URL"
|
||
},
|
||
"floor_style": {
|
||
"type": "string",
|
||
"description": "使用的款式（如 Light Oak）"
|
||
},
|
||
"pattern": {
|
||
"type": "string",
|
||
"description": "铺设方式（如 Herringbone, Straight Lay）"
|
||
},
|
||
"room_type": {
|
||
"type": "string",
|
||
"description": "房间类型（如 Living Room）"
|
||
},
|
||
"created_at": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"description": "创建时间"
|
||
},
|
||
"updated_at": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"description": "更新时间"
|
||
}
|
||
}
|
||
},
|
||
"ProductItem": {
|
||
"type": "object",
|
||
"properties": {
|
||
"brand": {
|
||
"type": "string",
|
||
"description": "品牌"
|
||
},
|
||
"series_name": {
|
||
"type": "string",
|
||
"description": "系列名称"
|
||
},
|
||
"style_name": {
|
||
"type": "string",
|
||
"description": "花色/款式名称"
|
||
},
|
||
"sku": {
|
||
"type": "string",
|
||
"description": "产品SKU编码"
|
||
},
|
||
"category": {
|
||
"type": "string",
|
||
"description": "分类（Hardwood / Laminate / SPC/LVP / Engineered Wood / Wood-Look Tile）"
|
||
},
|
||
"material": {
|
||
"type": "string",
|
||
"description": "材质（如 Oak, Porcelain, Walnut）"
|
||
},
|
||
"color_tone": {
|
||
"type": "string",
|
||
"description": "色调（如 Light Gray, Natural Oak, Dark Brown）"
|
||
},
|
||
"finish": {
|
||
"type": "string",
|
||
"description": "表面处理（如 Matte, Gloss, Textured）"
|
||
},
|
||
"price_per_sqft": {
|
||
"type": "number",
|
||
"description": "每平方英尺价格（美元）"
|
||
},
|
||
"price_tier": {
|
||
"type": "string",
|
||
"description": "价格段位（Budget/Value, Mid-Range, Upper Mid-Range, Premium）"
|
||
},
|
||
"main_image_url": {
|
||
"type": "string",
|
||
"description": "产品主图URL"
|
||
},
|
||
"size_label": {
|
||
"type": "string",
|
||
"description": "Size label"
|
||
},
|
||
"coverage_sqft_per_box": {
|
||
"type": "number",
|
||
"description": "Coverage per box (sqft)"
|
||
},
|
||
"is_favorited": {
|
||
"type": "boolean",
|
||
"description": "当前用户是否已收藏。未登录时始终为 false"
|
||
},
|
||
"spec_count": {
|
||
"type": "integer",
|
||
"description": "该花色的规格数量（同品牌同花色的SKU数，含自身）。>1 表示有多种尺寸可选"
|
||
},
|
||
"is_official_price": {
|
||
"type": "boolean",
|
||
"description": "是否为官方定价。true=品牌官网标价，false=市场估价或未找到"
|
||
}
|
||
}
|
||
},
|
||
"ProductListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"products": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/ProductItem"
|
||
},
|
||
"description": "产品列表"
|
||
},
|
||
"total": {
|
||
"type": "integer",
|
||
"description": "总数"
|
||
},
|
||
"page": {
|
||
"type": "integer",
|
||
"description": "当前页码"
|
||
},
|
||
"limit": {
|
||
"type": "integer",
|
||
"description": "每页数量"
|
||
},
|
||
"total_pages": {
|
||
"type": "integer",
|
||
"description": "总页数"
|
||
},
|
||
"filter_options": {
|
||
"type": "object",
|
||
"properties": {
|
||
"categories": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "所有分类"
|
||
},
|
||
"series_names": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "所有系列"
|
||
},
|
||
"brands": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/BrandInfo"
|
||
},
|
||
"description": "所有品牌（含logo、款式数、类型数）"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"RecommendResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"source": {
|
||
"": "#/components/schemas/ProductDetail",
|
||
"description": "源产品信息"
|
||
},
|
||
"products": {
|
||
"type": "array",
|
||
"items": {
|
||
"": "#/components/schemas/ProductItem"
|
||
},
|
||
"description": "推荐产品列表"
|
||
},
|
||
"scores": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "匹配度（如 90%）"
|
||
},
|
||
"total": {
|
||
"type": "integer",
|
||
"description": "推荐总数"
|
||
}
|
||
}
|
||
},
|
||
"ProductDetail": {
|
||
"type": "object",
|
||
"properties": {
|
||
"brand": {
|
||
"type": "string"
|
||
},
|
||
"group_name": {
|
||
"type": "string"
|
||
},
|
||
"sku": {
|
||
"type": "string"
|
||
},
|
||
"series_name": {
|
||
"type": "string"
|
||
},
|
||
"style_name": {
|
||
"type": "string"
|
||
},
|
||
"category": {
|
||
"type": "string"
|
||
},
|
||
"material": {
|
||
"type": "string"
|
||
},
|
||
"color_tone": {
|
||
"type": "string"
|
||
},
|
||
"finish": {
|
||
"type": "string"
|
||
},
|
||
"price_per_sqft": {
|
||
"type": "number"
|
||
},
|
||
"price_tier": {
|
||
"type": "string"
|
||
},
|
||
"price_source": {
|
||
"type": "string"
|
||
},
|
||
"main_image_url": {
|
||
"type": "string"
|
||
},
|
||
"room_image_url": {
|
||
"type": "string"
|
||
},
|
||
"source_url": {
|
||
"type": "string"
|
||
},
|
||
"description": {
|
||
"type": "string"
|
||
},
|
||
"status": {
|
||
"type": "string"
|
||
},
|
||
"coverage_sqft_per_box": {
|
||
"type": "number",
|
||
"description": "Coverage per box (sqft)"
|
||
},
|
||
"wood_species": {
|
||
"type": "string",
|
||
"description": "Wood species"
|
||
},
|
||
"size_label": {
|
||
"type": "string",
|
||
"description": "Size label (e.g. 6 x 48 in)"
|
||
},
|
||
"width_in": {
|
||
"type": "number",
|
||
"description": "Width (inches)"
|
||
},
|
||
"length_in": {
|
||
"type": "number",
|
||
"description": "Length (inches)"
|
||
},
|
||
"variants": {
|
||
"type": "array",
|
||
"description": "同款不同尺寸的完整产品数据。仅当同品牌同花色的其他SKU存在时返回（旧格式，建议使用 specs）",
|
||
"items": {
|
||
"$ref": "#/components/schemas/ProductVariant"
|
||
}
|
||
},
|
||
"specs": {
|
||
"type": "array",
|
||
"description": "规格列表：该花色的所有尺寸+价格。包含主产品自身（至少1条）。多规格时前端可展示尺寸选择器",
|
||
"items": {
|
||
"$ref": "#/components/schemas/ProductSpec"
|
||
}
|
||
},
|
||
"is_favorited": {
|
||
"type": "boolean",
|
||
"description": "当前用户是否已收藏。未登录时始终为 false"
|
||
},
|
||
"is_official_price": {
|
||
"type": "boolean",
|
||
"description": "是否为官方定价。true=品牌官网标价，false=市场估价或未找到"
|
||
}
|
||
}
|
||
},
|
||
"ProductSpec": {
|
||
"type": "object",
|
||
"description": "单个规格（尺寸+价格）",
|
||
"properties": {
|
||
"sku": {
|
||
"type": "string",
|
||
"description": "该规格对应的SKU"
|
||
},
|
||
"size_label": {
|
||
"type": "string",
|
||
"description": "尺寸标签，如 6 x 48 in"
|
||
},
|
||
"width_in": {
|
||
"type": "number",
|
||
"description": "宽度（英寸）"
|
||
},
|
||
"length_in": {
|
||
"type": "number",
|
||
"description": "长度（英寸）"
|
||
},
|
||
"price_per_sqft": {
|
||
"type": "number",
|
||
"description": "每平方英尺价格（美元）"
|
||
},
|
||
"price_tier": {
|
||
"type": "string",
|
||
"description": "价格段位"
|
||
},
|
||
"coverage_sqft_per_box": {
|
||
"type": "number",
|
||
"description": "每箱覆盖面积（平方英尺）"
|
||
},
|
||
"main_image_url": {
|
||
"type": "string",
|
||
"description": "该规格产品图片URL"
|
||
}
|
||
}
|
||
},
|
||
"ProductVariant": {
|
||
"type": "object",
|
||
"description": "Product variant (same style, different size/price)",
|
||
"properties": {
|
||
"sku": {
|
||
"type": "string"
|
||
},
|
||
"size_label": {
|
||
"type": "string"
|
||
},
|
||
"width_in": {
|
||
"type": "number"
|
||
},
|
||
"length_in": {
|
||
"type": "number"
|
||
},
|
||
"price_per_sqft": {
|
||
"type": "number"
|
||
},
|
||
"price_tier": {
|
||
"type": "string"
|
||
},
|
||
"series_name": {
|
||
"type": "string"
|
||
},
|
||
"main_image_url": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"FilterHierarchy": {
|
||
"type": "object",
|
||
"properties": {
|
||
"filters": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/FilterGroup"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"FilterGroup": {
|
||
"type": "object",
|
||
"properties": {
|
||
"key": {
|
||
"type": "string",
|
||
"description": "Filter parameter name (used with /products)"
|
||
},
|
||
"label": {
|
||
"type": "string",
|
||
"description": "Display label"
|
||
},
|
||
"options": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Available values (flat structure)"
|
||
},
|
||
"groups": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/FilterGroup"
|
||
},
|
||
"description": "Sub-groups (hierarchical, e.g. Material > Wood/Porcelain/Vinyl)"
|
||
}
|
||
}
|
||
},
|
||
"BrandInfo": {
|
||
"type": "object",
|
||
"description": "品牌信息（含统计和logo）",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"description": "品牌名称"
|
||
},
|
||
"logo_url": {
|
||
"type": "string",
|
||
"description": "品牌 logo 图片 URL（存在 static/brand_logos/ 下），可能为空"
|
||
},
|
||
"style_count": {
|
||
"type": "integer",
|
||
"description": "该品牌下的款式数量（distinct style_name）"
|
||
},
|
||
"collection_count": {
|
||
"type": "integer",
|
||
"description": "该品牌下的产品合集数量（distinct category）"
|
||
}
|
||
},
|
||
"example": {
|
||
"name": "Shaw Floors",
|
||
"logo_url": "/static/brand_logos/shaw_floors.webp",
|
||
"style_count": 1797,
|
||
"collection_count": 4
|
||
}
|
||
},
|
||
"Article": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "integer"
|
||
},
|
||
"title": {
|
||
"type": "string"
|
||
},
|
||
"summary": {
|
||
"type": "string"
|
||
},
|
||
"content": {
|
||
"type": "string",
|
||
"description": "Full article text"
|
||
},
|
||
"cover_url": {
|
||
"type": "string",
|
||
"description": "Cover image URL"
|
||
},
|
||
"image_urls": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Article images"
|
||
},
|
||
"created_at": {
|
||
"type": "string",
|
||
"format": "date-time"
|
||
}
|
||
}
|
||
},
|
||
"ArticleListResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"articles": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/Article"
|
||
}
|
||
},
|
||
"total": {
|
||
"type": "integer"
|
||
},
|
||
"page": {
|
||
"type": "integer"
|
||
},
|
||
"limit": {
|
||
"type": "integer"
|
||
},
|
||
"total_pages": {
|
||
"type": "integer"
|
||
}
|
||
}
|
||
},
|
||
"ArticleRecommendResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"articles": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/Article"
|
||
}
|
||
},
|
||
"total": {
|
||
"type": "integer"
|
||
}
|
||
}
|
||
},
|
||
"FloorStyleOption": {
|
||
"type": "object",
|
||
"description": "Floor style loaded from product database. Each entry = one unique style (dedup by brand+style_name). Variants list different sizes.",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Product SKU（用于 floor_id 参数）"
|
||
},
|
||
"sku": {
|
||
"type": "string",
|
||
"description": "Product SKU（同 id，兼容旧版）"
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Style name (花色名称)"
|
||
},
|
||
"material": {
|
||
"type": "string",
|
||
"description": "Material (材质，如 Oak/Porcelain/Luxury Vinyl)"
|
||
},
|
||
"color_tone": {
|
||
"type": "string",
|
||
"description": "Color tone (色调，如 Light Gray/Natural Oak/Dark Brown)"
|
||
},
|
||
"finish": {
|
||
"type": "string",
|
||
"description": "Finish (表面处理，如 Matte/Gloss/Textured)"
|
||
},
|
||
"size_label": {
|
||
"type": "string",
|
||
"description": "Size label, e.g. 6 x 48 in. 多尺寸时为首个尺寸"
|
||
},
|
||
"width_in": {
|
||
"type": "number",
|
||
"description": "Width in inches. Used in AI prompt for physical scale"
|
||
},
|
||
"length_in": {
|
||
"type": "number",
|
||
"description": "Length in inches. Used in AI prompt for physical scale"
|
||
},
|
||
"image_url": {
|
||
"type": "string",
|
||
"description": "Preview image URL"
|
||
},
|
||
"category": {
|
||
"type": "string",
|
||
"description": "Product category (Solid Hardwood / Engineered Hardwood / Tile/Stone / SPC-LVP / Laminate)"
|
||
},
|
||
"description": {
|
||
"type": "string",
|
||
"description": "Product description. Used in AI prompt for richer visual detail"
|
||
},
|
||
"variants": {
|
||
"type": "array",
|
||
"description": "Size variants of the same style (same brand+style_name, different SKU/size). Empty array if only one size.",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"sku": { "type": "string", "description": "Variant SKU" },
|
||
"size_label": { "type": "string", "description": "Variant size label" },
|
||
"width_in": { "type": "number" },
|
||
"length_in": { "type": "number" }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"FloorOptionsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"wood_floors": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/FloorStyleOption"
|
||
},
|
||
"description": "Wood products (Oak/Ash/Hickory/Maple etc.) — classified by material field"
|
||
},
|
||
"tile_floors": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/FloorStyleOption"
|
||
},
|
||
"description": "Tile/Stone (Porcelain/Stone Look/Glass) + Laminate products"
|
||
},
|
||
"vinyl_floors": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/FloorStyleOption"
|
||
},
|
||
"description": "Vinyl products (Luxury Vinyl/Rigid Core)"
|
||
},
|
||
"wood_patterns": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/PatternOption"
|
||
}
|
||
},
|
||
"tile_patterns": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/PatternOption"
|
||
}
|
||
},
|
||
"rooms": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/RoomOption"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"PatternOption": {
|
||
"type": "object",
|
||
"description": "铺设方式选项。code 1-4 为木地板，5-9 为瓷砖",
|
||
"properties": {
|
||
"code": {
|
||
"type": "integer",
|
||
"description": "铺设方式编码（1-9），见文档顶部数字编码对照表"
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "铺设方式名称"
|
||
},
|
||
"pattern": {
|
||
"type": "string",
|
||
"description": "AI提示词用的铺设描述"
|
||
},
|
||
"category": {
|
||
"type": "string",
|
||
"description": "所属类型：wood 或 tile"
|
||
}
|
||
},
|
||
"example": {
|
||
"code": 3,
|
||
"name": "Herringbone",
|
||
"pattern": "herringbone/zigzag pattern with rectangular planks arranged in a broken V shape",
|
||
"category": "wood"
|
||
}
|
||
},
|
||
"RoomOption": {
|
||
"type": "object",
|
||
"description": "房间类型选项。code 0 为自动检测",
|
||
"properties": {
|
||
"code": {
|
||
"type": "integer",
|
||
"description": "房间编码（0-7），见文档顶部数字编码对照表"
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "房间名称"
|
||
}
|
||
},
|
||
"example": {
|
||
"code": 1,
|
||
"name": "Living Room"
|
||
}
|
||
},
|
||
"CalcInput": {
|
||
"type": "object",
|
||
"required": [
|
||
"floor_type",
|
||
"rooms",
|
||
"piece_length",
|
||
"piece_width"
|
||
],
|
||
"properties": {
|
||
"floor_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"wood",
|
||
"tile"
|
||
],
|
||
"description": "地板类型"
|
||
},
|
||
"rooms": {
|
||
"type": "array",
|
||
"description": "房间列表，至少一个",
|
||
"items": {
|
||
"type": "object",
|
||
"required": [
|
||
"length",
|
||
"width"
|
||
],
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"description": "房间名称，如 Living Room"
|
||
},
|
||
"length": {
|
||
"type": "number",
|
||
"description": "长（米），如 5"
|
||
},
|
||
"width": {
|
||
"type": "number",
|
||
"description": "宽（米），如 4"
|
||
},
|
||
"deductions": {
|
||
"type": "array",
|
||
"description": "扣减区域，如柜子、壁炉等不铺地板的区域",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"description": "区域名称，如 Fireplace / Kitchen Island"
|
||
},
|
||
"shape": {
|
||
"type": "string",
|
||
"enum": [
|
||
"rectangle",
|
||
"circle",
|
||
"custom"
|
||
],
|
||
"description": "形状类型：rectangle=矩形(填length+width) / circle=圆形(填radius直径) / custom=自定义(填area)"
|
||
},
|
||
"length": {
|
||
"type": "number",
|
||
"description": "长（米），仅 rectangle 矩形时填写"
|
||
},
|
||
"width": {
|
||
"type": "number",
|
||
"description": "宽（米），仅 rectangle 矩形时填写"
|
||
},
|
||
"radius": {
|
||
"type": "number",
|
||
"description": "半径（米），仅 circle 圆形时填写，直径=radius*2"
|
||
},
|
||
"area": {
|
||
"type": "number",
|
||
"description": "面积（平方米），仅 custom 自定义时填写"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"pattern_index": {
|
||
"type": "integer",
|
||
"default": 0,
|
||
"description": "铺设方式索引（0-5）"
|
||
},
|
||
"piece_length": {
|
||
"type": "number",
|
||
"description": "单片长度（米），必填，如 1.2"
|
||
},
|
||
"piece_width": {
|
||
"type": "number",
|
||
"description": "单片宽度（米），必填，如 0.19"
|
||
},
|
||
"pieces_per_box": {
|
||
"type": "integer",
|
||
"description": "每箱片数，选填，如 8"
|
||
},
|
||
"price_per_sqm": {
|
||
"type": "number",
|
||
"description": "每平方米单价，选填，如 45"
|
||
},
|
||
"joint_width": {
|
||
"type": "number",
|
||
"description": "缝宽（米），瓷砖用，如 0.002"
|
||
}
|
||
},
|
||
"example": {
|
||
"floor_type": "wood",
|
||
"rooms": [
|
||
{
|
||
"name": "Living Room",
|
||
"length": 5,
|
||
"width": 4,
|
||
"deductions": [
|
||
{
|
||
"name": "Fireplace",
|
||
"shape": "rectangle",
|
||
"length": 1.5,
|
||
"width": 0.8
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"name": "Hallway",
|
||
"length": 3,
|
||
"width": 1.2,
|
||
"deductions": []
|
||
}
|
||
],
|
||
"pattern_index": 0,
|
||
"piece_length": 1.2,
|
||
"piece_width": 0.19,
|
||
"pieces_per_box": 8,
|
||
"price_per_sqm": 45
|
||
}
|
||
},
|
||
"CalcRoomInput": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"description": "房间名称"
|
||
},
|
||
"length": {
|
||
"type": "number",
|
||
"description": "长（米）"
|
||
},
|
||
"width": {
|
||
"type": "number",
|
||
"description": "宽（米）"
|
||
},
|
||
"deductions": {
|
||
"type": "array",
|
||
"items": {
|
||
"": "#/components/schemas/CalcDeduction"
|
||
},
|
||
"description": "扣减区域（柜子/壁炉等不铺地板的区域）"
|
||
}
|
||
}
|
||
},
|
||
"CalcDeduction": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string"
|
||
},
|
||
"shape": {
|
||
"type": "string",
|
||
"enum": [
|
||
"rectangle",
|
||
"circle",
|
||
"custom"
|
||
],
|
||
"description": "形状"
|
||
},
|
||
"length": {
|
||
"type": "number",
|
||
"description": "长（rectangle时用）"
|
||
},
|
||
"width": {
|
||
"type": "number",
|
||
"description": "宽（rectangle时用）"
|
||
},
|
||
"radius": {
|
||
"type": "number",
|
||
"description": "半径（circle时用）"
|
||
},
|
||
"area": {
|
||
"type": "number",
|
||
"description": "自定义面积（custom时用）"
|
||
}
|
||
}
|
||
},
|
||
"CalcResult": {
|
||
"type": "object",
|
||
"properties": {
|
||
"floor_type": {
|
||
"type": "string"
|
||
},
|
||
"rooms": {
|
||
"type": "array",
|
||
"items": {
|
||
"": "#/components/schemas/CalcRoomResult"
|
||
}
|
||
},
|
||
"total_room_area": {
|
||
"type": "number",
|
||
"description": "房间总面积"
|
||
},
|
||
"total_deduct": {
|
||
"type": "number",
|
||
"description": "总扣减面积"
|
||
},
|
||
"total_net_area": {
|
||
"type": "number",
|
||
"description": "总净面积（需铺地板）"
|
||
},
|
||
"waste_rate": {
|
||
"type": "number",
|
||
"description": "损耗率（%）"
|
||
},
|
||
"waste_area": {
|
||
"type": "number",
|
||
"description": "损耗面积"
|
||
},
|
||
"total_area": {
|
||
"type": "number",
|
||
"description": "含损耗总面积"
|
||
},
|
||
"pieces_needed": {
|
||
"type": "integer",
|
||
"description": "需要片数"
|
||
},
|
||
"boxes_needed": {
|
||
"type": "number",
|
||
"description": "需要箱数（仅传入pieces_per_box时返回）"
|
||
},
|
||
"joint_width": {
|
||
"type": "number"
|
||
},
|
||
"grout_kg": {
|
||
"type": "number",
|
||
"description": "填缝剂重量kg（仅瓷砖模式返回）"
|
||
},
|
||
"grout_bags": {
|
||
"type": "integer",
|
||
"description": "填缝剂袋数（仅瓷砖模式返回）"
|
||
},
|
||
"price_per_sqm": {
|
||
"type": "number"
|
||
},
|
||
"total_price": {
|
||
"type": "number",
|
||
"description": "总价（仅传入price_per_sqm时返回）"
|
||
},
|
||
"pattern_name": {
|
||
"type": "string"
|
||
},
|
||
"piece_length": {
|
||
"type": "number"
|
||
},
|
||
"piece_width": {
|
||
"type": "number"
|
||
}
|
||
}
|
||
},
|
||
"CalcRoomResult": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string"
|
||
},
|
||
"length": {
|
||
"type": "number"
|
||
},
|
||
"width": {
|
||
"type": "number"
|
||
},
|
||
"area": {
|
||
"type": "number"
|
||
},
|
||
"deductions": {
|
||
"type": "array",
|
||
"items": {
|
||
"": "#/components/schemas/CalcDeduction"
|
||
}
|
||
},
|
||
"deduction_total": {
|
||
"type": "number"
|
||
},
|
||
"net_area": {
|
||
"type": "number"
|
||
}
|
||
}
|
||
},
|
||
"FrequentBrand": {
|
||
"type": "object",
|
||
"description": "用户常用品牌",
|
||
"properties": {
|
||
"brand": {
|
||
"type": "string",
|
||
"description": "品牌名称"
|
||
},
|
||
"view_count": {
|
||
"type": "integer",
|
||
"description": "浏览次数"
|
||
},
|
||
"fav_count": {
|
||
"type": "integer",
|
||
"description": "收藏次数"
|
||
},
|
||
"logo_url": {
|
||
"type": "string",
|
||
"description": "品牌logo URL"
|
||
},
|
||
"style_count": {
|
||
"type": "integer",
|
||
"description": "该品牌款式总数"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"paths": {
|
||
"/auth/register": {
|
||
"post": {
|
||
"tags": [
|
||
"认证"
|
||
],
|
||
"summary": "用户注册",
|
||
"description": "使用用户名和密码注册新账号，返回 JWT token 和用户信息",
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"required": [
|
||
"username",
|
||
"password"
|
||
],
|
||
"properties": {
|
||
"username": {
|
||
"type": "string",
|
||
"description": "用户名"
|
||
},
|
||
"password": {
|
||
"type": "string",
|
||
"description": "密码"
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "显示名称（选填）"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "注册成功",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AuthResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数错误（用户名或密码为空/用户名已存在）"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/auth/login": {
|
||
"post": {
|
||
"tags": [
|
||
"认证"
|
||
],
|
||
"summary": "用户登录",
|
||
"description": "用户名+密码登录，返回 JWT token 和用户信息",
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"required": [
|
||
"username",
|
||
"password"
|
||
],
|
||
"properties": {
|
||
"username": {
|
||
"type": "string",
|
||
"description": "用户名"
|
||
},
|
||
"password": {
|
||
"type": "string",
|
||
"description": "密码"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "登录成功",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AuthResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "用户名或密码错误"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/user/me": {
|
||
"get": {
|
||
"tags": [
|
||
"用户"
|
||
],
|
||
"summary": "获取个人信息",
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "用户信息",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/User"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未登录或token过期"
|
||
}
|
||
}
|
||
},
|
||
"put": {
|
||
"tags": [
|
||
"用户"
|
||
],
|
||
"summary": "更新个人信息",
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"description": "显示名称"
|
||
},
|
||
"avatar_url": {
|
||
"type": "string",
|
||
"description": "头像URL"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "更新成功",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/User"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/user/favorites": {
|
||
"get": {
|
||
"tags": [
|
||
"收藏"
|
||
],
|
||
"summary": "获取收藏列表",
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "收藏列表",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"favorites": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/Favorite"
|
||
}
|
||
},
|
||
"total": {
|
||
"type": "integer"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"tags": [
|
||
"收藏"
|
||
],
|
||
"summary": "添加收藏",
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"responses": {
|
||
"201": {
|
||
"description": "收藏成功"
|
||
}
|
||
},
|
||
"description": "传入产品SKU，后端自动查库补全产品信息",
|
||
"parameters": [
|
||
{
|
||
"name": "sku",
|
||
"in": "query",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "产品SKU编码"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"/user/favorites/{sku}": {
|
||
"delete": {
|
||
"tags": [
|
||
"收藏"
|
||
],
|
||
"summary": "取消收藏",
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "sku",
|
||
"in": "path",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "产品SKU编码"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "取消成功"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/user/projects": {
|
||
"get": {
|
||
"tags": [
|
||
"项目"
|
||
],
|
||
"summary": "获取项目列表",
|
||
"description": "获取当前用户的所有AI换地板项目记录",
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "项目列表",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"projects": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/Project"
|
||
}
|
||
},
|
||
"total": {
|
||
"type": "integer"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"tags": [
|
||
"项目"
|
||
],
|
||
"summary": "创建项目",
|
||
"description": "保存一次AI换地板记录",
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"description": "项目名称，默认 Untitled",
|
||
"default": "Untitled"
|
||
},
|
||
"original_image_url": {
|
||
"type": "string",
|
||
"description": "换地板前原图URL"
|
||
},
|
||
"generated_image_url": {
|
||
"type": "string",
|
||
"description": "AI生成效果图URL"
|
||
},
|
||
"floor_style": {
|
||
"type": "string",
|
||
"description": "使用的款式"
|
||
},
|
||
"pattern": {
|
||
"type": "string",
|
||
"description": "铺设方式"
|
||
},
|
||
"room_type": {
|
||
"type": "string",
|
||
"description": "房间类型"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "创建成功",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/Project"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/user/projects/{id}": {
|
||
"get": {
|
||
"tags": [
|
||
"项目"
|
||
],
|
||
"summary": "获取单个项目",
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "id",
|
||
"in": "path",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "项目UUID"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "项目详情",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/Project"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "项目不存在"
|
||
}
|
||
}
|
||
},
|
||
"put": {
|
||
"tags": [
|
||
"项目"
|
||
],
|
||
"summary": "重命名项目",
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "id",
|
||
"in": "path",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "项目UUID"
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"required": [
|
||
"name"
|
||
],
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"description": "新名称"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "更新成功",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/Project"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"tags": [
|
||
"项目"
|
||
],
|
||
"summary": "删除项目",
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"name": "id",
|
||
"in": "path",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "项目UUID"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "删除成功"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/products": {
|
||
"get": {
|
||
"tags": [
|
||
"产品"
|
||
],
|
||
"summary": "产品列表（多维度筛选+搜索+分页）",
|
||
"parameters": [
|
||
{
|
||
"name": "category",
|
||
"in": "query",
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "类目：Hardwood / Engineered Wood / Laminate / SPC/LVP / Wood-Look Tile"
|
||
},
|
||
{
|
||
"name": "material",
|
||
"in": "query",
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "材质：Oak / Porcelain / Luxury Vinyl / Maple / Hickory 等"
|
||
},
|
||
{
|
||
"name": "color_tone",
|
||
"in": "query",
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "色调：Light Gray / Natural Oak / Dark Brown / Taupe 等"
|
||
},
|
||
{
|
||
"name": "finish",
|
||
"in": "query",
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "表面处理：Matte / Gloss / Textured / Wire-Brushed 等"
|
||
},
|
||
{
|
||
"name": "wood_species",
|
||
"in": "query",
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "木种：Oak / Maple / Hickory / Walnut / Birch 等"
|
||
},
|
||
{
|
||
"name": "brand",
|
||
"in": "query",
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "品牌筛选"
|
||
},
|
||
{
|
||
"name": "series_name",
|
||
"in": "query",
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "系列名称筛选"
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "模糊搜索（匹配款式名称/编号/品牌）"
|
||
},
|
||
{
|
||
"name": "page",
|
||
"in": "query",
|
||
"schema": {
|
||
"type": "integer",
|
||
"default": 1
|
||
},
|
||
"description": "页码"
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"schema": {
|
||
"type": "integer",
|
||
"default": 20
|
||
},
|
||
"description": "每页数量"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "产品列表",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ProductListResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"description": "所有筛选参数可任意组合。\n\n前端层层递进实现方式：用户每选择一个筛选项，将已选参数传给本接口，根据返回结果中的 filter_options 动态收窄其他筛选项的可选范围。"
|
||
}
|
||
},
|
||
"/product-options": {
|
||
"get": {
|
||
"tags": [
|
||
"产品"
|
||
],
|
||
"summary": "筛选选项（扁平结构）",
|
||
"description": "返回分类/系列/品牌列表。品牌包含名称、logo、款式数、类型数。",
|
||
"responses": {
|
||
"200": {
|
||
"description": "筛选项",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"code": {
|
||
"type": "integer",
|
||
"example": 200
|
||
},
|
||
"data": {
|
||
"type": "object",
|
||
"properties": {
|
||
"categories": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "分类列表"
|
||
},
|
||
"series_names": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "系列名称列表"
|
||
},
|
||
"brands": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/BrandInfo"
|
||
},
|
||
"description": "品牌列表（含统计和logo）"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"example": {
|
||
"code": 200,
|
||
"data": {
|
||
"categories": [
|
||
"Hardwood",
|
||
"Laminate",
|
||
"SPC/LVP",
|
||
"Engineered Wood",
|
||
"Wood-Look Tile"
|
||
],
|
||
"series_names": [
|
||
"American Retreat",
|
||
"Nature's Splendor",
|
||
"Timeless Design"
|
||
],
|
||
"brands": [
|
||
{
|
||
"name": "Shaw Floors",
|
||
"logo_url": "/static/brand_logos/shaw_floors.webp",
|
||
"style_count": 1797,
|
||
"collection_count": 4
|
||
},
|
||
{
|
||
"name": "Bruce",
|
||
"logo_url": "/static/brand_logos/bruce.jpg",
|
||
"style_count": 224,
|
||
"collection_count": 4
|
||
},
|
||
{
|
||
"name": "Karndean",
|
||
"logo_url": "/static/brand_logos/karndean.jpg",
|
||
"style_count": 251,
|
||
"collection_count": 1
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/recommend": {
|
||
"post": {
|
||
"tags": [
|
||
"推荐"
|
||
],
|
||
"summary": "智能推荐",
|
||
"description": "输入产品SKU，返回跨品牌相似地板推荐",
|
||
"responses": {
|
||
"200": {
|
||
"description": "推荐结果",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/RecommendResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"parameters": [
|
||
{
|
||
"name": "sku",
|
||
"in": "query",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "产品SKU编码",
|
||
"example": "CB218LG"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"/calculator/calc": {
|
||
"post": {
|
||
"tags": [
|
||
"计算器"
|
||
],
|
||
"summary": "地板面积计算",
|
||
"description": "支持多房间、扣减区域、单片尺寸、铺设方式损耗、每箱片数、缝宽、单价。报告由前端根据返回结果自行生成。",
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CalcInput"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "计算结果",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"": "#/components/schemas/CalcResult"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数错误"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/floor/options": {
|
||
"get": {
|
||
"tags": [
|
||
"地板更换"
|
||
],
|
||
"summary": "获取地板样式选项（从产品库动态加载，含尺寸变体）",
|
||
"description": "从产品数据库动态加载地板样式选项。每个样式对应一个真实产品SKU，含 width_in/length_in/description/variants 等字段。\n\n材质分类（按 material 字段自动归类）：\n- wood_floors：Oak/Ash/Hickory/Maple 等木材\n- tile_floors：Porcelain/Stone Look/Glass + Laminate\n- vinyl_floors：Luxury Vinyl/Rigid Core\n\n前端应使用 variants 渲染尺寸选择面板。",
|
||
"responses": {
|
||
"200": {
|
||
"description": "成功",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"code": {
|
||
"type": "integer",
|
||
"example": 200
|
||
},
|
||
"data": {
|
||
"$ref": "#/components/schemas/FloorOptionsResponse"
|
||
}
|
||
}
|
||
},
|
||
"example": {
|
||
"code": 200,
|
||
"data": {
|
||
"wood_floors": [],
|
||
"tile_floors": [],
|
||
"vinyl_floors": [],
|
||
"wood_floors": [
|
||
{
|
||
"id": "CB218LG",
|
||
"sku": "CB218LG",
|
||
"name": "Cherry",
|
||
"material": "Oak",
|
||
"color_tone": "Natural Oak",
|
||
"finish": "Matte",
|
||
"size_label": "2.25 x 84 in",
|
||
"width_in": 2.25,
|
||
"length_in": 84.0,
|
||
"image_url": "https://...",
|
||
"category": "Solid Hardwood",
|
||
"description": "Natural cherry oak with subtle grain",
|
||
"variants": [
|
||
{ "sku": "CB4218", "size_label": "4 x 84 in", "width_in": 4.0, "length_in": 84.0 },
|
||
{ "sku": "CB5218", "size_label": "5 x 84 in", "width_in": 5.0, "length_in": 84.0 }
|
||
]
|
||
}
|
||
],
|
||
"tile_floors": [],
|
||
"vinyl_floors": [],
|
||
"wood_patterns": [
|
||
{
|
||
"code": 1,
|
||
"name": "直铺（工字拼）Straight Lay",
|
||
"pattern": "straight/parallel planks running from front to back with staggered joints",
|
||
"category": "wood"
|
||
},
|
||
{
|
||
"code": 2,
|
||
"name": "横铺 Horizontal Lay",
|
||
"pattern": "horizontal planks running side to side across the width of the room",
|
||
"category": "wood"
|
||
},
|
||
{
|
||
"code": 3,
|
||
"name": "人字拼 Herringbone",
|
||
"pattern": "herringbone/zigzag pattern with rectangular planks arranged in a broken V shape",
|
||
"category": "wood"
|
||
},
|
||
{
|
||
"code": 4,
|
||
"name": "鱼骨拼 Chevron",
|
||
"pattern": "chevron pattern with planks cut at an angle forming a continuous V shape",
|
||
"category": "wood"
|
||
}
|
||
],
|
||
"tile_patterns": [
|
||
{
|
||
"code": 5,
|
||
"name": "直铺（网格对缝）Straight Grid",
|
||
"pattern": "straight grid layout with tiles perfectly aligned in rows and columns, clean orthogonal grout lines",
|
||
"category": "tile"
|
||
},
|
||
{
|
||
"code": 6,
|
||
"name": "工字铺（1/2错缝）Running Bond",
|
||
"pattern": "running bond/brick pattern with each row offset by 50%, staggered brickwork appearance",
|
||
"category": "tile"
|
||
},
|
||
{
|
||
"code": 7,
|
||
"name": "三七错铺 1/3 Offset",
|
||
"pattern": "tiles offset by 1/3 of their length in each row, subtle stepped pattern",
|
||
"category": "tile"
|
||
},
|
||
{
|
||
"code": 8,
|
||
"name": "六边形 Hexagonal",
|
||
"pattern": "hexagonal/honeycomb tiles fitted together in a seamless honeycomb mesh",
|
||
"category": "tile"
|
||
},
|
||
{
|
||
"code": 9,
|
||
"name": "斜铺（45度对角）Diagonal",
|
||
"pattern": "tiles laid at a 45-degree diagonal angle to the walls, diamond orientation",
|
||
"category": "tile"
|
||
}
|
||
],
|
||
"rooms": [
|
||
{ "code": 0, "name": "自动识别" },
|
||
{ "code": 1, "name": "客厅" },
|
||
{ "code": 2, "name": "卧室" },
|
||
{ "code": 3, "name": "厨房" },
|
||
{ "code": 4, "name": "餐厅" },
|
||
{ "code": 5, "name": "浴室" },
|
||
{ "code": 6, "name": "书房" },
|
||
{ "code": 7, "name": "走廊" }
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/floor/generate": {
|
||
"post": {
|
||
"tags": [
|
||
"地板更换"
|
||
],
|
||
"summary": "AI换地板（使用真实产品数据，含尺寸/变体）",
|
||
"description": "上传房间照片 + 地板选项，加入 Redis 异步队列，返回 job_id。用 GET /floor/status?job_id=xxx 查询进度。\n\nfloor_id 支持有尺寸变体的产品——选择变体对应 SKU 即可，AI 会根据 width_in/length_in 生成对应物理尺寸的地板。",
|
||
"requestBody": {
|
||
"content": {
|
||
"multipart/form-data": {
|
||
"schema": {
|
||
"type": "object",
|
||
"required": [
|
||
"image",
|
||
"floor_id",
|
||
"pattern_code"
|
||
],
|
||
"properties": {
|
||
"image": {
|
||
"type": "string",
|
||
"format": "binary",
|
||
"description": "房间照片"
|
||
},
|
||
"floor_id": {
|
||
"type": "string",
|
||
"description": "产品SKU，从 /floor/options 获取（如 \"CB218LG\"），必须是真实产品SKU"
|
||
},
|
||
"pattern_code": {
|
||
"type": "integer",
|
||
"description": "铺设方式编码（1-9），见文档顶部数字编码对照表",
|
||
"example": 3
|
||
},
|
||
"room_code": {
|
||
"type": "integer",
|
||
"description": "房间类型编码（0-7），见文档顶部数字编码对照表。0 或省略表示自动检测",
|
||
"example": 1
|
||
},
|
||
"grout_lines": {
|
||
"type": "boolean",
|
||
"description": "Optional. Tile floors only. true adds realistic visible grout lines between tiles.",
|
||
"example": false
|
||
},
|
||
"white_baseboard": {
|
||
"type": "boolean",
|
||
"description": "Optional. true adds or refreshes a realistic white baseboard/skirting board along visible wall-floor edges.",
|
||
"example": false
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "成功返回 job_id",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"code": {
|
||
"type": "integer",
|
||
"example": 200
|
||
},
|
||
"data": {
|
||
"type": "object",
|
||
"properties": {
|
||
"job_id": {
|
||
"type": "string",
|
||
"description": "用于查询进度的 job_id"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"example": {
|
||
"code": 200,
|
||
"data": {
|
||
"job_id": "1750123456789000000"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"code": {
|
||
"type": "integer",
|
||
"example": 400
|
||
},
|
||
"error": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"example": {
|
||
"code": 400,
|
||
"error": "Invalid options"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/products/{sku}": {
|
||
"get": {
|
||
"tags": [
|
||
"Products"
|
||
],
|
||
"summary": "产品详情（含同花色多尺寸变体）",
|
||
"description": "返回产品完整信息。如果该产品有同品牌+同花色(style_name)的其他SKU（不同尺寸/价格），会自动聚合到 variants 数组中，形成父子关系展示。\n\n例如：查询 Matte White 3×6 in，variants 返回 4×16 / 12×24 / 24×24 等其他尺寸。",
|
||
"parameters": [
|
||
{
|
||
"name": "sku",
|
||
"in": "path",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "Product SKU code"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Product with variants",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ProductDetail"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "Product not found"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/filter-options": {
|
||
"get": {
|
||
"tags": [
|
||
"Products"
|
||
],
|
||
"summary": "分级筛选选项（层级结构）",
|
||
"description": "返回所有可用的筛选值，支持层级结构（Material 下分 Wood / Porcelain / Vinyl / Other 子组）。\n\n前端层层递进实现方式：\n1. 页面加载时调用本接口获取全部选项\n2. 用户选择某个筛选项后，将已选参数传给 /products 接口\n3. 根据 /products 返回的 filter_options 动态收窄其他筛选项的可选范围",
|
||
"responses": {
|
||
"200": {
|
||
"description": "Filter hierarchy",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/FilterHierarchy"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/articles": {
|
||
"get": {
|
||
"tags": [
|
||
"Knowledge"
|
||
],
|
||
"summary": "科普文章列表（分页）",
|
||
"parameters": [
|
||
{
|
||
"name": "page",
|
||
"in": "query",
|
||
"schema": {
|
||
"type": "integer",
|
||
"default": 1
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"schema": {
|
||
"type": "integer",
|
||
"default": 10
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Article list",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ArticleListResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/articles/{id}": {
|
||
"get": {
|
||
"tags": [
|
||
"Knowledge"
|
||
],
|
||
"summary": "文章详情",
|
||
"parameters": [
|
||
{
|
||
"name": "id",
|
||
"in": "path",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "integer"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Article detail",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/Article"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "Article not found"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/articles/recommend": {
|
||
"get": {
|
||
"tags": [
|
||
"Knowledge"
|
||
],
|
||
"summary": "随机推荐文章（默认6篇）",
|
||
"description": "每次随机返回指定数量的文章，默认6篇，最多20篇",
|
||
"parameters": [
|
||
{
|
||
"name": "count",
|
||
"in": "query",
|
||
"schema": {
|
||
"type": "integer",
|
||
"default": 6
|
||
},
|
||
"description": "Count (1-20)"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Recommended articles",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ArticleRecommendResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/user/avatar": {
|
||
"post": {
|
||
"tags": [
|
||
"用户"
|
||
],
|
||
"summary": "上传头像",
|
||
"description": "上传用户头像图片，自动替换旧头像。最大5MB。头像存储在 uploads/avatars/ 目录。",
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"multipart/form-data": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"image": {
|
||
"type": "string",
|
||
"format": "binary",
|
||
"description": "头像图片文件"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "上传成功，返回用户信息（含avatar_url）"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/floor/status": {
|
||
"get": {
|
||
"tags": [
|
||
"地板更换"
|
||
],
|
||
"summary": "查询生成进度（HTTP 轮询，含耗时统计）",
|
||
"description": "Redis 异步队列任务状态查询。status: pending | processing | done | error。\n\n返回 timings_ms 字段包含每步耗时：check/mask/inpaint/cleanup/total。elapsed_ms 为总运行时间。",
|
||
"parameters": [
|
||
{
|
||
"name": "job_id",
|
||
"in": "query",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"description": "floor-generate 返回的 job_id"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Job status with timing",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"code": { "type": "integer", "example": 200 },
|
||
"data": {
|
||
"type": "object",
|
||
"properties": {
|
||
"job_id": { "type": "string" },
|
||
"status": { "type": "string", "description": "pending | processing | done | error" },
|
||
"step": { "type": "string", "description": "check | mask | inpaint | done | error" },
|
||
"message": { "type": "string" },
|
||
"result": { "type": "string", "description": "Generated image path, e.g. /outputs/result_xxx.png" },
|
||
"error": { "type": "string" },
|
||
"elapsed_ms": { "type": "integer", "description": "Total elapsed milliseconds since job start" },
|
||
"timings_ms": {
|
||
"type": "object",
|
||
"description": "Per-step duration in milliseconds",
|
||
"properties": {
|
||
"check": { "type": "integer" },
|
||
"mask": { "type": "integer" },
|
||
"inpaint": { "type": "integer" },
|
||
"total": { "type": "integer" }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"example": {
|
||
"code": 200,
|
||
"data": {
|
||
"job_id": "1784530075874083600",
|
||
"status": "done",
|
||
"step": "done",
|
||
"message": "Done",
|
||
"result": "/outputs/result_1784530075874083600.png",
|
||
"elapsed_ms": 100340,
|
||
"timings_ms": { "check": 5148, "mask": 25971, "inpaint": 69218, "total": 100340 }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/upload": {
|
||
"post": {
|
||
"tags": [
|
||
"Upload"
|
||
],
|
||
"summary": "通用图片上传",
|
||
"description": "上传图片文件，返回访问URL。最大20MB，自动检测图片类型。存于 static/images/ 目录",
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"multipart/form-data": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"image": {
|
||
"type": "string",
|
||
"format": "binary",
|
||
"description": "图片文件"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "上传成功",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"code": {
|
||
"type": "integer",
|
||
"example": 200
|
||
},
|
||
"data": {
|
||
"type": "object",
|
||
"properties": {
|
||
"url": {
|
||
"type": "string",
|
||
"example": "/static/images/abc123.jpg"
|
||
},
|
||
"filename": {
|
||
"type": "string",
|
||
"example": "abc123.jpg"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/user/frequent-brands": {
|
||
"get": {
|
||
"tags": [
|
||
"Brand Tracking"
|
||
],
|
||
"summary": "获取常用品牌",
|
||
"description": "返回浏览≥3次或收藏≥2次的品牌。需登录。按权重排序",
|
||
"security": [
|
||
{
|
||
"BearerAuth": []
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "常用品牌列表",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"code": {
|
||
"type": "integer",
|
||
"example": 200
|
||
},
|
||
"data": {
|
||
"type": "object",
|
||
"properties": {
|
||
"brands": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/FrequentBrand"
|
||
}
|
||
},
|
||
"total": {
|
||
"type": "integer"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|