{
  "openapi": "3.1.0",
  "info": {
    "title": "浙江文旅指数数据API（草案）",
    "version": "1.0.0-draft",
    "description": "本文档描述未来的数据查询接口。目前仅静态数据快照可用，/api/tourism/v1下所有REST接口尚未实现。鉴权及限流将在接口上线时确定。"
  },
  "servers": [
    {
      "url": "/api/tourism/v1",
      "description": "规划路径，尚未上线"
    }
  ],
  "x-api-status": "planned",
  "paths": {
    "/meta": {
      "get": {
        "summary": "数据版本与覆盖",
        "description": "获取当前数据版本、监测范围、各平台缺失项及可用日期。 此接口尚未实现。",
        "operationId": "travelIndex0",
        "tags": [
          "planned"
        ],
        "x-implementation-status": "planned",
        "parameters": [],
        "responses": {
          "200": {
            "description": "计划响应结构；以下为当前快照生成的示例，不代表线上接口可调用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                },
                "example": {
                  "data": {
                    "component": "zhejiang-tourism-index",
                    "schema_version": "1.0-snapshot",
                    "analysis_date": "2026-10-08",
                    "data_as_of": "2026-10-07",
                    "data_url": "/components/travel-index/data-20261008-4ffc17c02dd3.json",
                    "data_sha256": "304be1fb1a2074571066ccb900c69ab7419e9e6485742613e7bfe6cc5beff1f0",
                    "api_status": "planned",
                    "api_documentation_url": "/travel-index-api.html",
                    "coverage": {
                      "keywords": 39,
                      "expressions": 85,
                      "posts": 667,
                      "comments": 5018,
                      "official_daily_keywords": 38,
                      "audience_source": "douyin",
                      "audience_keywords": 15
                    },
                    "industry_period": {
                      "start": "2026-09-26",
                      "end": "2026-10-04",
                      "available_days": 9
                    },
                    "source_validation_sha256": "8e90b52c9ca43dec968b66370eee5ca1a9679800a34ff5c64898cfdef963eddf",
                    "source_analysis_version": "2.0 category semantic agents"
                  },
                  "meta": {
                    "schema_version": "1.0-draft",
                    "data_as_of": "2026-10-07",
                    "analysis_date": "2026-10-08",
                    "provisional": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "计划：参数缺失或无效"
          },
          "404": {
            "description": "计划：关键词不存在"
          },
          "429": {
            "description": "计划：超出正式接口限流；具体限额尚未确定"
          }
        }
      }
    },
    "/keywords": {
      "get": {
        "summary": "标准关键词列表",
        "description": "列出39个标准关键词及85种表达的映射，可按品类筛选。 此接口尚未实现。",
        "operationId": "travelIndex1",
        "tags": [
          "planned"
        ],
        "x-implementation-status": "planned",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "文档中的四类产品之一",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "美食",
                "住宿",
                "景区",
                "商业街"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "搜索标准词或别名",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "上一页返回的不透明游标；首屏省略",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "分页条数，默认50，最多100",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "计划响应结构；以下为当前快照生成的示例，不代表线上接口可调用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Keyword"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "o01",
                      "name": "千岛湖鱼头",
                      "category": "美食",
                      "aliases": [
                        "千岛湖鱼头",
                        "千岛湖鱼头汤"
                      ],
                      "heat_snapshot": 46.866691779740826,
                      "heat_mask": "douyin+wechat+weibo+xiaohongshu",
                      "sentiment_score": 88.53244697689142,
                      "aesthetic_score": 100,
                      "post_n": 48,
                      "comment_n": 238
                    }
                  ],
                  "meta": {
                    "schema_version": "1.0-draft",
                    "data_as_of": "2026-10-07",
                    "analysis_date": "2026-10-08",
                    "provisional": true
                  },
                  "pagination": {
                    "next_cursor": null,
                    "has_more": false
                  }
                }
              }
            }
          },
          "400": {
            "description": "计划：参数缺失或无效"
          },
          "404": {
            "description": "计划：关键词不存在"
          },
          "429": {
            "description": "计划：超出正式接口限流；具体限额尚未确定"
          }
        }
      }
    },
    "/keywords/{keyword_id}": {
      "get": {
        "summary": "关键词明细",
        "description": "查询一个标准对象的热度快照、舆情、审美、文本样本量和平台覆盖。 此接口尚未实现。",
        "operationId": "travelIndex2",
        "tags": [
          "planned"
        ],
        "x-implementation-status": "planned",
        "parameters": [
          {
            "name": "keyword_id",
            "in": "path",
            "required": true,
            "description": "标准对象ID，例如o01",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "计划响应结构；以下为当前快照生成的示例，不代表线上接口可调用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Keyword"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "sentiment": {
                              "$ref": "#/components/schemas/OpinionSummary"
                            },
                            "aesthetic": {
                              "$ref": "#/components/schemas/OpinionSummary"
                            }
                          }
                        }
                      ]
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "o01",
                    "name": "千岛湖鱼头",
                    "category": "美食",
                    "aliases": [
                      "千岛湖鱼头",
                      "千岛湖鱼头汤"
                    ],
                    "heat_snapshot": 46.866691779740826,
                    "heat_mask": "douyin+wechat+weibo+xiaohongshu",
                    "sentiment_score": 88.53244697689142,
                    "aesthetic_score": 100,
                    "post_n": 48,
                    "comment_n": 238,
                    "sentiment": {
                      "score": 88.53244697689142,
                      "components": {
                        "douyin:post": {
                          "score": 95.83333333333333,
                          "post_n": 12,
                          "text_n": 12
                        },
                        "xiaohongshu:post": {
                          "score": 80,
                          "post_n": 10,
                          "text_n": 10
                        },
                        "weibo:post": {
                          "score": 84.61538461538461,
                          "post_n": 26,
                          "text_n": 26
                        },
                        "douyin:comment": {
                          "score": 91.66666666666667,
                          "post_n": 6,
                          "text_n": 9
                        },
                        "xiaohongshu:comment": {
                          "score": 93.76543209876543,
                          "post_n": 9,
                          "text_n": 66
                        },
                        "weibo:comment": {
                          "score": 82.37179487179488,
                          "post_n": 6,
                          "text_n": 32
                        }
                      },
                      "type_scores": {
                        "post": 86.81623931623932,
                        "comment": 89.26796454574233
                      },
                      "complete_types": true,
                      "sample_text_n": 155,
                      "sample_post_n": 48,
                      "low_sample": false,
                      "provisional": true
                    },
                    "aesthetic": {
                      "score": 100,
                      "components": {
                        "douyin:post": {
                          "score": 100,
                          "post_n": 2,
                          "text_n": 2
                        },
                        "xiaohongshu:post": {
                          "score": 100,
                          "post_n": 2,
                          "text_n": 2
                        },
                        "weibo:post": {
                          "score": 100,
                          "post_n": 4,
                          "text_n": 4
                        },
                        "douyin:comment": {
                          "score": 100,
                          "post_n": 1,
                          "text_n": 1
                        },
                        "xiaohongshu:comment": {
                          "score": 100,
                          "post_n": 2,
                          "text_n": 2
                        },
                        "weibo:comment": {
                          "score": 100,
                          "post_n": 2,
                          "text_n": 12
                        }
                      },
                      "type_scores": {
                        "post": 100,
                        "comment": 100
                      },
                      "complete_types": true,
                      "sample_text_n": 23,
                      "sample_post_n": 13,
                      "low_sample": false,
                      "provisional": true
                    }
                  },
                  "meta": {
                    "schema_version": "1.0-draft",
                    "data_as_of": "2026-10-07",
                    "analysis_date": "2026-10-08",
                    "provisional": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "计划：参数缺失或无效"
          },
          "404": {
            "description": "计划：关键词不存在"
          },
          "429": {
            "description": "计划：超出正式接口限流；具体限额尚未确定"
          }
        }
      }
    },
    "/heat/daily": {
      "get": {
        "summary": "每日热度",
        "description": "按总体、品类或关键词获取日值。计算标尺固定；Y轴缩放属于显示设置。 此接口尚未实现。",
        "operationId": "travelIndex3",
        "tags": [
          "planned"
        ],
        "x-implementation-status": "planned",
        "parameters": [
          {
            "name": "scope",
            "in": "query",
            "description": "查询层级",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "overall",
                "category",
                "keyword"
              ],
              "default": "overall"
            }
          },
          {
            "name": "keyword_ids",
            "in": "query",
            "description": "scope=keyword时提供，以逗号分隔，例如o01,o03",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "文档中的四类产品之一",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "美食",
                "住宿",
                "景区",
                "商业街"
              ]
            }
          },
          {
            "name": "platform",
            "in": "query",
            "description": "综合日度或官方平台；微博当前暂缺",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "combined",
                "wechat",
                "douyin",
                "weibo"
              ],
              "default": "combined"
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "description": "开始日期，YYYY-MM-DD",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "description": "结束日期，YYYY-MM-DD",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "计划响应结构；以下为当前快照生成的示例，不代表线上接口可调用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/HeatSeries"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                },
                "example": {
                  "data": {
                    "scope": "overall",
                    "platform": "combined",
                    "points": [
                      {
                        "date": "2026-09-26",
                        "score": 45.03470104146567,
                        "rebased": 100
                      },
                      {
                        "date": "2026-09-27",
                        "score": 44.46850667604801,
                        "rebased": 98.74275980005655
                      },
                      {
                        "date": "2026-09-28",
                        "score": 43.76704852684506,
                        "rebased": 97.18516502762299
                      },
                      {
                        "date": "2026-09-29",
                        "score": 43.96950382842549,
                        "rebased": 97.6347190313101
                      },
                      {
                        "date": "2026-09-30",
                        "score": 44.67346908393533,
                        "rebased": 99.19788085814596
                      },
                      {
                        "date": "2026-10-01",
                        "score": 46.12099634270028,
                        "rebased": 102.4121294826281
                      },
                      {
                        "date": "2026-10-02",
                        "score": 46.5650193780763,
                        "rebased": 103.3980870333781
                      },
                      {
                        "date": "2026-10-03",
                        "score": 46.317896906134486,
                        "rebased": 102.84934913520868
                      },
                      {
                        "date": "2026-10-04",
                        "score": 45.79813762902637,
                        "rebased": 101.69521850907319
                      }
                    ]
                  },
                  "meta": {
                    "schema_version": "1.0-draft",
                    "data_as_of": "2026-10-07",
                    "analysis_date": "2026-10-08",
                    "provisional": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "计划：参数缺失或无效"
          },
          "404": {
            "description": "计划：关键词不存在"
          },
          "429": {
            "description": "计划：超出正式接口限流；具体限额尚未确定"
          }
        }
      }
    },
    "/opinions/summary": {
      "get": {
        "summary": "舆情与审美汇总",
        "description": "返回一个关键词已计算的综合得分、分项、标签计数与少样本标记。综合分同时考虑正文与评论；label_counts另按label_counts_scope说明计数范围。 此接口尚未实现。",
        "operationId": "travelIndex4",
        "tags": [
          "planned"
        ],
        "x-implementation-status": "planned",
        "parameters": [
          {
            "name": "keyword_id",
            "in": "query",
            "description": "标准关键词ID，例如o01；同义表达通过关键词列表映射",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "metric",
            "in": "query",
            "description": "选择舆情或审美",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "sentiment",
                "aesthetic"
              ],
              "default": "sentiment"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "计划响应结构；以下为当前快照生成的示例，不代表线上接口可调用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/OpinionSummary"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "keyword_id": {
                              "type": "string"
                            },
                            "metric": {
                              "type": "string",
                              "enum": [
                                "sentiment",
                                "aesthetic"
                              ]
                            },
                            "label_counts_scope": {
                              "type": "string",
                              "enum": [
                                "comment"
                              ]
                            }
                          }
                        }
                      ]
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                },
                "example": {
                  "data": {
                    "keyword_id": "o01",
                    "metric": "sentiment",
                    "score": 88.53244697689142,
                    "components": {
                      "douyin:post": {
                        "score": 95.83333333333333,
                        "post_n": 12,
                        "text_n": 12
                      },
                      "xiaohongshu:post": {
                        "score": 80,
                        "post_n": 10,
                        "text_n": 10
                      },
                      "weibo:post": {
                        "score": 84.61538461538461,
                        "post_n": 26,
                        "text_n": 26
                      },
                      "douyin:comment": {
                        "score": 91.66666666666667,
                        "post_n": 6,
                        "text_n": 9
                      },
                      "xiaohongshu:comment": {
                        "score": 93.76543209876543,
                        "post_n": 9,
                        "text_n": 66
                      },
                      "weibo:comment": {
                        "score": 82.37179487179488,
                        "post_n": 6,
                        "text_n": 32
                      }
                    },
                    "type_scores": {
                      "post": 86.81623931623932,
                      "comment": 89.26796454574233
                    },
                    "complete_types": true,
                    "sample_text_n": 155,
                    "sample_post_n": 48,
                    "low_sample": false,
                    "provisional": true,
                    "label_counts": {
                      "excluded": 55,
                      "positive": 84,
                      "unknown": 76,
                      "neutral": 18,
                      "negative": 3,
                      "mixed": 2
                    },
                    "label_counts_scope": "comment"
                  },
                  "meta": {
                    "schema_version": "1.0-draft",
                    "data_as_of": "2026-10-07",
                    "analysis_date": "2026-10-08",
                    "provisional": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "计划：参数缺失或无效"
          },
          "404": {
            "description": "计划：关键词不存在"
          },
          "429": {
            "description": "计划：超出正式接口限流；具体限额尚未确定"
          }
        }
      }
    },
    "/aspects": {
      "get": {
        "summary": "品类维度与方面情感",
        "description": "返回该品类发现的完整维度字典；若提供keyword_id，同时返回对应关键词的方面统计。 此接口尚未实现。",
        "operationId": "travelIndex5",
        "tags": [
          "planned"
        ],
        "x-implementation-status": "planned",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "文档中的四类产品之一",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "美食",
                "住宿",
                "景区",
                "商业街"
              ]
            }
          },
          {
            "name": "keyword_id",
            "in": "query",
            "description": "标准关键词ID，例如o01；同义表达通过关键词列表映射",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "aesthetic_only",
            "in": "query",
            "description": "仅返回审美维度",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "计划响应结构；以下为当前快照生成的示例，不代表线上接口可调用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AspectResponse"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                },
                "example": {
                  "data": {
                    "category": "美食",
                    "keyword_id": "o01",
                    "dimensions": [
                      {
                        "dimension_id": "f01",
                        "category": "美食",
                        "name": "味道与调味",
                        "definition": "标准食物的鲜香、甜咸辣酸、腥味、油腻感、汤汁风味及总体好吃程度；不包含别道菜的评价。",
                        "aesthetic": false,
                        "mentioned_text_n": 97,
                        "polarity_counts": {
                          "positive": 90,
                          "negative": 3,
                          "neutral": 3,
                          "mixed": 1
                        },
                        "score": 94.84536082474227
                      },
                      {
                        "dimension_id": "f02",
                        "category": "美食",
                        "name": "口感与质地",
                        "definition": "食物软糯、脆酥、嫩滑、肥瘦、皮馅厚薄和嚼感等入口质地。",
                        "aesthetic": false,
                        "mentioned_text_n": 22,
                        "polarity_counts": {
                          "positive": 22,
                          "negative": 0,
                          "neutral": 0,
                          "mixed": 0
                        },
                        "score": 100
                      },
                      {
                        "dimension_id": "f03",
                        "category": "美食",
                        "name": "食材新鲜与品质",
                        "definition": "原料鲜活、选材、肉膏饱满、有机/品质主张及加工后品质；只记录原文主张，不核实来源事实。",
                        "aesthetic": false,
                        "mentioned_text_n": 11,
                        "polarity_counts": {
                          "positive": 11,
                          "negative": 0,
                          "neutral": 0,
                          "mixed": 0
                        },
                        "score": 100
                      },
                      {
                        "dimension_id": "f04",
                        "category": "美食",
                        "name": "正宗传承与家乡记忆",
                        "definition": "地域风味是否正宗、手工传统与工业化差异、童年家乡味和节俗关联。",
                        "aesthetic": false,
                        "mentioned_text_n": 2,
                        "polarity_counts": {
                          "positive": 1,
                          "negative": 0,
                          "neutral": 1,
                          "mixed": 0
                        },
                        "score": 75
                      },
                      {
                        "dimension_id": "f05",
                        "category": "美食",
                        "name": "价格与性价比",
                        "definition": "标准食物售价、优惠、贵便宜与价值感；不将整座城市物价直接归给食物。",
                        "aesthetic": false,
                        "mentioned_text_n": 7,
                        "polarity_counts": {
                          "positive": 5,
                          "negative": 1,
                          "neutral": 1,
                          "mixed": 0
                        },
                        "score": 78.57142857142857
                      },
                      {
                        "dimension_id": "f06",
                        "category": "美食",
                        "name": "份量与规格",
                        "definition": "标准食物个头、数量、肉量、分量及是否足够吃；只谈大小不自动正负。",
                        "aesthetic": false,
                        "mentioned_text_n": 10,
                        "polarity_counts": {
                          "positive": 10,
                          "negative": 0,
                          "neutral": 0,
                          "mixed": 0
                        },
                        "score": 100
                      },
                      {
                        "dimension_id": "f07",
                        "category": "美食",
                        "name": "制作方法与便利性",
                        "definition": "烹饪、手工包制、调料处理、速食加热、制作难易和食用方法；厨师人物赞美不算食物评价。",
                        "aesthetic": false,
                        "mentioned_text_n": 1,
                        "polarity_counts": {
                          "positive": 0,
                          "negative": 0,
                          "neutral": 1,
                          "mixed": 0
                        },
                        "score": 50
                      },
                      {
                        "dimension_id": "f08",
                        "category": "美食",
                        "name": "保存运输与鲜活保持",
                        "definition": "冷藏暂养、死亡损耗、到货状态、包装说明、外送保温等保存运输体验与建议。",
                        "aesthetic": false,
                        "mentioned_text_n": 0,
                        "polarity_counts": {
                          "positive": 0,
                          "negative": 0,
                          "neutral": 0,
                          "mixed": 0
                        },
                        "score": null
                      },
                      {
                        "dimension_id": "f09",
                        "category": "美食",
                        "name": "食品安全与健康适配",
                        "definition": "食用不适、腐败与卫生担忧、添加剂、消化/减脂适配及安全提醒；UGC健康说法未经核实。",
                        "aesthetic": false,
                        "mentioned_text_n": 1,
                        "polarity_counts": {
                          "positive": 0,
                          "negative": 1,
                          "neutral": 0,
                          "mixed": 0
                        },
                        "score": 0
                      },
                      {
                        "dimension_id": "f10",
                        "category": "美食",
                        "name": "食物色泽与视觉食欲",
                        "definition": "食物汤色、色泽搭配与外观引发的食欲；只谈人物、摄影技术或餐厅装修的评价排除。",
                        "aesthetic": true,
                        "mentioned_text_n": 30,
                        "polarity_counts": {
                          "positive": 22,
                          "negative": 0,
                          "neutral": 8,
                          "mixed": 0
                        },
                        "score": 86.66666666666667
                      },
                      {
                        "dimension_id": "f11",
                        "category": "美食",
                        "name": "造型摆盘与精致感",
                        "definition": "食物外形、完整度、褶纹、陈列摆盘及精致观感；不是餐厅建筑或家具审美。",
                        "aesthetic": true,
                        "mentioned_text_n": 4,
                        "polarity_counts": {
                          "positive": 4,
                          "negative": 0,
                          "neutral": 0,
                          "mixed": 0
                        },
                        "score": 100
                      },
                      {
                        "dimension_id": "f12",
                        "category": "美食",
                        "name": "食用意愿与接受度",
                        "definition": "想吃、回购、偏爱或拒绝、不敢尝试、食用心理和伦理接受度；没有明确偏好的未尝过为中性。",
                        "aesthetic": false,
                        "mentioned_text_n": 12,
                        "polarity_counts": {
                          "positive": 8,
                          "negative": 0,
                          "neutral": 4,
                          "mixed": 0
                        },
                        "score": 83.33333333333333
                      },
                      {
                        "dimension_id": "f13",
                        "category": "美食",
                        "name": "购买渠道与获得便利",
                        "definition": "标准食物哪里能买、店名地址、配送、真空包装、供货可得与购买方便性；城市旅游交通排除。",
                        "aesthetic": false,
                        "mentioned_text_n": 17,
                        "polarity_counts": {
                          "positive": 1,
                          "negative": 1,
                          "neutral": 15,
                          "mixed": 0
                        },
                        "score": 50
                      },
                      {
                        "dimension_id": "f14",
                        "category": "美食",
                        "name": "宣传与推荐可信度",
                        "definition": "针对标准食物推荐、排名、广告水军或体验落差的可信度评价；仅骂作者分析或拍摄不算食物评价。",
                        "aesthetic": false,
                        "mentioned_text_n": 6,
                        "polarity_counts": {
                          "positive": 2,
                          "negative": 4,
                          "neutral": 0,
                          "mixed": 0
                        },
                        "score": 33.333333333333336
                      }
                    ]
                  },
                  "meta": {
                    "schema_version": "1.0-draft",
                    "data_as_of": "2026-10-07",
                    "analysis_date": "2026-10-08",
                    "provisional": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "计划：参数缺失或无效"
          },
          "404": {
            "description": "计划：关键词不存在"
          },
          "429": {
            "description": "计划：超出正式接口限流；具体限额尚未确定"
          }
        }
      }
    },
    "/evidence": {
      "get": {
        "summary": "原文与方面证据",
        "description": "查询帖子正文及一级评论的方面证据，保留来源和父帖关联；多维度会返回同一文本的多个证据片段。 此接口尚未实现。",
        "operationId": "travelIndex6",
        "tags": [
          "planned"
        ],
        "x-implementation-status": "planned",
        "parameters": [
          {
            "name": "keyword_id",
            "in": "query",
            "description": "标准关键词ID，例如o01；同义表达通过关键词列表映射",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "文档中的四类产品之一",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "美食",
                "住宿",
                "景区",
                "商业街"
              ]
            }
          },
          {
            "name": "dimension_id",
            "in": "query",
            "description": "必须结合品类使用该品类维度ID",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "label",
            "in": "query",
            "description": "方面情感标签",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "positive",
                "negative",
                "neutral",
                "mixed",
                "unknown",
                "excluded"
              ]
            }
          },
          {
            "name": "platform",
            "in": "query",
            "description": "原文平台",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "douyin",
                "xiaohongshu",
                "weibo"
              ]
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "上一页返回的不透明游标；首屏省略",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "分页条数，默认50，最多100",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "计划响应结构；以下为当前快照生成的示例，不代表线上接口可调用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Evidence"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "fragment_id": "food:1:0",
                      "document_id": "douyin:7687905924250354097:post:o06",
                      "post_key": "douyin:7687905924250354097",
                      "object": "杭州东坡肉",
                      "category": "美食",
                      "platform": "douyin",
                      "kind": "post",
                      "dimension_id": "f01",
                      "aspect": "味道与调味",
                      "aesthetic": false,
                      "label": "positive",
                      "quote": "东坡肉香拽了",
                      "date_raw": "9月21日",
                      "url": "https://www.douyin.com/video/7687905924250354097",
                      "analysis_method": "subagent_semantic",
                      "reason": "",
                      "text": "西湖边好吃好玩的创意杭帮菜，酥皮番茄牛腩和东坡肉香拽了！#杭帮菜 #杭州美食 #杭州旅游 #烟火气小店 #东坡肉",
                      "truncated": false
                    }
                  ],
                  "meta": {
                    "schema_version": "1.0-draft",
                    "data_as_of": "2026-10-07",
                    "analysis_date": "2026-10-08",
                    "provisional": true
                  },
                  "pagination": {
                    "next_cursor": null,
                    "has_more": false
                  }
                }
              }
            }
          },
          "400": {
            "description": "计划：参数缺失或无效"
          },
          "404": {
            "description": "计划：关键词不存在"
          },
          "429": {
            "description": "计划：超出正式接口限流；具体限额尚未确定"
          }
        }
      }
    },
    "/audience": {
      "get": {
        "summary": "人群画像",
        "description": "按标准关键词返回各实际查询表达的人群画像。当前仅有抖音画像，不平均或累加别名占比。 此接口尚未实现。",
        "operationId": "travelIndex7",
        "tags": [
          "planned"
        ],
        "x-implementation-status": "planned",
        "parameters": [
          {
            "name": "keyword_id",
            "in": "query",
            "description": "标准关键词ID，例如o01；同义表达通过关键词列表映射",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "description": "画像来源；尚无数据的平台返回availability=pending",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "douyin",
                "wechat",
                "xiaohongshu",
                "weibo"
              ],
              "default": "douyin"
            }
          },
          {
            "name": "query",
            "in": "query",
            "description": "可选：限定实际查询表达；省略则返回该标准关键词所有画像",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "计划响应结构；以下为当前快照生成的示例，不代表线上接口可调用。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AudienceResponse"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                },
                "example": {
                  "data": {
                    "keyword_id": "o01",
                    "availability": "available",
                    "profiles": [
                      {
                        "platform": "douyin",
                        "category": "美食",
                        "object": "千岛湖鱼头",
                        "query": "千岛湖鱼头",
                        "returned_keyword": "千岛湖鱼头",
                        "relationship": "原词",
                        "period_start": "2026-09-20",
                        "period_end": "2026-09-29",
                        "captured_date": "2026-10-01",
                        "scope_note": "",
                        "distributions": {
                          "gender": [
                            {
                              "name": "男性",
                              "share_percent": 58,
                              "share_raw": "58%",
                              "tgi": 121,
                              "tgi_raw": "121",
                              "order": 1
                            },
                            {
                              "name": "女性",
                              "share_percent": 42,
                              "share_raw": "42%",
                              "tgi": 81,
                              "tgi_raw": "81",
                              "order": 2
                            }
                          ],
                          "age": [
                            {
                              "name": "18-23岁",
                              "share_percent": 9.81,
                              "share_raw": "9.81%",
                              "tgi": 86.82,
                              "tgi_raw": "86.82",
                              "order": 1
                            },
                            {
                              "name": "24-30岁",
                              "share_percent": 16.29,
                              "share_raw": "16.29%",
                              "tgi": 126.73,
                              "tgi_raw": "126.73",
                              "order": 2
                            },
                            {
                              "name": "31-40岁",
                              "share_percent": 31.14,
                              "share_raw": "31.14%",
                              "tgi": 96.04,
                              "tgi_raw": "96.04",
                              "order": 3
                            },
                            {
                              "name": "41-50岁",
                              "share_percent": 19.81,
                              "share_raw": "19.81%",
                              "tgi": 90.5,
                              "tgi_raw": "90.50",
                              "order": 4
                            },
                            {
                              "name": "51岁+",
                              "share_percent": 22.95,
                              "share_raw": "22.95%",
                              "tgi": 106.57,
                              "tgi_raw": "106.57",
                              "order": 5
                            }
                          ],
                          "city": [
                            {
                              "name": "杭州",
                              "share_percent": 23.49,
                              "share_raw": "23.49%",
                              "tgi": 1735,
                              "tgi_raw": "1735.00",
                              "order": 1
                            },
                            {
                              "name": "上海",
                              "share_percent": 16.27,
                              "share_raw": "16.27%",
                              "tgi": 833,
                              "tgi_raw": "833.00",
                              "order": 2
                            },
                            {
                              "name": "金华",
                              "share_percent": 2.88,
                              "share_raw": "2.88%",
                              "tgi": 337,
                              "tgi_raw": "337.00",
                              "order": 3
                            },
                            {
                              "name": "苏州",
                              "share_percent": 2.67,
                              "share_raw": "2.67%",
                              "tgi": 163,
                              "tgi_raw": "163.00",
                              "order": 4
                            },
                            {
                              "name": "宁波",
                              "share_percent": 2.55,
                              "share_raw": "2.55%",
                              "tgi": 270,
                              "tgi_raw": "270.00",
                              "order": 5
                            }
                          ],
                          "interest": [
                            {
                              "name": "时尚",
                              "share_percent": 17.62,
                              "share_raw": "17.62%",
                              "tgi": 127.17,
                              "tgi_raw": "127.17",
                              "order": 1
                            },
                            {
                              "name": "美食",
                              "share_percent": 11.87,
                              "share_raw": "11.87%",
                              "tgi": 132.07,
                              "tgi_raw": "132.07",
                              "order": 2
                            },
                            {
                              "name": "旅行",
                              "share_percent": 6.16,
                              "share_raw": "6.16%",
                              "tgi": 171.47,
                              "tgi_raw": "171.47",
                              "order": 3
                            },
                            {
                              "name": "文化教育",
                              "share_percent": 5.77,
                              "share_raw": "5.77%",
                              "tgi": 100.66,
                              "tgi_raw": "100.66",
                              "order": 4
                            },
                            {
                              "name": "运动",
                              "share_percent": 5.73,
                              "share_raw": "5.73%",
                              "tgi": 168.23,
                              "tgi_raw": "168.23",
                              "order": 5
                            }
                          ]
                        }
                      }
                    ]
                  },
                  "meta": {
                    "schema_version": "1.0-draft",
                    "data_as_of": "2026-10-07",
                    "analysis_date": "2026-10-08",
                    "provisional": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "计划：参数缺失或无效"
          },
          "404": {
            "description": "计划：关键词不存在"
          },
          "429": {
            "description": "计划：超出正式接口限流；具体限额尚未确定"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Keyword": {
        "type": "object",
        "required": [
          "id",
          "name",
          "category",
          "aliases"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "标准对象ID；当前为o01至o39"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "美食",
              "住宿",
              "景区",
              "商业街"
            ]
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "heat_snapshot": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 100
          },
          "heat_mask": {
            "type": "string",
            "description": "参与快照的平台组合；不同组合不直接排名"
          },
          "sentiment_score": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 100
          },
          "aesthetic_score": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 100
          },
          "post_n": {
            "type": "integer",
            "minimum": 0
          },
          "comment_n": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "HeatPoint": {
        "type": "object",
        "required": [
          "date",
          "score"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "score": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 100
          },
          "rebased": {
            "type": [
              "number",
              "null"
            ],
            "description": "首日=100的重设基准值，只用于综合总体走势；数值可超过100"
          },
          "missing_reason": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "OpinionSummary": {
        "type": "object",
        "properties": {
          "score": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 100
          },
          "label_counts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            }
          },
          "sample_text_n": {
            "type": "integer",
            "minimum": 0
          },
          "sample_post_n": {
            "type": "integer",
            "minimum": 0
          },
          "low_sample": {
            "type": "boolean"
          },
          "complete_types": {
            "type": "boolean",
            "description": "有效正文与评论是否同时覆盖"
          },
          "components": {
            "type": "object",
            "description": "按平台和文本类型保留分值、文本数、帖子数"
          }
        }
      },
      "Dimension": {
        "type": "object",
        "required": [
          "dimension_id",
          "category",
          "name",
          "definition",
          "aesthetic"
        ],
        "properties": {
          "dimension_id": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "美食",
              "住宿",
              "景区",
              "商业街"
            ]
          },
          "name": {
            "type": "string"
          },
          "definition": {
            "type": "string"
          },
          "aesthetic": {
            "type": "boolean"
          },
          "mentioned_text_n": {
            "type": "integer",
            "minimum": 0
          },
          "polarity_counts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            }
          },
          "score": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "Evidence": {
        "type": "object",
        "required": [
          "document_id",
          "post_key",
          "object",
          "category",
          "dimension_id",
          "quote",
          "label"
        ],
        "properties": {
          "document_id": {
            "type": "string",
            "description": "不透明对象×文本ID，不应自行拆分"
          },
          "post_key": {
            "type": "string",
            "description": "父帖关联键"
          },
          "object": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "美食",
              "住宿",
              "景区",
              "商业街"
            ]
          },
          "platform": {
            "type": "string",
            "enum": [
              "douyin",
              "xiaohongshu",
              "weibo"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "post",
              "comment"
            ]
          },
          "dimension_id": {
            "type": "string"
          },
          "aspect": {
            "type": "string"
          },
          "aesthetic": {
            "type": "boolean"
          },
          "quote": {
            "type": "string",
            "description": "原文连续片段"
          },
          "text": {
            "type": "string",
            "description": "采集到的完整可见文本，可能有截断"
          },
          "label": {
            "type": "string",
            "enum": [
              "positive",
              "negative",
              "neutral",
              "mixed",
              "unknown",
              "excluded"
            ]
          },
          "date_raw": {
            "type": [
              "string",
              "null"
            ],
            "description": "来源显示的原始时间，不保证可解析成日期"
          },
          "url": {
            "type": [
              "string",
              "null"
            ]
          },
          "truncated": {
            "type": "boolean"
          }
        }
      },
      "AudienceRow": {
        "type": "object",
        "required": [
          "name",
          "share_percent",
          "share_raw",
          "tgi",
          "order"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "share_percent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "share_raw": {
            "type": "string",
            "description": "含百分号的原报占比，保留显示精度"
          },
          "tgi": {
            "type": "number",
            "minimum": 0,
            "description": "平台原报TGI，允许大于100，不是人数"
          },
          "tgi_raw": {
            "type": "string"
          },
          "order": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "AudienceProfile": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string",
            "enum": [
              "douyin",
              "wechat",
              "xiaohongshu",
              "weibo"
            ]
          },
          "object": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "美食",
              "住宿",
              "景区",
              "商业街"
            ]
          },
          "query": {
            "type": "string"
          },
          "returned_keyword": {
            "type": "string"
          },
          "relationship": {
            "type": "string"
          },
          "period_start": {
            "type": "string",
            "format": "date"
          },
          "period_end": {
            "type": "string",
            "format": "date"
          },
          "captured_date": {
            "type": "string",
            "format": "date"
          },
          "scope_note": {
            "type": "string"
          },
          "distributions": {
            "type": "object",
            "properties": {
              "gender": {
                "type": "array",
                "maxItems": 2,
                "items": {
                  "$ref": "#/components/schemas/AudienceRow"
                }
              },
              "age": {
                "type": "array",
                "maxItems": 5,
                "items": {
                  "$ref": "#/components/schemas/AudienceRow"
                }
              },
              "city": {
                "type": "array",
                "maxItems": 5,
                "items": {
                  "$ref": "#/components/schemas/AudienceRow"
                }
              },
              "interest": {
                "type": "array",
                "maxItems": 5,
                "items": {
                  "$ref": "#/components/schemas/AudienceRow"
                }
              }
            }
          }
        }
      },
      "ResponseMeta": {
        "type": "object",
        "required": [
          "schema_version",
          "data_as_of",
          "analysis_date",
          "provisional"
        ],
        "properties": {
          "schema_version": {
            "type": "string"
          },
          "data_as_of": {
            "type": "string",
            "format": "date"
          },
          "analysis_date": {
            "type": "string",
            "format": "date"
          },
          "provisional": {
            "type": "boolean"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "required": [
          "next_cursor",
          "has_more"
        ],
        "properties": {
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "has_more": {
            "type": "boolean"
          }
        }
      },
      "HeatSeries": {
        "type": "object",
        "required": [
          "scope",
          "platform",
          "points"
        ],
        "properties": {
          "scope": {
            "type": "string",
            "enum": [
              "overall",
              "category",
              "keyword"
            ]
          },
          "platform": {
            "type": "string",
            "enum": [
              "combined",
              "wechat",
              "douyin",
              "weibo"
            ]
          },
          "keyword_id": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "美食",
              "住宿",
              "景区",
              "商业街"
            ]
          },
          "points": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HeatPoint"
            }
          }
        }
      },
      "AspectResponse": {
        "type": "object",
        "required": [
          "category",
          "dimensions"
        ],
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "美食",
              "住宿",
              "景区",
              "商业街"
            ]
          },
          "keyword_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "dimensions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Dimension"
            }
          }
        }
      },
      "AudienceResponse": {
        "type": "object",
        "required": [
          "keyword_id",
          "availability",
          "profiles"
        ],
        "properties": {
          "keyword_id": {
            "type": "string"
          },
          "availability": {
            "type": "string",
            "enum": [
              "available",
              "pending",
              "no_data"
            ]
          },
          "profiles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AudienceProfile"
            }
          }
        }
      }
    }
  }
}
