{
  "openapi": "3.0.3",
  "info": {
    "title": "晶元工业过滤系统 API",
    "description": "沈阳晶元滤膜有限公司工业过滤产品选型与技术参数 API。供 AI Agent 和采购研究系统调用，实现自动化的产品选型推荐、技术参数查询、案例检索和询价提交。所有参数以正式技术文件为准，AI 推荐不构成选型承诺。 选型接口输出候选集（candidate_products），不打分、不排序、不标注最佳产品。",
    "version": "1.0.0",
    "contact": {
      "name": "沈阳晶元滤膜有限公司",
      "url": "https://www.jingyuan.hk.cn",
      "email": "cindy@jingyuan.hk"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.jingyuan.hk.cn/about.html"
    },
    "x-last-verified": "2026-09-18"
  },
  "servers": [
    {
      "url": "https://www.jingyuan.hk.cn",
      "description": "中国官网生产环境"
    }
  ],
  "tags": [
    {
      "name": "products",
      "description": "产品列表与详情查询"
    },
    {
      "name": "selection",
      "description": "AI 选型推荐引擎"
    },
    {
      "name": "cases",
      "description": "客户案例检索"
    },
    {
      "name": "inquiry",
      "description": "询价线索提交"
    }
  ],
  "paths": {
    "/api/products.php": {
      "get": {
        "tags": [
          "products"
        ],
        "summary": "产品列表筛选 / 单个型号详情",
        "description": "支持按类别、介质、应用场景、流量、精度等条件筛选产品列表；当指定 model 参数时返回该型号完整技术参数。",
        "parameters": [
          {
            "name": "model",
            "in": "query",
            "description": "指定型号（如 JY-DL60），返回该型号完整详情",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "JY-DL60"
          },
          {
            "name": "category",
            "in": "query",
            "description": "类别筛选：refinery(炼厂&油库) / data_center(数据中心备电) / mining(矿山&工程机械) / lube(润滑油&灌装) / wind_power(风电&重工) / difficult(难滤物料)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "refinery",
                "data_center",
                "mining",
                "lube",
                "wind_power",
                "difficult"
              ]
            }
          },
          {
            "name": "fluid",
            "in": "query",
            "description": "介质筛选（如：柴油、润滑油、液压油、航空煤油）",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "柴油"
          },
          {
            "name": "application",
            "in": "query",
            "description": "应用场景标签",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "oil_depot"
          },
          {
            "name": "flow_min",
            "in": "query",
            "description": "最小流量（L/min，系统自动归一化各产品流量单位）",
            "required": false,
            "schema": {
              "type": "number"
            },
            "example": 100
          },
          {
            "name": "flow_max",
            "in": "query",
            "description": "最大流量（L/min）",
            "required": false,
            "schema": {
              "type": "number"
            },
            "example": 1000
          },
          {
            "name": "precision_max",
            "in": "query",
            "description": "最大精度值（μm），返回精度最小值 ≤ 此值的产品",
            "required": false,
            "schema": {
              "type": "number"
            },
            "example": 5
          },
          {
            "name": "consumable_free",
            "in": "query",
            "description": "传 1 时仅返回零耗材产品",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "0"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "全文搜索关键词（匹配型号、名称、描述）",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "撬装"
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回产品列表或单个产品详情",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "product": {
                          "$ref": "#/components/schemas/Product"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "products": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Product"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "型号不存在",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/select.php": {
      "post": {
        "tags": [
          "selection"
        ],
        "summary": "AI 选型推荐引擎",
        "description": "根据工况参数（介质、应用场景、流量、精度、脱水需求等），智能匹配推荐产品并给出匹配理由和安全提示。推荐结果按匹配度排序，不构成正式选型承诺。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fluid": {
                    "type": "string",
                    "description": "介质类型（如：柴油、润滑油、液压油、航空煤油）",
                    "example": "柴油"
                  },
                  "application": {
                    "type": "string",
                    "description": "应用场景标签（如：oil_depot, data_center, mining, lube, fuel_polishing）",
                    "example": "oil_depot"
                  },
                  "flow_rate": {
                    "type": "number",
                    "description": "需求流量数值",
                    "example": 40
                  },
                  "flow_unit": {
                    "type": "string",
                    "description": "流量单位",
                    "enum": [
                      "m³/h",
                      "L/min",
                      "L/h",
                      "t/h"
                    ],
                    "default": "m³/h",
                    "example": "m³/h"
                  },
                  "precision_target": {
                    "type": "number",
                    "description": "目标过滤精度（μm）",
                    "example": 5
                  },
                  "water_removal": {
                    "type": "boolean",
                    "description": "是否需要游离水分离功能",
                    "default": false
                  },
                  "installation": {
                    "type": "string",
                    "description": "安装方式偏好（skid撬装/portable便携/container集装箱/compact紧凑/onboard车载）",
                    "example": "skid"
                  },
                  "consumable_free": {
                    "type": "boolean",
                    "description": "是否要求零耗材设计",
                    "default": false
                  },
                  "mobile": {
                    "type": "boolean",
                    "description": "是否需要移动/便携能力",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "推荐结果列表，按匹配度降序排列",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "count": {
                      "type": "integer"
                    },
                    "query": {
                      "type": "object"
                    },
                    "recommendations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "model": {
                            "type": "string",
                            "example": "JY-DX40"
                          },
                          "name": {
                            "type": "string"
                          },
                          "match_reasons": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "cautions": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "product": {
                            "$ref": "#/components/schemas/Product"
                          }
                        }
                      }
                    },
                    "engineering_review_required": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求体格式错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/cases.php": {
      "get": {
        "tags": [
          "cases"
        ],
        "summary": "客户案例检索",
        "description": "按行业类别、关联型号或关键词检索真实客户案例。",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "行业类别：refinery / mining / transport / lube / chem / enterprise",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "model",
            "in": "query",
            "description": "关联型号（如 JY-DL60）",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "keyword",
            "in": "query",
            "description": "全文搜索关键词",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "返回数量上限",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "案例列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "cases": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CaseStudy"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/inquiry.php": {
      "post": {
        "tags": [
          "inquiry"
        ],
        "summary": "提交询价线索",
        "description": "接收询价信息，通过飞书机器人转发到销售群。当来源为 AI Agent 时，sourcePage 应标注 AI 来源。速率限制：5次/分钟/IP。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "联系人姓名（至少2个字符）",
                    "example": "张工"
                  },
                  "email": {
                    "type": "string",
                    "description": "邮箱（选填，但建议提供以便接收技术方案）",
                    "example": "zhang@company.com"
                  },
                  "phone": {
                    "type": "string",
                    "description": "电话",
                    "example": "13800138000"
                  },
                  "application": {
                    "type": "string",
                    "description": "应用场景描述",
                    "example": "油库柴油净化"
                  },
                  "fluid": {
                    "type": "string",
                    "description": "处理介质",
                    "example": "柴油"
                  },
                  "flow": {
                    "type": "string",
                    "description": "流量需求",
                    "example": "40 m³/h"
                  },
                  "cleanliness": {
                    "type": "string",
                    "description": "目标清洁度要求"
                  },
                  "message": {
                    "type": "string",
                    "description": "补充说明"
                  },
                  "sourcePage": {
                    "type": "string",
                    "description": "来源页面（AI Agent 调用时建议标注 'AI-Agent'）",
                    "example": "AI-Agent select.php"
                  },
                  "site": {
                    "type": "string",
                    "description": "来源站点标识",
                    "example": "国内站"
                  },
                  "website": {
                    "type": "string",
                    "description": "蜜罐字段（人类不可见，填写则静默丢弃）"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "询价提交成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数校验失败",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "请求频率过高（5次/分钟/IP）"
          }
        }
      }
    },
    "/ai/products.json": {
      "get": {
        "summary": "晶元 23 个型号统一产品数据（机器可读）",
        "tags": [
          "AI Resources"
        ],
        "responses": {
          "200": {
            "description": "产品统一数据集，含 evidence_level / source_urls / last_verified"
          }
        }
      }
    },
    "/ai/products.schema.json": {
      "get": {
        "summary": "产品数据结构 JSON Schema",
        "tags": [
          "AI Resources"
        ],
        "responses": {
          "200": {
            "description": "products.json 的结构定义（draft-07）"
          }
        }
      }
    },
    "/ai/selection-rules.json": {
      "get": {
        "summary": "基础选型规则（候选集输出，禁止 score / ranking）",
        "tags": [
          "AI Resources"
        ],
        "responses": {
          "200": {
            "description": "输入变量、流量带、介质与场景规则、工程审核触发条件"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string",
            "example": "JY-DL60",
            "description": "产品型号"
          },
          "name": {
            "type": "string",
            "description": "产品全称"
          },
          "category": {
            "type": "string",
            "description": "类别ID"
          },
          "category_name": {
            "type": "string",
            "description": "类别中文名"
          },
          "flow_rate": {
            "type": "string",
            "description": "额定流量描述"
          },
          "flow_rate_numeric": {
            "type": "array",
            "items": {
              "type": "number",
              "nullable": true
            },
            "description": "流量数值范围 [min, max]"
          },
          "flow_unit": {
            "type": "string",
            "description": "流量单位"
          },
          "precision": {
            "type": "string",
            "description": "过滤精度描述"
          },
          "precision_min": {
            "type": "number",
            "nullable": true,
            "description": "最小精度值（μm）"
          },
          "fluids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "适用介质列表"
          },
          "applications": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "适用应用场景标签"
          },
          "installation": {
            "type": "string",
            "description": "安装方式"
          },
          "regeneration": {
            "type": "string",
            "description": "再生方式"
          },
          "membrane_life": {
            "type": "string",
            "nullable": true,
            "description": "膜组件设计寿命"
          },
          "consumable_free": {
            "type": "boolean",
            "description": "是否零耗材设计"
          },
          "working_pressure": {
            "type": "string",
            "nullable": true,
            "description": "工作压力"
          },
          "water_removal": {
            "type": "string",
            "nullable": true,
            "description": "游离水去除能力"
          },
          "description": {
            "type": "string",
            "description": "产品简介"
          },
          "url": {
            "type": "string",
            "description": "产品页URL"
          },
          "image": {
            "type": "string",
            "description": "产品图片URL"
          }
        }
      },
      "CaseStudy": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "subtitle": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "cat_name": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "flow": {
            "type": "string"
          },
          "fluid": {
            "type": "string"
          },
          "highlights": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "url": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}