{
  "openapi": "3.0.1",
  "info": {
    "title": "潮向 TrendFlow Open API",
    "description": "多平台实时热搜与跨端事件洞察引擎开放数据接口 (TrendFlow Open API)。支持 27+ 权威信源秒级热搜、跨平台事件聚类、60秒早报与历史热搜快照回溯。",
    "version": "v1.0.0",
    "contact": {
      "name": "潮向 TrendFlow 团队",
      "url": "https://hot.ikaicai.cn/",
      "email": "support@ikaicai.cn"
    }
  },
  "servers": [
    {
      "url": "https://hot.ikaicai.cn",
      "description": "生产环境正式接入点"
    }
  ],
  "paths": {
    "/api/boards": {
      "get": {
        "summary": "获取 27+ 权威热搜实时榜单",
        "description": "返回包含微博、知乎、百度、抖音、B站、36氪、IT之家、少数派、掘金、GitHub 等所有实时热搜榜单的结构化数据。支持 category 分类过滤，响应同时包含 boards 与 data 字段。",
        "operationId": "getLiveBoards",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "分类筛选: all(全部), tech(科技), entertainment(文娱), community(社区), finance(财经), developer(开发者), global / international(国际)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回热搜榜单列表",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BoardsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/events": {
      "get": {
        "summary": "获取跨平台聚合大事件",
        "description": "通过 NLP 聚类算法将分散在微博、知乎、百度等多端的同类突发事件整合为单一事件簇，并计算跨端综合声量。",
        "operationId": "getCrossPlatformEvents",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "返回事件数量，默认 50",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "sortBy",
            "in": "query",
            "required": false,
            "description": "排序方式: hot(综合热度), platforms(跨端数量), recent(最近更新)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回跨端聚合事件",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-news": {
      "get": {
        "summary": "获取今日 60 秒新闻早报 (主端点)",
        "description": "返回包含国内外重点要闻、科技前沿、财经金融、国际焦点四个象限结构化摘要与晨语历史今天。官方推荐使用的标准接口。",
        "operationId": "getDailyNews",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": false,
            "description": "查询指定日期的早报 (格式: YYYY-MM-DD)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回早报数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DailyDigestResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/daily-digest": {
      "get": {
        "deprecated": true,
        "summary": "获取今日 60 秒新闻早报 (兼容旧端点，已废弃)",
        "description": "已废弃别名端点。请在所有新系统中使用 /api/daily-news。返回结构与 /api/daily-news 完全一致。",
        "operationId": "getDailyDigest",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": false,
            "description": "查询指定日期的早报 (格式: YYYY-MM-DD)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回早报数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DailyDigestResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/timeline": {
      "get": {
        "summary": "获取多平台实时快讯流水线",
        "description": "按时间倒序排列的秒级多平台突发热点流，标明平台、热度与首发时间。",
        "operationId": "getRealtimeTimeline",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "分类过滤 (all, tech, entertainment, community, finance, developer, global)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "返回快讯条数，默认 40，最大 100",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回快讯时间线",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimelineResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/history": {
      "get": {
        "summary": "历史热搜快照回溯与比对",
        "description": "根据指定日期回溯当时的多平台热榜快照，支持比对今日热度变动与仍在榜状态。",
        "operationId": "getHistoricalSnapshot",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": true,
            "description": "历史日期 (格式: YYYY-MM-DD)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "description": "指定平台 ID (如 weibo, zhihu, baidu)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "compareToday",
            "in": "query",
            "required": false,
            "description": "是否计算与今日的热度及排名对比",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回历史快照及比对数据"
          }
        }
      }
    },
    "/api/history/dates": {
      "get": {
        "summary": "获取所有可供回溯的历史快照日期列表",
        "description": "返回数据库中已留存快照的全部历史日期列表。",
        "operationId": "getHistoricalDates",
        "responses": {
          "200": {
            "description": "成功返回可用日期数组"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BoardsResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "isLive": { "type": "boolean" },
          "updatedAt": { "type": "string" },
          "totalBoards": { "type": "integer" },
          "boards": {
            "type": "array",
            "description": "热搜榜单数组",
            "items": {
              "$ref": "#/components/schemas/Board"
            }
          },
          "data": {
            "type": "array",
            "description": "向后兼容的榜单别名字段",
            "items": {
              "$ref": "#/components/schemas/Board"
            }
          }
        },
        "required": ["success", "boards"]
      },
      "Board": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "title": { "type": "string" },
          "subTitle": { "type": "string" },
          "category": { "type": "string" },
          "icon": { "type": "string" },
          "url": { "type": "string" },
          "updateTime": { "type": "string" },
          "lastSuccessUpdate": { "type": "string" },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BoardItem"
            }
          }
        },
        "required": ["id", "name", "items"]
      },
      "BoardItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "rank": { "type": "integer" },
          "title": { "type": "string" },
          "hotScore": { "type": "string" },
          "url": { "type": "string" },
          "tagLabel": { "type": "string" }
        },
        "required": ["rank", "title"]
      },
      "EventsResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "count": { "type": "integer" },
          "updatedAt": { "type": "string" },
          "events": { "type": "array" }
        },
        "required": ["success", "events"]
      },
      "DailyDigestResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "isLive": { "type": "boolean" },
          "digest": {
            "type": "object",
            "properties": {
              "date": { "type": "string" },
              "lunarDate": { "type": "string" },
              "weekday": { "type": "string" },
              "quote": { "type": "object" },
              "sections": { "type": "array" }
            }
          }
        },
        "required": ["success", "digest"]
      },
      "TimelineResponse": {
        "type": "object",
        "properties": {
          "code": { "type": "integer" },
          "status": { "type": "string" },
          "total": { "type": "integer" },
          "items": { "type": "array" }
        },
        "required": ["status", "items"]
      }
    }
  }
}