From 6a053bdfe82c9af2ff2e573f77106691b12c8e86 Mon Sep 17 00:00:00 2001 From: kaireewu Date: Sun, 1 Nov 2026 00:06:59 +0800 Subject: [PATCH] docs: document UP ranking defaults and fan history import --- DEVELOPMENT.md | 13 +++++++++++-- README.md | 26 +++++++++++++++++++++++++- project.md | 4 +++- 3 files changed, 39 insertions(+), 4 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 722f687..d703155 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -116,6 +116,10 @@ uv run python app.py # 生成 7 天预览库并启动预览 uv run python tools/seed_preview_db.py --days 7 uv run python app.py serve --preview --config data/preview/config.json + +# 从小满虫之家回填粉丝历史（先 dry-run，默认跳过已有成功记录） +uv run python tools/import_fans_history.py --days 90 --dry-run +uv run python tools/import_fans_history.py --days 90 ``` 不建议直接激活 `.venv`；优先使用 `uv run ...`，这样命令总是运行在项目锁定的解释器和环境中。 @@ -232,7 +236,8 @@ PRAGMA synchronous = NORMAL; │ └── static/ # 原生 JS/CSS、ECharts、预览页面 │ ├── tools/ -│ └── seed_preview_db.py # 复制真实库并回填 7 天预览数据 +│ ├── seed_preview_db.py # 复制真实库并回填 7 天预览数据 +│ └── import_fans_history.py # 从小满虫之家回填 90 天粉丝历史 │ ├── tests/ └── data/ # 本地运行期数据，默认不提交 @@ -434,6 +439,7 @@ P3 实现说明： - 其他错误最多重试 3 次，仍失败则写入 `ok=0` 与错误信息，不写伪造的零值； - 每条视频请求之间随机等待 1.0～1.6 秒； - 对 `track_fans` 中的每个 mid 请求一次 `relation/stat` 并写入 `up_stat`； +- 可用 `tools/import_fans_history.py` 从小满虫之家公开 `data.js` 回填最近 90 天粉丝历史；只写 `up_stat`，默认跳过已有成功记录； - 任务结束向 Telegram 发送成功数、失败数、移除数和总耗时摘要。 服务启动后若当天快照尚未成功完成，应补跑当日任务；已成功的 `(stat_date, aid)` 不重复请求。 @@ -604,7 +610,8 @@ uv run python tests/test_moves.py - Telegram 用户与 chat ID 授权校验； - 看板查询的筛选、分页、增长冷启动与状态过滤； - 只读路由、鉴权、静态资源路径穿越和预览标记校验； -- 预览库生成的确定性、单调性、异常样本与真实库隔离。 +- 预览库生成的确定性、单调性、异常样本与真实库隔离； +- 粉丝历史 data.js 解析、每日净增反推、缺口停止与幂等回填。 只有当标准库测试维护成本明显过高时，才考虑通过 `uv add --dev pytest` 引入 pytest。 @@ -685,7 +692,9 @@ uv run python tests/test_moves.py - Web 业务接口只读，写操作继续由 Telegram/CLI/数据库承担； - 首页默认“最新动态”，增长榜在不足 2 天时显示空态； - 视频趋势按单指标切换，缺失日断开、失败快照按缺失处理； +- UP 榜默认平均播放，总播放/视频数排到末尾；单视频 UP 不显示单视频对比图； - 实现 `tools/seed_preview_db.py`：复制真实库并回填 7 天合成快照，支持 `--profile live|first-day`； +- 实现 `tools/import_fans_history.py`：从小满虫之家 `data.js` 回填 90 天粉丝历史，支持 dry-run、缺口停止和幂等写入； - `serve --preview` 校验 `preview:seeded=1` 标记，预览页面显示只读横幅； - 自动化测试见 `tests/test_analytics.py`、`test_preview_seed.py`、`test_web_queries.py`、`test_web_server.py`。 diff --git a/README.md b/README.md index b92f8d7..3c12a46 100644 --- a/README.md +++ b/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-.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 无凭据的预览配置（不提交） ``` diff --git a/project.md b/project.md index ac8d2c7..027fd29 100644 --- a/project.md +++ b/project.md @@ -394,7 +394,8 @@ for folder in 配置的年度夹（2025、2026、…）: - 续跑时已成功的 `(stat_date, mid)` 会跳过，不会因后续失败覆盖为 NULL； - 只加 1 次请求/天，成本可忽略； - 支持配置多个 mid（`track_fans: [37754047]`），但看板默认只突出咻咻满； -- 粉丝日增 = 今日 - 昨日，缺失日不插值，曲线断开。 +- 粉丝日增 = 今日 - 昨日，缺失日不插值，曲线断开； +- 历史数据可用 `tools/import_fans_history.py` 从小满虫之家公开 `data.js` 回填最近 90 天（当前快照锚点 2026-10-24）；只写 `up_stat`，默认跳过已有成功记录，缺失日保持断开。 --- @@ -798,6 +799,7 @@ storage：SQLite WAL，单写线程 | 34 | **P2 预览数据** | 复制真实库回填 7 天：796 条视频、4,606 条合成快照、3 条失败、4 条候选、1 条预览黑名单 | | 35 | **P2 只读页面** | 首页/榜单/视频/UP/粉丝/候选/系统 7 个页面在 390px 与 1280px 下无脚本错误 | | 36 | **P2 只读边界** | 业务 POST/PUT/PATCH/DELETE 均返回 405，请求前后数据库行数不变 | +| 37 | **粉丝历史回填** | 从小满虫之家 `data.js` 回填 90 天（2026-07-27~10-24）共 90 条，week 锚点校验一致；10-25~10-30 无数据保持断开 | **未验证（需授权或外部配合）**：