每周热点动态

一个本地运行的热点洞察工具。本质是把「公开热榜话题文本」当作原材料，按地理与品类维度做聚合，帮营销决策看清「哪里、什么品类、被谁关注」。

核心约束：只聚合公开话题文本，不采集任何个人数据。性别是品类属性代理，不是真实用户性别。视频号无公开热榜接口，仅由演示数据覆盖并明确标注。

适用场景

区域营销选题：某省/某市近期哪类话题最热
品类对比：美食、穿搭、科技数码等品类的热度与城市分布
性别偏好趋势：某品类更偏男性还是女性关注（代理口径）
平台差异：抖音/小红书/微博/头条等平台的话题分布
每周热点复盘：近 7 天趋势曲线与每类 TOP3

文件结构

| 文件 | 角色 | |---|---| | core.py | 核心引擎：分类、地理归属、性别拆分、SQLite 存储、所有聚合函数 | | server.py | 后端：stdlib http.server，10 个 API 路由，启动即建库+播种 | | index.html | 前端：原生 JS 仪表盘，6 个筛选控件 + 7 个可视化面板 + 详情弹窗 | | sample_data.py | 演示种子：27 品类 × 10 模板 × 17 城市 × 7 天全交叉 | | fetchers.py | 实时接入：抖音/小红书/头条/微博 best-effort 拉取，失败回退演示 | | data.db | 运行时生成的 SQLite，不打包，首次启动自动创建 |

运行方式

复制本目录下全部文件（除 data.db）到一个工作目录
在该目录执行 python server.py（Windows 可用 C:\Users\cheng\.workbuddy\binaries\python\versions\3.13.12\python.exe server.py）
浏览器打开 http://127.0.0.1:8000

无需 pip install，纯标准库。首次启动若库为空会写入 7 天演示数据，并 best-effort 尝试拉取今日实时热榜覆盖当日（成功则页面标注 source: live，否则 source: sample）。

筛选控件

地区（省）、城市（随省联动）、分类（品类）、时间窗（天数）、平台、性别（全部/男/女）。所有聚合接口都接收这套参数。

API 路由

后端统一前缀 /api。公共参数：province、city、category、platform、days、gender、title（详情用）。

| 路由 | 说明 | 关键返回 | |---|---|---| | /api/status | 元数据 | latest(最近日期)、source(live/sample)、provinces、categories、platforms | | /api/cities | 城市列表 | 有 province 则返回该省城市，否则返回全部可识别城市 | | /api/rank | 话题 TOP20 | 标题聚合热度排行（受 gender 影响） | | /api/dist | 品类分布 | 各品类热度占比 | | /api/province_totals | 省份 TOP15 | 各省热度汇总 | | /api/city_totals | 城市 TOP15 | 各城市热度汇总（含归属省） | | /api/gender | 性别代理 | [{gender:女,heat},{gender:男,heat}] | | /api/trend | 时间趋势 | 按日期的热度曲线，前端用 SVG 绘制 | | /api/cat_top | 每类 TOP3 | 每个品类返回热度前三话题 | | /api/detail | 话题详情 | 按 title 返回最新一条 + 内容（点击排行/分类条目触发） |

数据库 Schema

表 snapshots，列：id, date, title, heat, source, url, content, category, province, city, platform, g_male, g_female。

g_male / g_female 由 gender_split(heat, category) 按品类女性占比拆出，用于性别维度的聚合与展示。init_db() 会在缺少任一关键列时 DROP TABLE 重建，所以改 schema 后重启即可，无需手动删库。

合规边界（务必保留）

数据来源仅为公开热榜的话题文本与平台热度值，不含任何用户级内容（符合个人信息保护法的最小化原则）。
地理归属靠标题中的地名关键词匹配，不是基于个人位置数据。
性别是「品类女性占比」的统计代理，页面必须标注为模拟口径，不得表述为真实用户性别分布。
视频号（微信）无公开热榜接口，不实现抓取，仅由演示数据覆盖并明确标注。
实时接入失败即跳过，不降级到任何非公开数据源。

迭代指引

改这几处即可扩展，改动后重启 server.py：

新增/调整品类：core.py 的 CATEGORIES 字典（关键词映射到品类）
调整性别代理比例：core.py 的 GENDER_FSHARE（营销经验值，非真实数据）
新增省份/城市：core.py 的 PROVINCES（城市名会同步进 CITY_NAMES）
新增/修改演示标题：sample_data.py 的 TEMPLATES 与 CITIES
接入更多实时源：fetchers.py 的 fetch_* 函数，并在 try_live 的列表里登记

数据来源标注

演示数据：sample_data.build_sample() 程序生成，非真实统计
实时数据：fetchers.py 调用今日头条/微博公开热榜、抖音/小红书 best-effort 接口
全部为公开话题文本聚合，无任何个人数据