docs: document read-only dashboard and preview workflow
This commit is contained in:
kairee committed
1 parent
cbba405271
commit
d18ebbfb2f
3 files changed
+122
-51
No files matched your search
@@ -4,9 +4,9 @@
|
||||
|
||||
项目以 B 站年度收藏夹为可信视频来源，补充关键词发现和 Telegram 人工确认，持续采集 reaction 视频的七项数据与咻咻满粉丝数，并提供本地数据看板。现有的收藏夹排序工具仍保留并作为一键加入后的排序能力基础。
|
||||
|
||||
> 当前状态：**P0（数据底座与收藏夹同步）、P1（快照与粉丝追踪）、P3（Telegram 与一键加入）已实施；P2 待开始。**
|
||||
> 当前状态：**P0（数据底座与收藏夹同步）、P1（快照与粉丝追踪）、P2（只读本地看板）、P3（Telegram 与一键加入）已实施。**
|
||||
>
|
||||
> 当前已可用：扫码授权、收藏夹读取、排序计划生成、执行与校验；SQLite 建库迁移、收藏夹首次导入与增量同步、失效识别、黑名单种子；每日七项视频快照、粉丝数快照、失败占位、断点续跑与日备份；搜索发现、候选池、Telegram 通知与收藏/忽略/拉黑回调。
|
||||
> 当前已可用：扫码授权、收藏夹读取、排序计划生成、执行与校验；SQLite 建库迁移、收藏夹首次导入与增量同步、失效识别、黑名单种子；每日七项视频快照、粉丝数快照、失败占位、断点续跑与日备份；搜索发现、候选池、Telegram 通知与收藏/忽略/拉黑回调；只读本地看板与可重复生成的预览数据。
|
||||
>
|
||||
> 详细业务口径、接口验证和风险记录见 [project.md](project.md)；开发架构与实施计划见 [DEVELOPMENT.md](DEVELOPMENT.md)。
|
||||
|
||||
@@ -21,7 +21,7 @@
|
||||
| 粉丝追踪 | 可用（P1） | 每日记录咻咻满等配置 UP 的粉丝数。 |
|
||||
| 搜索发现与候选池 | 可用（P3） | 每小时搜索前 2 页，分类打分后写入候选池。 |
|
||||
| Telegram 通知与一键加入 | 可用（P3） | 收藏 / 忽略 / 拉黑按钮，`deal` + `sort` 回读校验。 |
|
||||
| 本地数据看板 | 规划（P2） | 总览、榜单、视频/UP 详情、粉丝曲线、候选池和系统状态。 |
|
||||
| 本地数据看板 | 可用（P2） | 只读总览、榜单、视频/UP 详情、粉丝曲线、候选池和系统状态。 |
|
||||
|
||||
## 核心工作流
|
||||
|
||||
@@ -150,6 +150,41 @@ uv run python app.py run
|
||||
|
||||
> 真实 `deal` / `sort` 需要用户点击 Telegram 按钮才会触发；离线测试使用契约一致的 Mock 覆盖。
|
||||
|
||||
## P2：只读本地看板
|
||||
|
||||
P2 提供移动端优先的只读看板，默认绑定 `127.0.0.1:8080`。Web 页面不提供收藏、忽略、拉黑、移出库等写操作；数据管理仍通过 Telegram、CLI 或数据库完成。
|
||||
|
||||
```powershell
|
||||
# 只启动只读 Web（不运行调度、不连 B 站）
|
||||
uv run python app.py serve
|
||||
|
||||
# 无子命令启动完整服务：只读 Web + 调度 + Telegram
|
||||
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
|
||||
```
|
||||
|
||||
- 首页默认“最新动态”：今日增量、最新入库、最近发布、增长动态、热度速览、收藏夹容量与采集状态；
|
||||
- 榜单支持综合热度、七项单项、互动率、增长/增速，以及 UP 聚合榜；服务端筛选、排序、分页和 CSV 导出；
|
||||
- 视频详情提供七项指标、单指标趋势、快照表和同 UP 对比；UP 页提供聚合趋势与单视频对比；
|
||||
- 粉丝页只绘制粉丝曲线，不叠加视频数据；
|
||||
- 候选池和系统状态只读展示，操作入口指向 Telegram/CLI；
|
||||
- 本地回环地址默认免登录；配置 `web.auth_token` 后启用登录页和 HttpOnly Cookie；非回环地址且未配置 token 时拒绝启动；
|
||||
- 所有业务接口只接受 GET，写方法返回 `405`。
|
||||
|
||||
### 预览数据
|
||||
|
||||
`tools/seed_preview_db.py` 通过 SQLite backup API 复制真实库到 `data/preview/app.db`，再回填 7 天合成快照：
|
||||
|
||||
- 合成行标记 `src='preview'`，并写入 `kv preview:seeded=1`；
|
||||
- 真实库只读，预览库与真实库完全分离；
|
||||
- 默认包含少量缺失日、3 条失败快照、4 条预览候选和 1 条预览黑名单；
|
||||
- `--profile first-day` 可生成保持“首次导入”状态的冷启动库；
|
||||
- 预览配置不包含真实 Cookie，端口 8081，Telegram 关闭；
|
||||
- 重新生成前必须先停止预览服务，否则 Windows 会因数据库被占用而拒绝覆盖。
|
||||
|
||||
## 配置
|
||||
|
||||
复制样例配置，并填写 B 站账号信息：
|
||||
@@ -293,6 +328,10 @@ uv run python tests/test_folder_sync.py # 首次导入、差集、失效识
|
||||
uv run python tests/test_snapshot.py # 七项快照、补采、断点续跑、粉丝、备份重试
|
||||
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_web_queries.py # 看板查询层与冷启动
|
||||
uv run python tests/test_web_server.py # 只读路由、鉴权、静态资源与预览模式
|
||||
uv run python tests/test_scheduler.py # 内置调度器到期/失败隔离
|
||||
uv run python tests/test_provider.py # 凭据变化重建客户端与配置 revision
|
||||
uv run python tests/test_favsort_run.py # 排序参数校验与混合资源类型
|
||||
@@ -309,6 +348,8 @@ data/journal-<media_id>.jsonl 排序执行日志
|
||||
data/app.db SQLite 数据库（收藏夹、视频、快照、粉丝、黑名单）
|
||||
data/backup/app-YYYYMMDD.db 每日快照后的 SQLite 备份
|
||||
data/backup/app-pre-v*.db 数据库迁移前的自动备份
|
||||
data/preview/app.db 合成预览数据库（不提交）
|
||||
data/preview/config.json 无凭据的预览配置（不提交）
|
||||
```
|
||||
|
||||
## 文档索引
|
||||
|
||||
Reference in new issue
Block a user