From dd6b09807d2f072d625381a2c196ebe17e2d50c0 Mon Sep 17 00:00:00 2001 From: kaireewu Date: Sun, 1 Nov 2026 02:23:10 +0800 Subject: [PATCH] docs: document csv fan import --- DEVELOPMENT.md | 14 +++++++------- README.md | 29 +++++++++++++++++++---------- project.md | 4 ++-- 3 files changed, 28 insertions(+), 19 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 232b015..764b775 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -117,9 +117,9 @@ uv run python app.py 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 +# 从 B 站粉丝历史 CSV 回填（先 dry-run；首次完整导入可用 --replace） +uv run python tools/import_fans_csv.py --csv E:\Downloads\history.csv --dry-run +uv run python tools/import_fans_csv.py --csv E:\Downloads\history.csv --replace ``` 不建议直接激活 `.venv`；优先使用 `uv run ...`，这样命令总是运行在项目锁定的解释器和环境中。 @@ -237,7 +237,7 @@ PRAGMA synchronous = NORMAL; │ ├── tools/ │ ├── seed_preview_db.py # 复制真实库并回填 7 天预览数据 -│ └── import_fans_history.py # 从小满虫之家回填 90 天粉丝历史 +│ └── import_fans_csv.py # 从 B 站粉丝历史 CSV 回填 up_stat │ ├── tests/ └── data/ # 本地运行期数据，默认不提交 @@ -439,7 +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`，默认跳过已有成功记录； +- 可用 `tools/import_fans_csv.py` 从 B 站粉丝历史 CSV 回填 `up_stat`；只写 `up_stat`，默认跳过已有成功记录，`--replace` 可用完整历史覆盖重建； - 任务结束向 Telegram 发送成功数、失败数、移除数和总耗时摘要。 服务启动后若当天快照尚未成功完成，应补跑当日任务；已成功的 `(stat_date, aid)` 不重复请求。 @@ -610,7 +610,7 @@ uv run python tests/test_moves.py - 看板查询的筛选、分页、增长冷启动与状态过滤； - 只读路由、鉴权、静态资源路径穿越和预览标记校验； - 预览库生成的确定性、单调性、异常样本与真实库隔离； -- 粉丝历史 data.js 解析、每日净增反推、缺口停止与幂等回填。 +- 粉丝历史 CSV 解析、同日去重、缺口计数与幂等/替换回填。 只有当标准库测试维护成本明显过高时，才考虑通过 `uv add --dev pytest` 引入 pytest。 @@ -693,7 +693,7 @@ uv run python tests/test_moves.py - 视频趋势按单指标切换，缺失日断开、失败快照按缺失处理； - UP 榜默认平均播放，总播放/视频数排到末尾；单视频 UP 不显示单视频对比图； - 实现 `tools/seed_preview_db.py`：复制真实库并回填 7 天合成快照，支持 `--profile live|first-day`； -- 实现 `tools/import_fans_history.py`：从小满虫之家 `data.js` 回填 90 天粉丝历史，支持 dry-run、缺口停止和幂等写入； +- 实现 `tools/import_fans_csv.py`：从 B 站粉丝历史 CSV 回填 `up_stat`，支持 dry-run、`--force` 覆盖和 `--replace` 重建； - `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 2eb89f2..c4d81dc 100644 --- a/README.md +++ b/README.md @@ -186,25 +186,34 @@ uv run python app.py serve --preview --config data/preview/config.json - 预览配置不包含真实 Cookie，端口 8081，Telegram 关闭； - 重新生成前必须先停止预览服务，否则 Windows 会因数据库被占用而拒绝覆盖。 -### 粉丝历史回填 +### 粉丝历史回填（CSV） -小满虫之家 `data.html` 的 `assets/js/data.js` 包含 90 天粉丝锚点和每日净增。可以只读拉取并回填 `up_stat`： +B 站粉丝历史 CSV 形如： + +```csv +时间,粉丝,7日变化,1日变化 +2026-10-31 22:42,2767269,139,-33 +2026-10-29 23:53,2767334,496,15 +``` + +导入命令： ```powershell # 先预览将要写入的内容 -uv run python tools/import_fans_history.py --days 90 --dry-run +uv run python tools/import_fans_csv.py --csv E:\Downloads\history.csv --dry-run -# 实际写入；默认跳过已有成功记录，--force 才覆盖 -uv run python tools/import_fans_history.py --days 90 +# 实际写入；默认跳过已有成功记录，--force 才覆盖同日期记录 +uv run python tools/import_fans_csv.py --csv E:\Downloads\history.csv -# 站点不可达时，用保存下来的 data.js 离线导入 -uv run python tools/import_fans_history.py --from-file data.js --days 90 +# 用完整 CSV 替换该 mid 的全部粉丝历史（推荐首次导入完整历史时使用） +uv run python tools/import_fans_csv.py --csv E:\Downloads\history.csv --replace ``` -- 数据源当前快照日期为 `2026-10-24`，导入范围 `2026-07-27 ~ 2026-10-24`； - 只写 `up_stat`，不修改视频快照、收藏夹或黑名单； +- 同一天出现多行时保留时间最晚的一条； - 缺失日期不插值，粉丝曲线会断开； -- 默认跳过已有 `ok=1` 记录；`ok=0` 的历史记录会用站点数据修复； +- 默认跳过已有 `ok=1` 记录；`ok=0` 的历史记录会被修复； +- `--replace` 会先删除该 mid 的全部 `up_stat`，再按 CSV 重建，适合用完整历史覆盖旧数据； - 页面的“日增”只在存在前一天数据时计算，跨多天不会标成日增； - 写入前建议先备份 `data/app.db`，例如 `data/backup/app-pre-fans-YYYYMMDD.db`。 @@ -395,7 +404,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_fans_csv.py # 粉丝 CSV 解析、替换与幂等回填 uv run python tests/test_web_queries.py # 看板查询层与冷启动 uv run python tests/test_web_server.py # 只读路由、鉴权、静态资源与预览模式 uv run python tests/test_scheduler.py # 内置调度器到期/失败隔离 diff --git a/project.md b/project.md index 52d04c3..d4fce4d 100644 --- a/project.md +++ b/project.md @@ -395,7 +395,7 @@ for folder in 配置的年度夹（2025、2026、…）: - 只加 1 次请求/天，成本可忽略； - 支持配置多个 mid（`track_fans: [37754047]`），但看板默认只突出咻咻满； - 粉丝日增 = 今日 - 昨日，缺失日不插值，曲线断开； -- 历史数据可用 `tools/import_fans_history.py` 从小满虫之家公开 `data.js` 回填最近 90 天（当前快照锚点 2026-10-24）；只写 `up_stat`，默认跳过已有成功记录，缺失日保持断开。 +- 历史数据可用 `tools/import_fans_csv.py` 从 B 站粉丝历史 CSV 回填；只写 `up_stat`，默认跳过已有成功记录，`--replace` 可用完整历史覆盖重建，缺失日保持断开。 --- @@ -801,7 +801,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 无数据保持断开 | +| 37 | **粉丝历史回填（CSV）** | 从 B 站粉丝历史 CSV 导入 2020-06-03~2026-10-31 共 1788 条，替换旧 91 条；155 个缺失日保持断开 | **未验证（需授权或外部配合）**：