docs: document UP ranking defaults and fan history import

README.md

@@ -167,7 +167,7 @@ uv run python app.py serve --preview --config data/preview/config.json
 ```
 
 - 首页默认“最新动态”：今日增量、最新入库、最近发布、增长动态、热度速览、收藏夹容量与采集状态；
-- 榜单支持综合热度、七项单项、互动率、增长/增速，以及 UP 聚合榜；服务端筛选、排序、分页和 CSV 导出；
+- 榜单支持综合热度、七项单项、互动率、增长/增速，以及 UP 聚合榜；UP 榜默认按**平均播放**排序，总播放和视频数放在排序项末尾；服务端筛选、排序、分页和 CSV 导出；
 - 视频详情提供七项指标、单指标趋势、快照表和同 UP 对比；UP 页提供聚合趋势与单视频对比；
 - 粉丝页只绘制粉丝曲线，不叠加视频数据；
 - 候选池和系统状态只读展示，操作入口指向 Telegram/CLI；
@@ -185,6 +185,28 @@ uv run python app.py serve --preview --config data/preview/config.json
 - 预览配置不包含真实 Cookie，端口 8081，Telegram 关闭；
 - 重新生成前必须先停止预览服务，否则 Windows 会因数据库被占用而拒绝覆盖。
 
+### 粉丝历史回填
+
+小满虫之家 `data.html` 的 `assets/js/data.js` 包含 90 天粉丝锚点和每日净增。可以只读拉取并回填 `up_stat`：
+
+```powershell
+# 先预览将要写入的内容
+uv run python tools/import_fans_history.py --days 90 --dry-run
+
+# 实际写入；默认跳过已有成功记录，--force 才覆盖
+uv run python tools/import_fans_history.py --days 90
+
+# 站点不可达时，用保存下来的 data.js 离线导入
+uv run python tools/import_fans_history.py --from-file data.js --days 90
+```
+
+- 数据源当前快照日期为 `2026-10-24`，导入范围 `2026-07-27 ~ 2026-10-24`；
+- 只写 `up_stat`，不修改视频快照、收藏夹或黑名单；
+- 缺失日期不插值，粉丝曲线会断开；
+- 默认跳过已有 `ok=1` 记录；`ok=0` 的历史记录会用站点数据修复；
+- 页面的“日增”只在存在前一天数据时计算，跨多天不会标成日增；
+- 写入前建议先备份 `data/app.db`，例如 `data/backup/app-pre-fans-YYYYMMDD.db`。
+
 ## 配置
 
 复制样例配置，并填写 B 站账号信息：
@@ -330,6 +352,7 @@ uv run python tests/test_maintenance.py     # 日备份与保留期
 uv run python tests/test_timeutil.py        # 上海时区与每日任务时间
 uv run python tests/test_analytics.py      # 热度、互动率、增长与封面
 uv run python tests/test_preview_seed.py   # 预览库回填、确定性与安全边界
+uv run python tests/test_fans_history.py   # 粉丝历史解析、净增计算与幂等回填
 uv run python tests/test_web_queries.py    # 看板查询层与冷启动
 uv run python tests/test_web_server.py     # 只读路由、鉴权、静态资源与预览模式
 uv run python tests/test_scheduler.py       # 内置调度器到期/失败隔离
@@ -348,6 +371,7 @@ data/journal-<media_id>.jsonl 排序执行日志
 data/app.db                    SQLite 数据库（收藏夹、视频、快照、粉丝、黑名单）
 data/backup/app-YYYYMMDD.db    每日快照后的 SQLite 备份
 data/backup/app-pre-v*.db      数据库迁移前的自动备份
+data/backup/app-pre-fans-*.db  粉丝历史回填前的手动备份
 data/preview/app.db            合成预览数据库（不提交）
 data/preview/config.json       无凭据的预览配置（不提交）
 ```