docs: document read-only dashboard and preview workflow

2026-10-31 23:47:02 +08:00
1 parent cbba405271
commit d18ebbfb2f
@@ -1,6 +1,6 @@
 # 咻咻满 Reaction 视频数据看板开发文档

-> **状态：** P0（数据底座与收藏夹同步）、P1（每日快照与粉丝追踪）已实施并通过只读联调；P2 待开始
+> **状态：** P0（数据底座与收藏夹同步）、P1（每日快照与粉丝追踪）、P2（只读本地看板）、P3（Telegram 与一键加入）已实施
 >
 > **技术基线：** Python 3.14、Python 标准库、SQLite、原生 HTML/CSS/JavaScript、`uv`
 >
@@ -107,8 +107,15 @@ uv run python app.py auth-check
 uv run python app.py status

 # P2 起启动本地看板服务
+uv run python app.py serve
+uv run python app.py serve --config .\config.json
+
+# 无子命令启动完整服务：只读 Web + 调度 + Telegram
 uv run python app.py
-uv run python app.py --config .\config.json
+
+# 生成 7 天预览库并启动预览
+uv run python tools/seed_preview_db.py --days 7
+uv run python app.py serve --preview --config data/preview/config.json
 ```

 不建议直接激活 `.venv`；优先使用 `uv run ...`，这样命令总是运行在项目锁定的解释器和环境中。
@@ -218,10 +225,10 @@ PRAGMA synchronous = NORMAL;
 │   │   ├── snapshot.py
 │   │   └── maintenance.py
 │   ├── notify/telegram.py         # Telegram 消息与按钮
-│   └── web/                       # P2 预留
-│       ├── server.py
-│       ├── api.py
-│       └── static/
+│   └── web/                       # P2 只读看板
+│       ├── server.py              # HTTP、路由、鉴权、静态资源
+│       ├── queries.py             # 看板 SQL 与数据整形
+│       └── static/                # 原生 JS/CSS、ECharts、预览页面
 │
 ├── tests/
 └── data/                          # 本地运行期数据，默认不提交
@@ -487,9 +494,10 @@ P3 实现说明：

 ### 9.1 API 原则

- `/api/health` 可匿名，仅返回健康状态；
- 其他 `/api/*` 默认要求 `Authorization: Bearer <token>`；
- 写操作额外要求 CSRF 防护与 Origin/Referer 校验；
+- P2 看板**只读**：业务接口只注册 GET，写方法统一返回 `405`；
+- 数据管理（收藏、忽略、拉黑、移出库、移除黑名单）继续通过 Telegram、CLI 或数据库完成；
+- `/api/health` 可匿名；配置 `web.auth_token` 后其他 `/api/*` 要求 Cookie 或 `Authorization: Bearer <token>`；
+- 只读接口不需要 CSRF；登录 POST 只建立会话，不修改业务数据；
 - API 返回 JSON；前端不复制热度、状态机或收藏夹归属判断；
 - CSV 导出由后端根据当前筛选条件生成。

@@ -497,32 +505,38 @@ P3 实现说明：

 | 方法 | 路径 | 用途 |
 |---|---|---|
-| `GET` | `/api/overview` | 总览指标、容量、采集状态 |
-| `GET` | `/api/videos` | 视频分页、筛选和排序 |
+| `GET` | `/api/overview` | 首页动态、总览指标、容量、采集状态 |
+| `GET` | `/api/videos` | 视频分页、筛选和排序（支持 added/published/heat/七项/互动/增长） |
 | `GET` | `/api/videos/{aid}` | 视频详情 |
 | `GET` | `/api/videos/{aid}/trend` | 七项趋势数据 |
-| `GET` | `/api/rankings` | 热度、增长、互动率与单项榜 |
+| `GET` | `/api/rankings` | 视频榜或 `scope=up` 的 UP 聚合榜 |
 | `GET` | `/api/ups` | UP 聚合榜单 |
+| `GET` | `/api/ups/{mid}` | UP 详情、聚合趋势和视频列表 |
 | `GET` | `/api/fans` | 粉丝曲线与增量 |
-| `GET` | `/api/candidates` | 候选池 |
-| `GET` | `/api/system/status` | 最近任务、下次任务、错误日志 |
-| `POST` | `/api/candidates/{aid}/favorite` | 收藏候选 |
-| `POST` | `/api/candidates/{aid}/ignore` | 忽略候选 |
-| `POST` | `/api/candidates/{aid}/blacklist` | 拉黑候选所属 UP |
-| `DELETE` | `/api/blacklist/{mid}` | 移除黑名单 |
-| `POST` | `/api/videos/{aid}/drop` | 手动停止追踪 |
+| `GET` | `/api/candidates` | 候选池（只读） |
+| `GET` | `/api/system` | 最近任务、下次任务、备份、黑名单 |
+| `GET` | `/api/export.csv` | 按当前视频筛选导出 CSV |

 ### 9.2 页面

 | 页面 | 内容 |
 |---|---|
-| 总览 | 库内数、UP 数、今日新增、增量、容量条、采集成功率、故障提示。 |
+| 首页 | 最新动态优先：今日增量、最新入库、最近发布、增长动态、热度速览、容量与采集状态。 |
 | 榜单 | 综合热度、七项单项、增长、增速、互动率、UP 聚合、筛选和 CSV。 |
-| 视频详情 | 元数据、七项趋势、快照表、失败标记、同 UP 对比。 |
-| UP 页 | UP 的全部视频、聚合趋势和平均互动率。 |
+| 视频详情 | 元数据、七项指标、单指标趋势、快照表、失败标记、同 UP 对比。 |
+| UP 页 | UP 的全部视频、聚合趋势、单视频对比和平均互动率。 |
 | 粉丝页 | 粉丝总数、日增、7 日净增、累计增长；不叠加视频数据。 |
-| 候选池 | 待确认候选、规则命中、剩余保留时间和三个操作。 |
-| 系统状态 | 最近扫描、同步、快照、下一次运行时间和错误。 |
+| 候选池 | 待确认候选、规则命中、剩余保留时间；操作指向 Telegram/CLI。 |
+| 系统状态 | 最近扫描、同步、快照、下次运行、备份、鉴权和黑名单。 |
+
+### 9.3 预览模式
+
+- `tools/seed_preview_db.py` 复制真实库并回填合成快照，真实库只读；
+- 合成快照写 `src='preview'`，预览库写 `kv preview:seeded=1`；
+- `python app.py serve --preview` 校验标记，缺失时拒绝启动；
+- 预览配置不包含真实凭据，默认端口 8081，Telegram 关闭；
+- 预览页面显示固定“预览数据 · 只读”横幅；
+- 重新生成预览库前必须停止预览服务，避免 Windows 文件占用。

 ---

@@ -583,7 +597,10 @@ uv run python tests/test_moves.py
 - 热度、增长和互动率计算；
 - 收藏夹目标选择与排序锚点；
 - `fav_action` 的重复点击、失败重试和过期处理；
- Telegram 用户与 chat ID 授权校验。
+- Telegram 用户与 chat ID 授权校验；
+- 看板查询的筛选、分页、增长冷启动与状态过滤；
+- 只读路由、鉴权、静态资源路径穿越和预览标记校验；
+- 预览库生成的确定性、单调性、异常样本与真实库隔离。

 只有当标准库测试维护成本明显过高时，才考虑通过 `uv add --dev pytest` 引入 pytest。

@@ -656,11 +673,17 @@ uv run python tests/test_moves.py
 - 真实 `deal` / `sort` 尚未在收藏夹执行，等待用户点击 Telegram 按钮或授权测试视频后验证；
 - 自动化测试见 `tests/test_classify.py`、`test_search.py`、`test_candidates.py`、`test_discovery.py`、`test_fav_position.py`、`test_favorites.py`、`test_telegram.py`、`test_httpx_transport.py`、`test_favsort_http.py`。

-### P2：本地看板
+### P2：只读本地看板 ✅

- 总览、榜单、详情、UP、粉丝、候选和系统状态页面；
- 原生前端和 ECharts；
- 本机默认绑定 `127.0.0.1:8080`。
+- 首页、榜单、视频/UP 详情、粉丝、候选和系统状态页面；
+- 原生前端和本地 vendored ECharts；
+- 本机默认绑定 `127.0.0.1:8080`；
+- Web 业务接口只读，写操作继续由 Telegram/CLI/数据库承担；
+- 首页默认“最新动态”，增长榜在不足 2 天时显示空态；
+- 视频趋势按单指标切换，缺失日断开、失败快照按缺失处理；
+- 实现 `tools/seed_preview_db.py`：复制真实库并回填 7 天合成快照，支持 `--profile live|first-day`；
+- `serve --preview` 校验 `preview:seeded=1` 标记，预览页面显示只读横幅；
+- 自动化测试见 `tests/test_analytics.py`、`test_preview_seed.py`、`test_web_queries.py`、`test_web_server.py`。

 ### P4：可选部署