{
  "openapi": "3.1.0",
  "info": {
    "title": "Lan-快乐小屋 · AI 账号比价 API",
    "version": "1.0.0",
    "description": "AI 账号比价数据服务。聚合多家发卡店铺的在售商品报价，支持按产品线与服务形态检索、跨店比价、价格历史查询。所有接口返回 `summary` 字段（可直接引用）与 `as_of` 时间戳。",
    "contact": {
      "url": "https://shop.hy666666.me"
    }
  },
  "servers": [
    {
      "url": "https://shop.hy666666.me"
    }
  ],
  "tags": [
    {
      "name": "search_products",
      "description": "按关键词搜索 AI 账号商品，返回按价格升序的报价（含店铺、库存、购买链接）。适合回答「X 多少钱」「有没有便宜的 X」。关键词支持多词，如 \"ChatGPT Plus\"、\"claude 成品号\"。"
    },
    {
      "name": "get_cheapest",
      "description": "给定产品线 / 服务形态 / 预算，直接返回最便宜的几个购买选项。比 search_products 更精确，适合回答「ChatGPT 成品号最便宜多少」「200 元以内的 Claude 有什么」。"
    },
    {
      "name": "compare_product",
      "description": "给一个商品（key 或标题），返回它所属类别下所有店铺的报价排序与价格统计（最低/中位/均价）。适合回答「这个东西哪家便宜」「价格合不合理」。"
    },
    {
      "name": "price_history",
      "description": "查某个商品近 N 天的价格采样与涨跌幅。适合回答「这个涨价了吗」「最近行情怎么样」。"
    },
    {
      "name": "market_overview",
      "description": "返回全站或指定产品线的市场规模：商品数、店铺数、价格区间、各服务形态的最低价、商品最多的店铺。适合回答「ChatGPT 账号市场什么行情」「哪个形态最划算」。"
    },
    {
      "name": "list_categories",
      "description": "返回本站支持的产品线与服务形态清单，以及每个「产品线 × 形态」组合的件数与最低价。用于理解可选空间。"
    },
    {
      "name": "find_shops",
      "description": "按关键词或产品线查找发卡店铺，返回在售商品数、最低价、销量。"
    }
  ],
  "paths": {
    "/api/agent/search_products": {
      "post": {
        "tags": [
          "search_products"
        ],
        "summary": "搜索商品比价",
        "description": "按关键词搜索 AI 账号商品，返回按价格升序的报价（含店铺、库存、购买链接）。适合回答「X 多少钱」「有没有便宜的 X」。关键词支持多词，如 \"ChatGPT Plus\"、\"claude 成品号\"。",
        "operationId": "search_products",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "搜索关键词，如 \"ChatGPT Plus\"、\"claude opus\""
                  },
                  "limit": {
                    "type": "integer",
                    "description": "返回条数，默认 10，最大 50"
                  },
                  "max_price": {
                    "type": "number",
                    "description": "价格上限（人民币元）"
                  },
                  "min_price": {
                    "type": "number",
                    "description": "价格下限（人民币元）"
                  },
                  "in_stock": {
                    "type": "boolean",
                    "description": "只看有库存的"
                  }
                },
                "required": [
                  "query"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "type": "string",
                      "description": "可直接引用给用户的一句话结论"
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "last_scan": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "error": {
                      "type": "string"
                    },
                    "hint": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误"
          },
          "429": {
            "description": "超出速率限制"
          }
        }
      },
      "get": {
        "tags": [
          "search_products"
        ],
        "summary": "搜索商品比价（GET 形式）",
        "operationId": "search_products_get",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "搜索关键词，如 \"ChatGPT Plus\"、\"claude opus\""
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "返回条数，默认 10，最大 50"
          },
          {
            "name": "max_price",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "价格上限（人民币元）"
          },
          {
            "name": "min_price",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "价格下限（人民币元）"
          },
          {
            "name": "in_stock",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "只看有库存的"
          }
        ],
        "responses": {
          "200": {
            "description": "成功"
          }
        }
      }
    },
    "/api/agent/get_cheapest": {
      "post": {
        "tags": [
          "get_cheapest"
        ],
        "summary": "找最便宜方案",
        "description": "给定产品线 / 服务形态 / 预算，直接返回最便宜的几个购买选项。比 search_products 更精确，适合回答「ChatGPT 成品号最便宜多少」「200 元以内的 Claude 有什么」。",
        "operationId": "get_cheapest",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "product_line": {
                    "type": "string",
                    "description": "产品线 id 或名称，如 \"chatgpt\" / \"ChatGPT\" / \"claude\" / \"gemini\" / \"grok\"",
                    "enum": [
                      "chatgpt",
                      "claude",
                      "gemini",
                      "grok",
                      "coding",
                      "image",
                      "api",
                      "other-ai",
                      "general"
                    ]
                  },
                  "form": {
                    "type": "string",
                    "description": "服务形态 id 或名称，如 \"account\"（成品号）/ \"recharge\"（官方充值）/ \"cdk\"（卡密）/ \"sms\"（接码）",
                    "enum": [
                      "account",
                      "tutorial",
                      "cdk",
                      "recharge",
                      "sms",
                      "quota",
                      "other"
                    ]
                  },
                  "max_price": {
                    "type": "number",
                    "description": "预算上限（人民币元）"
                  },
                  "in_stock": {
                    "type": "boolean",
                    "description": "只看有库存的"
                  },
                  "keyword": {
                    "type": "string",
                    "description": "额外标题关键词过滤"
                  },
                  "limit": {
                    "type": "integer",
                    "description": "返回条数，默认 3，最大 20"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "type": "string",
                      "description": "可直接引用给用户的一句话结论"
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "last_scan": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "error": {
                      "type": "string"
                    },
                    "hint": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误"
          },
          "429": {
            "description": "超出速率限制"
          }
        }
      },
      "get": {
        "tags": [
          "get_cheapest"
        ],
        "summary": "找最便宜方案（GET 形式）",
        "operationId": "get_cheapest_get",
        "parameters": [
          {
            "name": "product_line",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "chatgpt",
                "claude",
                "gemini",
                "grok",
                "coding",
                "image",
                "api",
                "other-ai",
                "general"
              ]
            },
            "description": "产品线 id 或名称，如 \"chatgpt\" / \"ChatGPT\" / \"claude\" / \"gemini\" / \"grok\""
          },
          {
            "name": "form",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "account",
                "tutorial",
                "cdk",
                "recharge",
                "sms",
                "quota",
                "other"
              ]
            },
            "description": "服务形态 id 或名称，如 \"account\"（成品号）/ \"recharge\"（官方充值）/ \"cdk\"（卡密）/ \"sms\"（接码）"
          },
          {
            "name": "max_price",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "预算上限（人民币元）"
          },
          {
            "name": "in_stock",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "只看有库存的"
          },
          {
            "name": "keyword",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "额外标题关键词过滤"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "返回条数，默认 3，最大 20"
          }
        ],
        "responses": {
          "200": {
            "description": "成功"
          }
        }
      }
    },
    "/api/agent/compare_product": {
      "post": {
        "tags": [
          "compare_product"
        ],
        "summary": "同类商品跨店比价",
        "description": "给一个商品（key 或标题），返回它所属类别下所有店铺的报价排序与价格统计（最低/中位/均价）。适合回答「这个东西哪家便宜」「价格合不合理」。",
        "operationId": "compare_product",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "goods_key": {
                    "type": "string",
                    "description": "商品 key（来自 search_products）"
                  },
                  "title": {
                    "type": "string",
                    "description": "商品标题关键词（没有 key 时用）"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "type": "string",
                      "description": "可直接引用给用户的一句话结论"
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "last_scan": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "error": {
                      "type": "string"
                    },
                    "hint": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误"
          },
          "429": {
            "description": "超出速率限制"
          }
        }
      },
      "get": {
        "tags": [
          "compare_product"
        ],
        "summary": "同类商品跨店比价（GET 形式）",
        "operationId": "compare_product_get",
        "parameters": [
          {
            "name": "goods_key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "商品 key（来自 search_products）"
          },
          {
            "name": "title",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "商品标题关键词（没有 key 时用）"
          }
        ],
        "responses": {
          "200": {
            "description": "成功"
          }
        }
      }
    },
    "/api/agent/price_history": {
      "post": {
        "tags": [
          "price_history"
        ],
        "summary": "价格走势",
        "description": "查某个商品近 N 天的价格采样与涨跌幅。适合回答「这个涨价了吗」「最近行情怎么样」。",
        "operationId": "price_history",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "goods_key": {
                    "type": "string",
                    "description": "商品 key"
                  },
                  "days": {
                    "type": "integer",
                    "description": "回看天数，默认 30，最大 90"
                  }
                },
                "required": [
                  "goods_key"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "type": "string",
                      "description": "可直接引用给用户的一句话结论"
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "last_scan": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "error": {
                      "type": "string"
                    },
                    "hint": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误"
          },
          "429": {
            "description": "超出速率限制"
          }
        }
      },
      "get": {
        "tags": [
          "price_history"
        ],
        "summary": "价格走势（GET 形式）",
        "operationId": "price_history_get",
        "parameters": [
          {
            "name": "goods_key",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "商品 key"
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "回看天数，默认 30，最大 90"
          }
        ],
        "responses": {
          "200": {
            "description": "成功"
          }
        }
      }
    },
    "/api/agent/market_overview": {
      "post": {
        "tags": [
          "market_overview"
        ],
        "summary": "市场概览",
        "description": "返回全站或指定产品线的市场规模：商品数、店铺数、价格区间、各服务形态的最低价、商品最多的店铺。适合回答「ChatGPT 账号市场什么行情」「哪个形态最划算」。",
        "operationId": "market_overview",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "product_line": {
                    "type": "string",
                    "description": "产品线 id，不传则返回全站",
                    "enum": [
                      "chatgpt",
                      "claude",
                      "gemini",
                      "grok",
                      "coding",
                      "image",
                      "api",
                      "other-ai",
                      "general"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "type": "string",
                      "description": "可直接引用给用户的一句话结论"
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "last_scan": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "error": {
                      "type": "string"
                    },
                    "hint": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误"
          },
          "429": {
            "description": "超出速率限制"
          }
        }
      },
      "get": {
        "tags": [
          "market_overview"
        ],
        "summary": "市场概览（GET 形式）",
        "operationId": "market_overview_get",
        "parameters": [
          {
            "name": "product_line",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "chatgpt",
                "claude",
                "gemini",
                "grok",
                "coding",
                "image",
                "api",
                "other-ai",
                "general"
              ]
            },
            "description": "产品线 id，不传则返回全站"
          }
        ],
        "responses": {
          "200": {
            "description": "成功"
          }
        }
      }
    },
    "/api/agent/list_categories": {
      "post": {
        "tags": [
          "list_categories"
        ],
        "summary": "列出可选维度",
        "description": "返回本站支持的产品线与服务形态清单，以及每个「产品线 × 形态」组合的件数与最低价。用于理解可选空间。",
        "operationId": "list_categories",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "type": "string",
                      "description": "可直接引用给用户的一句话结论"
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "last_scan": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "error": {
                      "type": "string"
                    },
                    "hint": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误"
          },
          "429": {
            "description": "超出速率限制"
          }
        }
      },
      "get": {
        "tags": [
          "list_categories"
        ],
        "summary": "列出可选维度（GET 形式）",
        "operationId": "list_categories_get",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功"
          }
        }
      }
    },
    "/api/agent/find_shops": {
      "post": {
        "tags": [
          "find_shops"
        ],
        "summary": "找店铺",
        "description": "按关键词或产品线查找发卡店铺，返回在售商品数、最低价、销量。",
        "operationId": "find_shops",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "keyword": {
                    "type": "string",
                    "description": "店铺名关键词"
                  },
                  "product_line": {
                    "type": "string",
                    "description": "限定经营该产品线的店铺",
                    "enum": [
                      "chatgpt",
                      "claude",
                      "gemini",
                      "grok",
                      "coding",
                      "image",
                      "api",
                      "other-ai",
                      "general"
                    ]
                  },
                  "limit": {
                    "type": "integer",
                    "description": "返回条数，默认 10，最大 50"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "type": "string",
                      "description": "可直接引用给用户的一句话结论"
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "last_scan": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "error": {
                      "type": "string"
                    },
                    "hint": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误"
          },
          "429": {
            "description": "超出速率限制"
          }
        }
      },
      "get": {
        "tags": [
          "find_shops"
        ],
        "summary": "找店铺（GET 形式）",
        "operationId": "find_shops_get",
        "parameters": [
          {
            "name": "keyword",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "店铺名关键词"
          },
          {
            "name": "product_line",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "chatgpt",
                "claude",
                "gemini",
                "grok",
                "coding",
                "image",
                "api",
                "other-ai",
                "general"
              ]
            },
            "description": "限定经营该产品线的店铺"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "返回条数，默认 10，最大 50"
          }
        ],
        "responses": {
          "200": {
            "description": "成功"
          }
        }
      }
    }
  }
}