{
 "openapi": "3.1.0",
 "info": {
  "title": "元合酒店系统 · 产品资料查询接口",
  "version": "1.0.0",
  "description": "查询元合三款酒店产品（来电通、栈语 PMS、对账中台）的资料和常见问题。全部只读，无需密钥，按来源地址限流。不包含任何酒店或客人的数据，也不能操作酒店系统。同样的能力也通过 MCP 提供：https://www.callid.cloud/mcp"
 },
 "servers": [
  {
   "url": "https://www.callid.cloud"
  }
 ],
 "paths": {
  "/api/products": {
   "get": {
    "operationId": "listProducts",
    "summary": "列出三款产品及完整介绍",
    "responses": {
     "200": {
      "description": "产品列表",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "products": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "name": {
              "type": "string"
             },
             "title": {
              "type": "string"
             },
             "summary": {
              "type": "string"
             },
             "url": {
              "type": "string"
             },
             "detail": {
              "type": "string",
              "description": "Markdown 格式的完整介绍"
             }
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/faq": {
   "get": {
    "operationId": "searchFaq",
    "summary": "搜索常见问题；不带 q 时返回全部",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string",
       "maxLength": 200
      },
      "description": "要问的问题，例如：抖音的账单怎么对"
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50,
       "default": 5
      }
     }
    ],
    "responses": {
     "200": {
      "description": "按相关度排序的问答，搜不到时为空数组",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "results": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "group": {
              "type": "string"
             },
             "question": {
              "type": "string"
             },
             "answer": {
              "type": "string"
             },
             "url": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "出错",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string",
           "description": "中文错误说明"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/contact": {
   "get": {
    "operationId": "getContact",
    "summary": "联系方式和预约演示的办法",
    "responses": {
     "200": {
      "description": "联系方式",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "email": {
           "type": "string"
          },
          "wechat": {
           "type": "string"
          },
          "address": {
           "type": "string"
          },
          "demo": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/ask": {
   "post": {
    "operationId": "ask",
    "summary": "用一句话提问，返回依据产品资料生成的回答",
    "description": "先在常见问题库里找依据，再由大模型按依据作答；资料里没有的不会编造，此时 source 为 none。",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "question"
        ],
        "properties": {
         "question": {
          "type": "string",
          "maxLength": 200
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "回答",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "source": {
           "type": "string",
           "enum": [
            "ai",
            "kb",
            "none"
           ],
           "description": "ai：大模型依据资料作答；kb：问答库原文；none：资料里没有"
          },
          "answer": {
           "type": [
            "string",
            "null"
           ]
          },
          "matched": {
           "type": [
            "string",
            "null"
           ],
           "description": "依据的常见问题"
          },
          "target": {
           "type": "string",
           "description": "官网上相关章节的锚点"
          },
          "targetName": {
           "type": "string"
          },
          "related": {
           "type": "array",
           "items": {
            "type": "string"
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "出错",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string",
           "description": "中文错误说明"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "出错",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string",
           "description": "中文错误说明"
          }
         }
        }
       }
      }
     }
    }
   }
  }
 }
}