docs: document duration efficiency, up follower snapshot and nav split
This commit is contained in:
kairee committed
1 parent
c0b0286395
commit
cb9e8e031b
2 files changed
+101
-22
No files matched your search
+50
-10
@@ -100,6 +100,10 @@ uv run python app.py run --once
|
||||
uv run python app.py snapshot
|
||||
uv run python app.py snapshot --force
|
||||
|
||||
# 回填历史视频的 UP 粉丝数快照（第 9 轮；只补空值）
|
||||
uv run python app.py backfill-followers
|
||||
uv run python app.py backfill-followers --dry-run
|
||||
|
||||
# 检查 Cookie 登录态（P1）
|
||||
uv run python app.py auth-check
|
||||
|
||||
@@ -206,7 +210,7 @@ PRAGMA synchronous = NORMAL;
|
||||
│
|
||||
├── reaction_board/
|
||||
│ ├── config.py # 配置、ENV 覆盖、mtime 热加载
|
||||
│ ├── analytics.py # 热度、增长、互动率与封面工具
|
||||
│ ├── analytics.py # 热度、增长、互动率、时长效率、EB 收缩与封面工具
|
||||
│ ├── database.py # SQLite 连接、迁移、单写队列
|
||||
│ ├── migrations.py # schema_version 与迁移
|
||||
│ ├── scheduler.py # 内置任务调度
|
||||
@@ -228,6 +232,7 @@ PRAGMA synchronous = NORMAL;
|
||||
│ │ ├── telegram_poller.py # getUpdates 与回调分发
|
||||
│ │ ├── folder_sync.py
|
||||
│ │ ├── snapshot.py
|
||||
│ │ ├── up_profile.py # UP 粉丝快照采集与历史回填
|
||||
│ │ └── maintenance.py
|
||||
│ ├── notify/telegram.py # Telegram 消息与按钮
|
||||
│ └── web/ # P2 只读看板
|
||||
@@ -521,24 +526,27 @@ P3 实现说明：
|
||||
| 方法 | 路径 | 用途 |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/overview` | 首页动态、总览指标、容量、采集状态 |
|
||||
| `GET` | `/api/videos` | 视频分页、筛选和排序（支持 added/published/heat/七项/互动/增长） |
|
||||
| `GET` | `/api/videos/{aid}` | 视频详情 |
|
||||
| `GET` | `/api/videos` | 视频分页、筛选和排序（支持 added/published/heat/七项/互动/增长/内容效率） |
|
||||
| `GET` | `/api/videos/{aid}` | 视频详情（含分 P 数、入库时粉丝数、内容/互动效率） |
|
||||
| `GET` | `/api/videos/{aid}/trend` | 七项趋势数据 |
|
||||
| `GET` | `/api/rankings` | 视频榜或 `scope=up` 的 UP 聚合榜 |
|
||||
| `GET` | `/api/ups` | UP 聚合榜单 |
|
||||
| `GET` | `/api/rankings` | 兼容旧链接；`scope=up` 时为 UP 聚合榜 |
|
||||
| `GET` | `/api/ups` | UP 聚合榜单（含总时长、播放·小时、内容效率） |
|
||||
| `GET` | `/api/ups/{mid}` | UP 详情、聚合趋势和视频列表 |
|
||||
| `GET` | `/api/fans` | 粉丝曲线与增量 |
|
||||
| `GET` | `/api/candidates` | 候选池（只读） |
|
||||
| `GET` | `/api/system` | 最近任务、下次任务、备份、黑名单 |
|
||||
| `GET` | `/api/about` | 数据说明页当前口径（配置阈值、权重、覆盖度；无凭据） |
|
||||
|
||||
### 9.2 页面
|
||||
|
||||
| 页面 | 内容 |
|
||||
|---|---|
|
||||
| 首页 | 最新动态优先：今日增量、最新入库、最近发布、增长动态、热度速览、容量与采集状态。 |
|
||||
| 榜单 | 综合热度、七项单项、播放增量、播放增速、互动率、UP 聚合和筛选。 |
|
||||
| 视频详情 | 元数据、七项指标、单指标趋势、快照表、失败标记、同 UP 对比。 |
|
||||
| UP 页 | UP 的全部视频、聚合趋势、单视频对比和平均互动率。 |
|
||||
| 视频（`/videos`） | 内容效率（默认）、综合热度、播放/投币/收藏/评论、互动率、播放增量、播放增速；筛选与搜索。 |
|
||||
| UP主（`/ups`） | 独立入口，不再与视频混排；视频数、总时长、播放·小时、互动·小时等可分别排序。 |
|
||||
| 数据说明（`/about`） | 数据来源与更新、发布时间/入库时间/快照日期、指标公式、时长与成熟窗口筛选、粉丝快照覆盖与已知局限；数值由 `/api/about` 动态读取。 |
|
||||
| 视频详情 | 元数据、分 P 数、七项指标、内容/互动效率、入库时粉丝数、单指标趋势、快照表、同 UP 对比。 |
|
||||
| UP 页 | 该 UP 的全部视频、聚合趋势、单视频对比、总时长与播放·小时、入库时与当前粉丝数。 |
|
||||
| 粉丝页 | 粉丝总数、日增、7 日净增、累计增长（标注起始日期）；支持预设和自选日期，范围超过一年时按每月峰值日期聚合；最近记录默认 14 天并显示“较上一成功日”增量；不叠加视频数据。 |
|
||||
| 候选池 | 待确认候选、规则命中、剩余保留时间；操作指向 Telegram/CLI。 |
|
||||
| 系统状态 | 最近扫描、同步、快照、下次运行、备份、鉴权和黑名单。 |
|
||||
@@ -550,7 +558,8 @@ P3 实现说明：
|
||||
- `python app.py serve --preview` 校验标记，缺失时拒绝启动；
|
||||
- 预览配置不包含真实凭据，默认端口 8081，Telegram 关闭；
|
||||
- 预览页面显示固定“预览数据 · 不影响真实数据库”横幅，右上角入口显示“预览”；
|
||||
- 重新生成预览库前必须停止预览服务，避免 Windows 文件占用。
|
||||
- 重新生成预览库前必须停止预览服务，避免 Windows 文件占用；
|
||||
- 第 9 轮起本地不再保留 `data/app.db` 真实副本；重新生成预览时用 `--source` 指向 `data/backup/` 中的真实库备份（如 `app-local-before-reseed-20261101.db`）。
|
||||
|
||||
---
|
||||
|
||||
@@ -589,6 +598,22 @@ interaction_rate = (like + coin + favorite) / max(view, 1)
|
||||
- 互动率榜要求播放至少 100；
|
||||
- 样本不足两天的视频明确标注，不伪造增长数据。
|
||||
|
||||
### 10.3 时长效率与 UP 内容效率（第 9 轮）
|
||||
|
||||
```text
|
||||
内容小时 = duration / 3600
|
||||
内容效率 = view / 内容小时
|
||||
互动效率 = (like + coin + favorite) / 内容小时
|
||||
UP 内容效率 = (Σview + κ·μ₀) / (Σ内容分钟 + κ) * 60
|
||||
```
|
||||
|
||||
- 分母只用总时长，不用分 P 数（B 站播放记在 bvid 上，`view/pages` 无统计含义）；
|
||||
- 效率榜要求 `duration >= analytics.min_duration_seconds`（默认 600 秒）且发布满 `analytics.maturity_days`（默认 14 天）；
|
||||
- 不引入 `log(age)` 等无界年龄项，避免系统性惩罚老视频；
|
||||
- `duration` 缺失或非正数不参与效率排序；
|
||||
- UP 收缩强度 `κ` 取全库 UP 总内容分钟中位数，`analytics.shrink_minutes` 可覆盖；
|
||||
- 视频数与总时长并列展示、分别排序，不合成单一产出分。
|
||||
|
||||
---
|
||||
|
||||
## 11. 测试与质量要求
|
||||
@@ -615,7 +640,9 @@ uv run python tests/test_moves.py
|
||||
- 看板查询的筛选、分页、增长冷启动与状态过滤；
|
||||
- 只读路由、鉴权、静态资源路径穿越和预览标记校验；
|
||||
- 预览库生成的确定性、单调性、异常样本与真实库隔离；
|
||||
- 粉丝历史 CSV 解析、同日去重、缺口计数与幂等/替换回填。
|
||||
- 粉丝历史 CSV 解析、同日去重、缺口计数与幂等/替换回填；
|
||||
- UP 粉丝快照：首次写入不可覆盖、同轮去重、失败不中断、`live_since` 实时/回填标记、`backfill` 的 dry-run 与 limit；
|
||||
- 时长效率：`duration` 缺失/非正数、短于门槛、未满成熟窗口的排除，EB 收缩边界（除零、负先验）。
|
||||
|
||||
只有当标准库测试维护成本明显过高时，才考虑通过 `uv add --dev pytest` 引入 pytest。
|
||||
|
||||
@@ -702,6 +729,19 @@ uv run python tests/test_moves.py
|
||||
- `serve --preview` 校验 `preview:seeded=1` 标记，预览页面显示“预览数据”横幅；
|
||||
- 自动化测试见 `tests/test_analytics.py`、`test_preview_seed.py`、`test_web_queries.py`、`test_web_server.py`。
|
||||
|
||||
### 第 9 轮：时长效率榜、粉丝快照与导航拆分 ✅（2026-11-01）
|
||||
|
||||
- 迁移 v4：`video.pages`、`video.up_follower` / `up_follower_at` / `up_follower_backfilled`、`up_profile`；
|
||||
- 收藏夹同步结束时采集缺失 UP 的粉丝数（`relation/stat`，匿名可用）；`first_seen >= 运行开始 - 1h` 记为实时，更早的记为回填；
|
||||
- `app.py backfill-followers`：一次性回填历史视频粉丝数，支持 `--limit` / `--dry-run`；
|
||||
- 新增内容效率/互动效率榜与 UP 内容效率（Gamma–Poisson EB 收缩），过滤 < 600 秒与未满 14 天的视频；
|
||||
- `analytics` 配置段：`min_duration_seconds`、`maturity_days`、`min_view_for_efficiency`、`shrink_minutes`；
|
||||
- 主导航拆分：`/videos`（视频）与 `/ups`（UP主）独立；旧 `/rank` 保留兼容；
|
||||
- 新增 `/about` 数据说明页与 `/api/about`；
|
||||
- 卡片精简：列表只保留主指标与互动率，明细移到详情页；
|
||||
- 本地只保留可再生的预览库 `data/preview/app.db`；
|
||||
- 自动化测试新增 `tests/test_up_profile.py`，并扩展 `test_analytics.py`、`test_repository.py`、`test_config.py`、`test_folder_sync.py`、`test_web_queries.py`、`test_web_server.py`、`test_migrations.py`、`test_database.py`、`test_cli.py`。
|
||||
|
||||
### P4：可选部署
|
||||
|
||||
- 反向代理、TLS、远程访问鉴权；
|
||||
|
||||
Reference in new issue
Block a user