{
  "openapi": "3.0.3",
  "info": {
    "title": "优纯严选 · 开放数据 API | Youcun Select Open Data API",
    "version": "1.0.2",
    "summary": "中国家纺（床品 / 面料）源头在售存货的机器可读数据源，只读、无需鉴权。",
    "description": "面向 AI 采购助手、跨境买手与第三方工具的**只读**数据接口。\n\n**A machine-readable, read-only data source** for in-stock home-textile (bedding & fabric) supply from China, for AI purchasing agents, cross-border buyers and third-party tools.\n\n## 怎么读（Read order）\n1. `GET /api/open/v1` —— 索引：有哪些数据、怎么调、配额与许可\n2. `GET /api/open/v1/schema` —— 字段字典：每个字段的含义 / 类型 / 单位 / 枚举 / 空值约定\n3. `GET /api/open/v1/stocks` —— 存货列表（成品 + 面料）；`GET /api/open/v1/fabrics` —— 只看面料参数\n\n## 三条必须知道的约定（Three conventions you must not miss）\n- **空值**：任何字段为 `null` 表示**商家没填**，不是 0、也不是「没有此能力」。`true/false` 才是明确能力。\n- **价格**：`price` 是**单价**，`price_unit` 是计价单位（套 / 条 / 公斤 / 米），`currency` 标币种（默认 `CNY`，跨境报价**不要假定美元**）。最小起订金额 = `price × min_order`。\n- **筛选不静默**：参数名未被识别时不会被悄悄忽略，响应里的 `ignored_filters` 会列出来 —— 避免「以为筛过了，其实是全量」。\n\n## 隐私与立场（Privacy & stance）\n- 本接口**不提供任何商家联系方式**（手机 / 微信 / 邮箱 / 地址），也不含商家内部编号。\n- 商家可匿名发布 → `supplier.name` 为 `null`；商家可开启「详细参数仅对验证买家开放」→ 该条 `param_locked=true` 且部分面料参数不返回。\n- 平台**只撮合买卖双方，不做中间商、不囤货、不担保交易**。需要样品或报价请通过平台站内询盘。\n\n## 许可与引用（License）\n允许 AI 助手、搜索引擎与第三方工具读取、引用与转述本接口数据；**引用时请标注来源 ucunhome.com**。建议缓存不超过 1 小时。\n\n## 版本策略（Versioning）\n字段名在 `1.x` 内**只新增、不改名、不删除**。破坏性变更会升 `api_version` 主版本号。",
    "termsOfService": "https://ucunhome.com/rules.html",
    "contact": {
      "name": "优纯严选 · 接口文档（中英对照）",
      "url": "https://ucunhome.com/open-api.html"
    },
    "license": {
      "name": "可读可引用，引用请标注来源 ucunhome.com",
      "url": "https://ucunhome.com/api/open/v1"
    }
  },
  "externalDocs": {
    "description": "人读的接口文档：字段表、调用示例、常见问题（中英对照）",
    "url": "https://ucunhome.com/open-api.html"
  },
  "servers": [
    {
      "url": "https://ucunhome.com",
      "description": "生产环境（唯一对外环境）"
    }
  ],
  "tags": [
    {
      "name": "索引",
      "description": "AI 从这里开始读：数据范围、端点清单、配额、许可。"
    },
    {
      "name": "字段字典",
      "description": "字段的含义、类型、单位、枚举与空值约定 —— 与数据接口的字段一一对应。"
    },
    {
      "name": "数据",
      "description": "在售存货（成品 + 面料）。每条记录都是现货，售完即止。"
    },
    {
      "name": "站点",
      "description": "给 AI 爬虫的纯文本入口。"
    }
  ],
  "paths": {
    "/api/open/v1": {
      "get": {
        "tags": [
          "索引"
        ],
        "operationId": "getApiIndex",
        "summary": "接口索引（Call this first）",
        "description": "返回本接口的用途、端点清单与各自的可用参数、当前在售统计（成品 / 面料 / 商家数）、按 IP 的限流窗口、隐私口径、许可条款与调用顺序建议。\n\nAI 助手应**先读本端点**再决定调哪个数据端点。",
        "responses": {
          "200": {
            "description": "索引",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiIndex"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/open/v1/schema": {
      "get": {
        "tags": [
          "字段字典"
        ],
        "operationId": "getFieldSchema",
        "summary": "字段字典（Field dictionary）",
        "description": "返回平台字段的**自描述字典**：每个字段的中英文名、类型、单位、枚举与说明；空值 / 布尔 / 时间 / 图片 / 价格 / 联系方式的取值约定；以及从当前在售数据**实时统计出的真实取值**（`observed_values`）——它永远比猜测准，可直接当作筛选参数用。\n\n本端点告诉你「字段是什么意思」；`/openapi.json` 告诉你「接口怎么调」。两者互补。",
        "responses": {
          "200": {
            "description": "字段字典",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FieldSchema"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "可选。输出翻译后的枚举值（品类/材质/尺寸/计价单位/混批等，17语言字典），自由文本保持原文。不带此参数时行为不变（中文原文）。schema 端点则同时切换字段说明语言（en 已完整，其它语言字段说明回退英文）。",
            "schema": {
              "type": "string",
              "example": "en"
            }
          }
        ]
      }
    },
    "/api/open/v1/stocks": {
      "get": {
        "tags": [
          "数据"
        ],
        "operationId": "listStocks",
        "summary": "存货列表：成品 + 面料（In-stock goods）",
        "description": "返回全部在售存货（成品与面料混排）。用 `group=fabric|finished` 只取一侧。\n\n每条记录都是**现货**；`price` 是单价，配合 `price_unit` / `currency` 解读。",
        "parameters": [
          {
            "$ref": "#/components/parameters/group"
          },
          {
            "$ref": "#/components/parameters/kindAlias"
          },
          {
            "$ref": "#/components/parameters/category"
          },
          {
            "$ref": "#/components/parameters/subcategory"
          },
          {
            "$ref": "#/components/parameters/material"
          },
          {
            "$ref": "#/components/parameters/keyword"
          },
          {
            "$ref": "#/components/parameters/q"
          },
          {
            "$ref": "#/components/parameters/price_min"
          },
          {
            "$ref": "#/components/parameters/price_max"
          },
          {
            "$ref": "#/components/parameters/moq_max"
          },
          {
            "$ref": "#/components/parameters/export_ok"
          },
          {
            "$ref": "#/components/parameters/days"
          },
          {
            "$ref": "#/components/parameters/sort"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "可选。输出翻译后的枚举值（品类/材质/尺寸/计价单位/混批等，17语言字典），自由文本保持原文。不带此参数时行为不变（中文原文）。schema 端点则同时切换字段说明语言（en 已完整，其它语言字段说明回退英文）。",
            "schema": {
              "type": "string",
              "example": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "存货列表",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StockList"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/open/v1/fabrics": {
      "get": {
        "tags": [
          "数据"
        ],
        "operationId": "listFabrics",
        "summary": "面料参数列表（Fabric parameters）",
        "description": "与 `/stocks` 同构，但**只返回面料**（等价于固定 `group=fabric`），并额外支持面料专属筛选：印染方式、织法、可否寄样、可否定织、门幅区间。\n\n适合「找一块能做四件套、240 门幅、可寄样的全棉活性印染面料」这类参数化询盘。",
        "parameters": [
          {
            "$ref": "#/components/parameters/category"
          },
          {
            "$ref": "#/components/parameters/subcategory"
          },
          {
            "$ref": "#/components/parameters/material"
          },
          {
            "$ref": "#/components/parameters/keyword"
          },
          {
            "$ref": "#/components/parameters/q"
          },
          {
            "$ref": "#/components/parameters/print_type"
          },
          {
            "$ref": "#/components/parameters/weave"
          },
          {
            "$ref": "#/components/parameters/sample_ok"
          },
          {
            "$ref": "#/components/parameters/custom_ok"
          },
          {
            "$ref": "#/components/parameters/width_min"
          },
          {
            "$ref": "#/components/parameters/width_max"
          },
          {
            "$ref": "#/components/parameters/price_min"
          },
          {
            "$ref": "#/components/parameters/price_max"
          },
          {
            "$ref": "#/components/parameters/moq_max"
          },
          {
            "$ref": "#/components/parameters/export_ok"
          },
          {
            "$ref": "#/components/parameters/days"
          },
          {
            "$ref": "#/components/parameters/sort"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "可选。输出翻译后的枚举值（品类/材质/尺寸/计价单位/混批等，17语言字典），自由文本保持原文。不带此参数时行为不变（中文原文）。schema 端点则同时切换字段说明语言（en 已完整，其它语言字段说明回退英文）。",
            "schema": {
              "type": "string",
              "example": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "面料参数列表（`kind` 恒为 `fabric`）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StockList"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": [
          "站点"
        ],
        "operationId": "getLlmsTxt",
        "summary": "给 AI 的纯文本站点地图（llms.txt）",
        "description": "纯文本。说明本站是什么、有哪些机器可读资源、每种语言一个独立 URL 的页面清单（如 `/{lang}/insights.html`）。",
        "responses": {
          "200": {
            "description": "纯文本站点地图",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "tags": [
          "站点"
        ],
        "operationId": "getSitemap",
        "summary": "全站 sitemap（含每种语言的页面与商品详情页）",
        "responses": {
          "200": {
            "description": "sitemap",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "RateLimited": {
        "description": "按来源 IP 计数超出配额（窗口 60 秒，具体上限见 `/api/open/v1` 的 `rate_limit`）。稍后重试即可；批量抓取需要更高配额请通过站内意见箱联系。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "parameters": {
      "limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "本次返回条数上限，默认 50，最大 300。",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 300,
          "default": 50
        }
      },
      "offset": {
        "name": "offset",
        "in": "query",
        "required": false,
        "description": "分页偏移。配合响应里的 `has_more` 做翻页。",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "default": 0
        }
      },
      "group": {
        "name": "group",
        "in": "query",
        "required": false,
        "description": "只要一侧：`fabric` = 面料，`finished` = 成品（四件套 / 被子 / 毛毯等）。不传 = 两者都要。",
        "schema": {
          "type": "string",
          "enum": [
            "fabric",
            "finished"
          ],
          "example": "finished"
        }
      },
      "kindAlias": {
        "name": "kind",
        "in": "query",
        "required": false,
        "description": "`group` 的等价别名（历史参数名，行为完全相同）。两者同时传时以 `group` 为准。",
        "schema": {
          "type": "string",
          "enum": [
            "fabric",
            "finished",
            "product",
            "products"
          ]
        }
      },
      "category": {
        "name": "category",
        "in": "query",
        "required": false,
        "description": "品类精确匹配，如 `四件套` / `三件套` / `被子` / `毛毯` / `面料`。可取的真实值见 `/api/open/v1/schema` 的 `observed_values.category`。",
        "schema": {
          "type": "string"
        }
      },
      "subcategory": {
        "name": "subcategory",
        "in": "query",
        "required": false,
        "description": "子类精确匹配。真实取值见 `observed_values.subcategory`。",
        "schema": {
          "type": "string"
        }
      },
      "material": {
        "name": "material",
        "in": "query",
        "required": false,
        "description": "材质匹配，如 `全棉` / `天丝` / `绒类` / `贡缎`。既匹配完全相等，也匹配 `全棉·xx` 这种前缀合并写法。真实取值见 `observed_values.material`。",
        "schema": {
          "type": "string",
          "example": "全棉"
        }
      },
      "keyword": {
        "name": "keyword",
        "in": "query",
        "required": false,
        "description": "整条记录的关键词模糊匹配（不区分大小写，含标题 / 描述 / 参数）。",
        "schema": {
          "type": "string"
        }
      },
      "q": {
        "name": "q",
        "in": "query",
        "required": false,
        "description": "`keyword` 的等价别名。",
        "schema": {
          "type": "string"
        }
      },
      "price_min": {
        "name": "price_min",
        "in": "query",
        "required": false,
        "description": "单价下限（含）。注意不同记录币种与计价单位可能不同（见 `currency` / `price_unit`），跨币种直接比较没有意义。",
        "schema": {
          "type": "number",
          "minimum": 0
        }
      },
      "price_max": {
        "name": "price_max",
        "in": "query",
        "required": false,
        "description": "单价上限（含）。",
        "schema": {
          "type": "number",
          "minimum": 0
        }
      },
      "moq_max": {
        "name": "moq_max",
        "in": "query",
        "required": false,
        "description": "起订量上限（含）—— 用来找「小批量能拿」的货源。",
        "schema": {
          "type": "number",
          "minimum": 0
        }
      },
      "export_ok": {
        "name": "export_ok",
        "in": "query",
        "required": false,
        "description": "只要可接外贸订单的货源。传 `true` 生效；传 `false` 不生效（不会筛出「不可外贸」）。",
        "schema": {
          "type": "boolean"
        }
      },
      "days": {
        "name": "days",
        "in": "query",
        "required": false,
        "description": "只要最近 N 天上架的存货（按 `created_at`）。",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "sort": {
        "name": "sort",
        "in": "query",
        "required": false,
        "description": "排序方式。默认 `new`（按更新时间倒序）。",
        "schema": {
          "type": "string",
          "enum": [
            "new",
            "price_asc",
            "price_desc",
            "moq_asc"
          ],
          "default": "new"
        }
      },
      "print_type": {
        "name": "print_type",
        "in": "query",
        "required": false,
        "description": "印染方式精确匹配，如 `reactive_print`（活性印染，环保、色牢度高）/ 涂料印染 / 色织。真实取值见 `observed_values.print_type`。",
        "schema": {
          "type": "string"
        }
      },
      "weave": {
        "name": "weave",
        "in": "query",
        "required": false,
        "description": "织法精确匹配，如 `汗布` / `平纹` / `斜纹` / `贡缎` / `提花`。真实取值见 `observed_values.weave`。",
        "schema": {
          "type": "string"
        }
      },
      "sample_ok": {
        "name": "sample_ok",
        "in": "query",
        "required": false,
        "description": "只要**可寄样**的面料（`true` 生效）。寄样由卖家直接寄出，不由平台代寄。",
        "schema": {
          "type": "boolean"
        }
      },
      "custom_ok": {
        "name": "custom_ok",
        "in": "query",
        "required": false,
        "description": "只要**可定织**（可按要求改参数或打样生产）的面料。",
        "schema": {
          "type": "boolean"
        }
      },
      "width_min": {
        "name": "width_min",
        "in": "query",
        "required": false,
        "description": "门幅下限（含），单位 cm。行业俗称 `240门幅` = `240`。",
        "schema": {
          "type": "number",
          "minimum": 0
        }
      },
      "width_max": {
        "name": "width_max",
        "in": "query",
        "required": false,
        "description": "门幅上限（含），单位 cm。",
        "schema": {
          "type": "number",
          "minimum": 0
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "ok"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "description": "错误说明（中文）",
            "example": "未找到该端点"
          },
          "hint": {
            "type": "string",
            "description": "下一步该看哪里",
            "example": "可用端点见 https://ucunhome.com/api/open/v1"
          }
        }
      },
      "ApiIndex": {
        "type": "object",
        "description": "接口索引。字段可能随版本新增，`1.x` 内不做删除或改名。",
        "required": [
          "ok",
          "api_version",
          "endpoints"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "api": {
            "type": "string",
            "example": "优纯严选 · 开放数据 API"
          },
          "api_en": {
            "type": "string",
            "example": "Youcun Select Open Data API"
          },
          "api_version": {
            "type": "string",
            "example": "1.0.0"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "site": {
            "type": "string",
            "format": "uri",
            "example": "https://ucunhome.com"
          },
          "docs": {
            "type": "string",
            "format": "uri",
            "description": "人读的接口文档页"
          },
          "docs_note": {
            "type": "string"
          },
          "purpose": {
            "type": "string",
            "description": "中文用途说明"
          },
          "purpose_en": {
            "type": "string",
            "description": "英文用途说明"
          },
          "endpoints": {
            "type": "array",
            "description": "可用端点清单",
            "items": {
              "$ref": "#/components/schemas/EndpointInfo"
            }
          },
          "param_note": {
            "type": "string",
            "description": "关于未识别参数会回显在 ignored_filters 的说明"
          },
          "stats": {
            "$ref": "#/components/schemas/Stats"
          },
          "rate_limit": {
            "type": "object",
            "properties": {
              "window_seconds": {
                "type": "integer",
                "example": 60
              },
              "max_requests_per_ip": {
                "type": "integer",
                "nullable": true,
                "description": "每 IP 每窗口最大请求数；超限返回 429"
              },
              "note": {
                "type": "string"
              }
            }
          },
          "privacy": {
            "type": "object",
            "properties": {
              "contact_info": {
                "type": "string"
              },
              "anonymous_suppliers": {
                "type": "string"
              },
              "locked_params": {
                "type": "string"
              }
            }
          },
          "license": {
            "type": "object",
            "properties": {
              "usage": {
                "type": "string"
              },
              "requirement": {
                "type": "string"
              },
              "prohibited": {
                "type": "string"
              },
              "freshness": {
                "type": "string"
              }
            }
          },
          "quick_start": {
            "type": "array",
            "description": "建议的调用顺序",
            "items": {
              "type": "string"
            }
          },
          "changelog": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "version": {
                  "type": "string"
                },
                "date": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "EndpointInfo": {
        "type": "object",
        "properties": {
          "method": {
            "type": "string",
            "enum": [
              "GET"
            ]
          },
          "path": {
            "type": "string",
            "example": "/api/open/v1/stocks"
          },
          "desc": {
            "type": "string"
          },
          "params": {
            "type": "array",
            "description": "该端点可用参数（文字说明形态）",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Stats": {
        "type": "object",
        "properties": {
          "on_sale_total": {
            "type": "integer",
            "description": "在售存货总条数（成品 + 面料）"
          },
          "fabric": {
            "type": "integer",
            "description": "在售面料条数"
          },
          "finished": {
            "type": "integer",
            "description": "在售成品条数"
          },
          "suppliers": {
            "type": "integer",
            "description": "当前有在售货源的商家数"
          }
        }
      },
      "FieldSchema": {
        "type": "object",
        "description": "字段字典：告诉 AI「每个字段是什么意思」。",
        "required": [
          "ok",
          "api_version",
          "groups"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "api_version": {
            "type": "string"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "about": {
            "type": "string"
          },
          "value_conventions": {
            "type": "object",
            "description": "取值约定：空值 / 布尔 / 时间 / 图片 / 价格 / 联系方式各自怎么读",
            "properties": {
              "null_means": {
                "type": "string"
              },
              "boolean": {
                "type": "string"
              },
              "time": {
                "type": "string"
              },
              "image_url": {
                "type": "string"
              },
              "price": {
                "type": "string"
              },
              "contact": {
                "type": "string"
              }
            }
          },
          "groups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FieldGroup"
            }
          },
          "observed_values": {
            "type": "object",
            "description": "从当前在售数据实时统计出的真实取值 —— 可直接当作筛选参数用，比猜测准。",
            "properties": {
              "category": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "subcategory": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "material": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "print_type": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "weave": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "price_unit": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "observed_note": {
            "type": "string"
          }
        }
      },
      "FieldGroup": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "common",
              "fabric",
              "quality",
              "supplier"
            ],
            "description": "common=成品与面料都有；fabric=仅面料；quality=品质（成品为主）；supplier=供应商（不含联系方式）"
          },
          "cn": {
            "type": "string",
            "description": "分组中文名"
          },
          "en": {
            "type": "string",
            "description": "分组英文名"
          },
          "fields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FieldDef"
            }
          }
        }
      },
      "FieldDef": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "price"
          },
          "cn": {
            "type": "string",
            "example": "单价"
          },
          "en": {
            "type": "string",
            "example": "Unit price"
          },
          "type": {
            "type": "string",
            "example": "number"
          },
          "unit": {
            "type": "string",
            "example": "g/m²"
          },
          "enums": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "desc": {
            "type": "string"
          }
        }
      },
      "StockList": {
        "type": "object",
        "required": [
          "ok",
          "api_version",
          "total",
          "returned",
          "items"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "api_version": {
            "type": "string",
            "example": "1.0.0"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "kind": {
            "type": "string",
            "enum": [
              "stock",
              "fabric"
            ],
            "description": "本次调用的端点类型：`stock`=/stocks（成品+面料），`fabric`=/fabrics（仅面料）"
          },
          "total": {
            "type": "integer",
            "description": "符合筛选条件的总条数（不是本次返回数）"
          },
          "returned": {
            "type": "integer",
            "description": "本次实际返回条数"
          },
          "offset": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "has_more": {
            "type": "boolean",
            "description": "为 true 时用 `offset += returned` 取下一页"
          },
          "filters": {
            "type": "object",
            "description": "本次请求里带的筛选参数原文",
            "additionalProperties": {
              "type": "string"
            }
          },
          "applied_filters": {
            "type": "object",
            "description": "**真正生效**的筛选条件（含被归一化后的值，如 `sample_ok` 转成了布尔）",
            "additionalProperties": true
          },
          "ignored_filters": {
            "type": "array",
            "description": "未被识别的参数名 —— 这些**没有**参与筛选，别以为筛过了",
            "items": {
              "type": "string"
            }
          },
          "ignored_note": {
            "type": "string",
            "nullable": true,
            "description": "有未识别参数时的提醒文案，无则为 null"
          },
          "schema": {
            "type": "string",
            "format": "uri",
            "description": "字段字典地址"
          },
          "note": {
            "type": "string",
            "description": "本响应的解读提醒（空值 / 价格 / 起订量）"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StockItem"
            }
          }
        }
      },
      "StockItem": {
        "type": "object",
        "description": "一条在售存货。面料专属字段仅在 `kind=fabric` 时出现（`param_locked=true` 时其中部分会被平台隐去）。\n\n**除 `id` / `kind` / `title` 外，字段一律可能为 `null`** —— null 表示商家未填写。",
        "required": [
          "id",
          "kind",
          "title"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "货品编号，平台内唯一。详情页：`/detail.html?id={id}`",
            "example": "mts7e2k43z3h3"
          },
          "kind": {
            "type": "string",
            "enum": [
              "finished",
              "fabric"
            ],
            "description": "`finished` = 成品存货，`fabric` = 面料存货"
          },
          "title": {
            "type": "string",
            "nullable": true,
            "description": "标题"
          },
          "title_en": {
            "type": "string",
            "nullable": true,
            "description": "商家填写的外贸标题（可能为空）"
          },
          "category": {
            "type": "string",
            "nullable": true,
            "description": "品类，如 四件套 / 三件套 / 被子 / 毛毯 / 面料"
          },
          "subcategory": {
            "type": "string",
            "nullable": true,
            "description": "子类"
          },
          "material": {
            "type": "string",
            "nullable": true,
            "description": "材质，如 全棉 / 天丝 / 绒类 / 贡缎"
          },
          "filling_material": {
            "type": "string",
            "nullable": true,
            "description": "填充物（被芯类）"
          },
          "yarn_spec": {
            "type": "string",
            "nullable": true,
            "description": "纱支。行业写法：`40支` = 40×40；经纬不同写 `21×32`"
          },
          "fabric_tech": {
            "type": "string",
            "nullable": true,
            "description": "工艺，如 素色 / 印花 / 提花 / 磨毛"
          },
          "size": {
            "type": "string",
            "nullable": true,
            "description": "规格尺寸（cm），如 `200*230`"
          },
          "fabric_count": {
            "type": "string",
            "nullable": true,
            "description": "密度。行业写法：`12868` = 128×68 根/英寸"
          },
          "fabric_weight": {
            "type": "number",
            "nullable": true,
            "description": "克重（g/m²）"
          },
          "quilt_weight": {
            "type": "number",
            "nullable": true,
            "description": "被重（kg）"
          },
          "price": {
            "type": "number",
            "nullable": true,
            "description": "**单价**（不是总价）。计价单位见 `price_unit`，币种见 `currency`"
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "description": "币种，默认 `CNY`。跨境报价务必读此字段，不要假定美元"
          },
          "usd_ref": {
            "type": "object",
            "description": "美元参考价（FOB 口径）：{currency,min,max,basis,basis_cn}。区间 = 人民币单价上浮20–40%（×1.2–1.4）÷ 固定汇率 6.75，含尺寸变体取全区间。仅供 AI/海外买家比价，非实时报价，实际成交以询盘为准。",
            "properties": {
              "currency": {
                "type": "string",
                "example": "USD"
              },
              "min": {
                "type": "number",
                "description": "区间下限 = 最低单价（含尺寸变体）×1.2 ÷ 6.75",
                "example": 24.5
              },
              "max": {
                "type": "number",
                "description": "区间上限 = 最高单价（含尺寸变体）×1.4 ÷ 6.75",
                "example": 28.6
              },
              "basis": {
                "type": "string",
                "description": "口径说明（英文）"
              },
              "basis_cn": {
                "type": "string",
                "description": "口径说明（中文）"
              }
            },
            "nullable": true
          },
          "price_unit": {
            "type": "string",
            "nullable": true,
            "description": "计价单位，如 套 / 条 / 件 / 公斤 / 米。面料按米或按公斤，务必看清"
          },
          "min_order": {
            "type": "number",
            "nullable": true,
            "description": "起订量，单位与 `price_unit` 一致。最小起订金额 = `price × min_order`"
          },
          "stock_count": {
            "type": "number",
            "nullable": true,
            "description": "现货数量（售完即止）"
          },
          "mix_batch": {
            "type": "string",
            "nullable": true,
            "description": "混批说明"
          },
          "mix_batch_ok": {
            "type": "boolean",
            "nullable": true,
            "description": "是否支持混批"
          },
          "brand_decl": {
            "type": "string",
            "nullable": true,
            "description": "品牌声明，如 无品牌 / 自有品牌"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "描述"
          },
          "spec": {
            "type": "string",
            "nullable": true,
            "description": "规格补充"
          },
          "images": {
            "type": "array",
            "description": "图片绝对 URL 数组，可直接引用（可能为空数组）",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "video": {
            "type": "string",
            "nullable": true,
            "description": "视频"
          },
          "status": {
            "type": "string",
            "nullable": true,
            "enum": [
              "onsale"
            ],
            "description": "本接口只返回 `onsale`（在售）"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "上架时间（ISO 8601，UTC）"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "更新时间（ISO 8601，UTC）"
          },
          "view_count": {
            "type": "number",
            "nullable": true,
            "description": "浏览量"
          },
          "export_ok": {
            "type": "boolean",
            "nullable": true,
            "description": "是否可接外贸订单"
          },
          "export_note": {
            "type": "string",
            "nullable": true,
            "description": "外贸说明"
          },
          "inspection_reports": {
            "type": "array",
            "description": "质检报告绝对 URL 数组（可能为空数组）",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "quality": {
            "$ref": "#/components/schemas/Quality"
          },
          "supplier": {
            "$ref": "#/components/schemas/Supplier"
          },
          "density": {
            "type": "string",
            "nullable": true,
            "description": "【面料】密度，根/英寸，行业写法 `12868` = 128×68"
          },
          "gsm": {
            "type": "number",
            "nullable": true,
            "description": "【面料】克重（g/m²）"
          },
          "width_cm": {
            "type": "number",
            "nullable": true,
            "description": "【面料】门幅（cm）。行业俗称 `240门幅` = 240"
          },
          "weave": {
            "type": "string",
            "nullable": true,
            "description": "【面料】织法，如 汗布 / 平纹 / 斜纹 / 贡缎 / 提花"
          },
          "gauge": {
            "type": "string",
            "nullable": true,
            "description": "【面料】克重 / 规格补充"
          },
          "print_type": {
            "type": "string",
            "nullable": true,
            "description": "【面料】印染方式，如 `reactive_print`（活性印染）"
          },
          "pattern": {
            "type": "string",
            "nullable": true,
            "description": "【面料】花型"
          },
          "use_for": {
            "type": "string",
            "nullable": true,
            "description": "【面料】用途，如 四件套面料 / 被壳面料"
          },
          "colorways": {
            "type": "string",
            "nullable": true,
            "description": "【面料】配色数：一个花型有几种配色（买家选色的维度）"
          },
          "colors": {
            "type": "string",
            "nullable": true,
            "description": "【面料】色号：具体颜色名 / 色卡编号"
          },
          "lead_time_days": {
            "type": "number",
            "nullable": true,
            "description": "【面料】交期（天）"
          },
          "sample_ok": {
            "type": "boolean",
            "nullable": true,
            "description": "【面料】可否寄样（由卖家直接寄出）"
          },
          "custom_ok": {
            "type": "boolean",
            "nullable": true,
            "description": "【面料】可否定织"
          },
          "shrinkage_pct": {
            "type": "number",
            "nullable": true,
            "description": "【面料】缩水率（%）"
          },
          "colorfastness_grade": {
            "type": "string",
            "nullable": true,
            "description": "【面料】色牢度等级"
          },
          "verification": {
            "type": "string",
            "nullable": true,
            "description": "【面料】检测核验"
          },
          "standard": {
            "type": "string",
            "nullable": true,
            "description": "【面料】执行标准；默认中国国家标准（GB / GB-T），不等同于 ASTM / EN / JIS / IS / GOST 等其他体系；为空 = 商家未声明，不代表符合任何标准"
          },
          "region": {
            "type": "string",
            "nullable": true,
            "description": "【面料】产地"
          },
          "export_standard": {
            "type": "string",
            "nullable": true,
            "description": "【面料】出口标准"
          },
          "param_locked": {
            "type": "boolean",
            "description": "【面料】true = 商家选择了「详细参数仅对验证买家开放」，此时部分参数已被平台隐去（该字段本身一定存在）"
          }
        }
      },
      "Quality": {
        "type": "object",
        "description": "品质信息（成品存货为主）。库存货的品质分级与已知瑕疵是买断决策的关键。",
        "properties": {
          "grade": {
            "type": "string",
            "nullable": true,
            "description": "品质等级，如 全新 / 微瑕"
          },
          "storage": {
            "type": "string",
            "nullable": true,
            "description": "存放时长"
          },
          "defects": {
            "type": "array",
            "description": "已知瑕疵",
            "items": {
              "type": "string"
            }
          },
          "safety": {
            "type": "array",
            "description": "安全项，如 无甲醛",
            "items": {
              "type": "string"
            }
          },
          "batch": {
            "type": "array",
            "description": "批次说明",
            "items": {
              "type": "string"
            }
          },
          "photos": {
            "type": "array",
            "description": "实拍图绝对 URL",
            "items": {
              "type": "string",
              "format": "uri"
            }
          }
        }
      },
      "Supplier": {
        "type": "object",
        "description": "供应商信息。**出于隐私设计，本接口不含任何联系方式**（手机 / 微信 / 邮箱 / 地址）。",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true,
            "description": "供应商名称；商家选择匿名发布时为 `null`"
          },
          "verified": {
            "type": "boolean",
            "description": "是否平台核验"
          },
          "rating_avg": {
            "type": "number",
            "nullable": true,
            "description": "平均评分（5 分制）；无评价时为 `null`"
          },
          "rating_count": {
            "type": "number",
            "nullable": true,
            "description": "评价条数"
          }
        }
      }
    }
  }
}