feat: 完善 MVP-2 演示和进度体验
This commit is contained in:
meijiali
@@ -98,3 +98,90 @@ curl -f http://localhost:8000/health
|
||||
docker compose up -d --build
|
||||
curl -f http://localhost:8000/health
|
||||
```
|
||||
|
||||
## 公网云服务器部署
|
||||
|
||||
第一版公网演示使用云服务器 + Docker Compose，不增加登录或密码。
|
||||
|
||||
上线前准备：
|
||||
|
||||
```bash
|
||||
git pull
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
在 `.env` 中填写真实 Key：
|
||||
|
||||
```text
|
||||
TIKHUB_API_KEY=
|
||||
AI_BASE_URL=
|
||||
AI_API_KEY=
|
||||
AI_MODEL=
|
||||
```
|
||||
|
||||
启动：
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
curl -f http://127.0.0.1:8000/health
|
||||
```
|
||||
|
||||
如果服务器安全组直接开放端口，公网入口为：
|
||||
|
||||
```text
|
||||
http://服务器公网 IP:8000
|
||||
```
|
||||
|
||||
也可以用 Nginx 反向代理到本机 `127.0.0.1:8000`。
|
||||
|
||||
注意：
|
||||
|
||||
- 第一版公网不加访问控制，任何知道地址的人都可以访问页面。
|
||||
- 创建任务会消耗真实 TikHub 和 AI Key。
|
||||
- 系统仍保持同一时间只允许一个 running 任务，避免多人同时触发造成成本和稳定性问题。
|
||||
|
||||
## 初始化 Demo 数据
|
||||
|
||||
公网演示建议先初始化脱敏 Demo 数据：
|
||||
|
||||
```bash
|
||||
docker compose exec app python -m app.demo_seed
|
||||
```
|
||||
|
||||
Demo 数据特点：
|
||||
|
||||
- 使用脱敏真实感评论文本。
|
||||
- 不保存作者昵称、平台原始评论 ID、原始内容 URL 或 raw sensitive data。
|
||||
- 可以和新创建的真实任务同时出现在任务列表中。
|
||||
|
||||
## 数据库异常备份与恢复
|
||||
|
||||
如果页面出现数据库不可用提示，先不要删除 `data` 目录。
|
||||
|
||||
系统会优先备份现有 SQLite 文件到：
|
||||
|
||||
```text
|
||||
data/corrupt-backups/
|
||||
```
|
||||
|
||||
手动诊断：
|
||||
|
||||
```bash
|
||||
docker compose exec app python - <<'PY'
|
||||
from app.db import engine
|
||||
from sqlalchemy import text
|
||||
with engine.connect() as c:
|
||||
print(c.execute(text("PRAGMA integrity_check")).fetchall())
|
||||
print(c.exec_driver_sql("PRAGMA wal_checkpoint(TRUNCATE)").fetchall())
|
||||
PY
|
||||
```
|
||||
|
||||
如果需要重新初始化演示数据：
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
mv data/app.db data/corrupt-backups/app.db.manual.bak
|
||||
rm -f data/app.db-wal data/app.db-shm
|
||||
docker compose up -d --build
|
||||
docker compose exec app python -m app.demo_seed
|
||||
```
|
||||
|
||||
@@ -900,3 +900,433 @@ WO-10 收尾与 P1 评估
|
||||
验收结论：小红书 1×1×10 跑通，页面显示已完成，报告摘要正常
|
||||
遗留问题：任务列表自动刷新和进度条仍待做
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. MVP-2 新问题与产品化工单
|
||||
|
||||
本节记录 MVP 演示候选版本之后，用户在网页人工验收阶段发现的新问题和新增需求。
|
||||
|
||||
当前原则：
|
||||
|
||||
- 不覆盖 WO-01 到 WO-10 的完成记录。
|
||||
- 新问题按 MVP-2 工单继续推进。
|
||||
- 阻塞主链路的问题优先修复。
|
||||
- 不清楚的产品决策必须先确认，不擅自替用户决定。
|
||||
- 每个工单完成后继续按“完成日期 / commit / 验证命令 / 验收结论 / 遗留问题”记录。
|
||||
|
||||
### MVP-2 工单总览
|
||||
|
||||
| 编号 | 工单 | 优先级 | 目标 |
|
||||
|---|---|---|---|
|
||||
| WO-11 | 全站 Internal Server Error 排查与兜底 | P0 | 解决点击按钮或刷新页面出现 500 的阻塞问题 |
|
||||
| WO-12 | 导出 Markdown / CSV 点击失效修复 | P0 | 恢复报告和评论导出主链路 |
|
||||
| WO-13 | 抓取任务进度透明化与耗时预期 | P0 | 降低长任务黑盒感，让用户知道任务是否真的在推进 |
|
||||
| WO-14 | Demo 数据保留与新任务并存体验 | P0 | 打开页面即可看 demo 数据，同时还能新跑完整流程 |
|
||||
| WO-15 | 公网部署方案与上线验收 | P0 | 从本机 Docker 演示推进到可公网访问的部署 |
|
||||
| WO-16 | UI 产品化改版 | P1 | 在不破坏主链路的前提下提升页面观感和演示质感 |
|
||||
| WO-17 | 默认规模数据量解释与展示优化 | P1 | 把“未达到 1250”解释为真实内容/评论不足，并在 UI 中清楚呈现 |
|
||||
|
||||
### WO-11 全站 Internal Server Error 排查与兜底
|
||||
|
||||
优先级：P0
|
||||
|
||||
背景：
|
||||
|
||||
- 用户反馈：每次点击一个按钮或刷新页面时，页面可能显示 `Internal Server Error`。
|
||||
- 这是主链路阻塞问题，必须优先定位。
|
||||
|
||||
目标：
|
||||
|
||||
- 找出导致 500 的具体路由、异常堆栈和触发条件。
|
||||
- 对可恢复异常提供友好页面或错误提示，不让普通点击直接暴露 500。
|
||||
- 确保任务详情页、热点报告页、内容详情页、导出入口、刷新入口都不会因缺失数据直接崩溃。
|
||||
|
||||
包含范围：
|
||||
|
||||
- 查看 Docker / Uvicorn 日志，记录 500 对应的异常堆栈。
|
||||
- 覆盖任务详情页刷新、任务列表刷新、热点报告页、内容详情页、导出入口等高频路由。
|
||||
- 对缺失任务、缺失热点、缺失内容、缺失报告、数据库读取异常等场景增加兜底。
|
||||
- 增加回归测试，覆盖已发现的 500 触发路径。
|
||||
|
||||
边界情况：
|
||||
|
||||
- 任务 ID 不存在。
|
||||
- 报告记录不存在。
|
||||
- 内容条目存在但评论为空。
|
||||
- 任务处于 `running`，相关热点 / 内容 / 报告尚未生成。
|
||||
- 数据库暂时不可读或记录字段为空。
|
||||
- 浏览器重复刷新或重复点击按钮。
|
||||
|
||||
验收标准：
|
||||
|
||||
- 已知触发 500 的页面和按钮不再返回 `Internal Server Error`。
|
||||
- 真实异常在服务端日志中可定位，前端展示友好提示。
|
||||
- `pytest tests/unit tests/integration -q` 通过。
|
||||
- Docker 环境下手动刷新任务详情页、报告页、内容页不出现 500。
|
||||
|
||||
建议 commit：
|
||||
|
||||
```text
|
||||
fix: 修复页面刷新和按钮点击的 500 错误
|
||||
```
|
||||
|
||||
待确认：
|
||||
|
||||
- 用户需要提供或复现最容易触发 500 的页面 URL 与按钮名称；如果无法提供，则开发时先从当前浏览器打开的任务详情页开始排查。
|
||||
|
||||
### WO-12 导出 Markdown / CSV 点击失效修复
|
||||
|
||||
优先级：P0
|
||||
|
||||
背景：
|
||||
|
||||
- 用户反馈：点击导出 Markdown 文档和导出 CSV 评论时，页面没有反应，像是按钮失效。
|
||||
|
||||
目标：
|
||||
|
||||
- 恢复热点报告 Markdown、内容报告 Markdown、热点评论 CSV、内容评论 CSV 的下载能力。
|
||||
- 当报告尚未生成或数据为空时，按钮必须给出明确提示，而不是“点不动”。
|
||||
|
||||
包含范围：
|
||||
|
||||
- 检查导出按钮的前端事件绑定、HTMX / 普通链接行为、下载路由返回头。
|
||||
- 检查导出路由是否返回正确的 `Content-Type` 和 `Content-Disposition`。
|
||||
- 检查浏览器端是否被 disabled 状态、JS 错误或 500 响应卡住。
|
||||
- 报告缺失时提供友好提示。
|
||||
- 评论为空时仍可下载只有表头的 CSV，或按用户决策改为提示无评论。
|
||||
|
||||
边界情况：
|
||||
|
||||
- 报告尚未生成。
|
||||
- 评论数量为 0。
|
||||
- 文件名包含中文或特殊字符。
|
||||
- 浏览器拦截下载。
|
||||
- 导出接口返回 404 / 500。
|
||||
- 用户连续点击导出按钮。
|
||||
|
||||
验收标准：
|
||||
|
||||
- 页面点击导出后浏览器能下载文件，或看到明确的不可导出原因。
|
||||
- CSV 可打开且含 UTF-8-BOM、公式注入防护、换行替换。
|
||||
- Markdown 内容与页面报告一致。
|
||||
- 导出失败不会造成整页 500。
|
||||
|
||||
建议 commit：
|
||||
|
||||
```text
|
||||
fix: 修复报告和评论导出点击失效
|
||||
```
|
||||
|
||||
待确认：
|
||||
|
||||
- 评论为空时，用户希望“下载只有表头的 CSV”，还是“按钮禁用并提示暂无评论”。
|
||||
|
||||
### WO-13 抓取任务进度透明化与耗时预期
|
||||
|
||||
优先级：P0
|
||||
|
||||
背景：
|
||||
|
||||
- 用户反馈：开始抓取后虽然显示运行中，但不知道具体需要多少时间，也不知道系统是否真的在抓取。
|
||||
- 当前体验仍有黑盒感，尤其是默认规模任务会等待较久。
|
||||
|
||||
目标：
|
||||
|
||||
- 让任务详情页清楚展示当前阶段、已完成数量、失败数量、最近更新时间和粗略耗时预期。
|
||||
- 用户能判断任务是否仍在推进、是否卡住、卡在哪个阶段。
|
||||
|
||||
包含范围：
|
||||
|
||||
- 后端记录或计算任务阶段：
|
||||
- 获取热点中
|
||||
- 搜索内容中
|
||||
- 抓取评论中
|
||||
- AI 分析中
|
||||
- 生成报告中
|
||||
- 已完成 / 已失败
|
||||
- 展示当前进度：
|
||||
- 热点：已获取 / 目标
|
||||
- 内容：已处理 / 总数
|
||||
- 评论：已抓取数量
|
||||
- AI：成功率 / 失败数
|
||||
- 报告：已生成数量
|
||||
- 展示任务开始时间、运行时长、最近更新时间。
|
||||
- 给出非承诺式耗时提示，例如“小规模通常较快，默认规模可能需要数分钟，取决于 TikHub 与 AI 响应速度”。
|
||||
- 如果一段时间没有进度更新，展示“可能仍在等待外部接口响应”的提示。
|
||||
|
||||
边界情况：
|
||||
|
||||
- 刚开始运行，热点还没入库。
|
||||
- 已抓到热点但还没抓到内容。
|
||||
- 某个内容失败但任务继续。
|
||||
- 外部接口慢但未超时。
|
||||
- AI 请求慢。
|
||||
- Docker 重启导致任务中断。
|
||||
|
||||
验收标准：
|
||||
|
||||
- 创建任务后，任务详情页能看到阶段和进度数字变化。
|
||||
- 用户不需要打开日志，也能知道任务大概处于哪个阶段。
|
||||
- 任务长时间无变化时有提示，不再只显示“正在抓取热点数据，请稍候...”。
|
||||
- 终态为 success / failed 后停止轮询。
|
||||
|
||||
建议 commit：
|
||||
|
||||
```text
|
||||
feat: 增强任务进度和运行阶段展示
|
||||
```
|
||||
|
||||
待确认：
|
||||
|
||||
- 是否需要显示“预计剩余时间”。如果需要，建议第一版只显示粗略区间，不做精确倒计时，避免误导。
|
||||
|
||||
### WO-14 Demo 数据保留与新任务并存体验
|
||||
|
||||
优先级：P0
|
||||
|
||||
背景：
|
||||
|
||||
- 用户希望别人打开后既能看到已经跑通的 demo 数据，又能自己创建任务跑完整流程。
|
||||
- 当前 `data/` 是本地运行数据，未纳入 Git，不能直接当作可交付 demo 数据方案。
|
||||
|
||||
目标：
|
||||
|
||||
- 设计一套可控的 demo 数据方案，让页面首次打开就有可展示内容。
|
||||
- 同时保留用户创建新任务的能力。
|
||||
|
||||
可选方案：
|
||||
|
||||
| 方案 | 描述 | 优点 | 风险 |
|
||||
|---|---|---|---|
|
||||
| A | 保留本机 `data/app.db` 作为本地演示数据库，不提交 Git | 最快，适合自己电脑演示 | 换机器或公网部署时不可复现 |
|
||||
| B | 提供脱敏 seed 数据脚本，部署时生成 demo 任务 | 可复现，适合交付和公网部署 | 需要额外开发 seed 脚本 |
|
||||
| C | 提供 demo JSON / fixture，首次启动导入 | 可控、可版本化 | 需要确认哪些真实数据可以脱敏保存 |
|
||||
|
||||
包含范围：
|
||||
|
||||
- 首页展示 demo 任务和真实新任务。
|
||||
- 标记 demo 数据来源，避免和真实新任务混淆。
|
||||
- 提供重置 demo 数据或清空本地任务的说明。
|
||||
- 确认不提交 API Key、用户隐私、敏感评论作者信息。
|
||||
|
||||
边界情况：
|
||||
|
||||
- demo 数据和新抓取任务混在同一个任务列表。
|
||||
- 用户删除或重置数据库后 demo 数据消失。
|
||||
- 公网部署时没有本地 data 目录。
|
||||
- 真实评论内容可能包含敏感信息。
|
||||
|
||||
验收标准：
|
||||
|
||||
- 新用户打开页面能看到可点击的 demo 任务。
|
||||
- 用户仍能创建新任务并进入运行中状态。
|
||||
- demo 数据不依赖真实 API Key。
|
||||
- demo 数据不包含敏感凭证。
|
||||
|
||||
建议 commit：
|
||||
|
||||
```text
|
||||
feat: 增加可复现 demo 数据
|
||||
```
|
||||
|
||||
待确认：
|
||||
|
||||
- demo 数据使用真实抓取结果脱敏，还是使用模拟数据。
|
||||
- 是否允许在公网演示中展示真实评论文本和作者昵称。
|
||||
- demo 数据是否需要提供“一键恢复”能力。
|
||||
|
||||
### WO-15 公网部署方案与上线验收
|
||||
|
||||
优先级：P0
|
||||
|
||||
背景：
|
||||
|
||||
- 用户明确需要公网部署，而不仅是本机 Docker 访问。
|
||||
|
||||
目标：
|
||||
|
||||
- 选择并落地公网部署方式，提供可访问 URL。
|
||||
- 确保环境变量、数据目录、端口、健康检查、重启策略清楚可靠。
|
||||
|
||||
包含范围：
|
||||
|
||||
- 确认部署目标：
|
||||
- 云服务器 Docker Compose
|
||||
- PaaS 平台
|
||||
- 内网穿透 / 临时演示链接
|
||||
- 配置环境变量和密钥管理。
|
||||
- 配置持久化数据目录。
|
||||
- 配置反向代理或公网端口。
|
||||
- 配置健康检查和重启策略。
|
||||
- 更新部署文档。
|
||||
|
||||
边界情况：
|
||||
|
||||
- API Key 不应暴露在仓库或页面。
|
||||
- 公网访问可能产生额外抓取成本。
|
||||
- 多人同时点击创建任务。
|
||||
- SQLite 在公网多人使用下的并发限制。
|
||||
- 没有登录权限时，任何知道地址的人都能创建抓取任务。
|
||||
|
||||
验收标准：
|
||||
|
||||
- 用户可以通过公网 URL 打开首页。
|
||||
- 公网环境能查看 demo 数据。
|
||||
- 公网环境能创建至少一个小规模任务。
|
||||
- 健康检查可访问。
|
||||
- 重启后数据不丢失，或文档明确说明数据生命周期。
|
||||
|
||||
建议 commit：
|
||||
|
||||
```text
|
||||
docs: 补充公网部署方案
|
||||
```
|
||||
|
||||
或如果包含实际部署配置：
|
||||
|
||||
```text
|
||||
chore: 增加公网部署配置
|
||||
```
|
||||
|
||||
待确认：
|
||||
|
||||
- 部署平台选择。
|
||||
- 是否需要访问密码 / 简单登录。
|
||||
- 是否允许公网用户直接消耗真实 TikHub 和 AI Key。
|
||||
- 是否需要限制同一时间只能运行一个任务。
|
||||
|
||||
### WO-16 UI 产品化改版
|
||||
|
||||
优先级：P1
|
||||
|
||||
背景：
|
||||
|
||||
- 用户明确希望后续修改 UI。
|
||||
- 当前页面主链路可用，但仍需要提升产品化观感。
|
||||
|
||||
目标：
|
||||
|
||||
- 在不破坏功能的前提下，让首页、任务列表、任务详情、报告页、内容详情页更适合演示。
|
||||
|
||||
包含范围：
|
||||
|
||||
- 首页信息架构优化。
|
||||
- 任务列表更像仪表盘。
|
||||
- 任务详情页突出进度、阶段、失败原因、AI 成功率。
|
||||
- 热点报告页和内容详情页优化阅读层次。
|
||||
- 按钮状态更清楚：可点击、加载中、禁用、失败。
|
||||
- 空状态更友好。
|
||||
- 移动端基础适配。
|
||||
|
||||
边界情况：
|
||||
|
||||
- 文本过长。
|
||||
- 评论列表很多。
|
||||
- 无报告 / 无评论 / AI 失败。
|
||||
- 默认规模任务 running 很久。
|
||||
- 导出按钮不可用。
|
||||
|
||||
验收标准：
|
||||
|
||||
- 页面不会出现文字重叠、按钮挤压、信息难以扫描。
|
||||
- 主要 CTA 明确。
|
||||
- 运行中和失败态清楚。
|
||||
- UI 改动不影响创建任务、查看报告和导出。
|
||||
|
||||
建议 commit：
|
||||
|
||||
```text
|
||||
feat: 优化 MVP 页面产品化体验
|
||||
```
|
||||
|
||||
待确认：
|
||||
|
||||
- UI 风格方向：更偏数据仪表盘、内部工具，还是偏演示型产品页面。
|
||||
- 是否需要提供简单品牌名 / Logo / 说明文案。
|
||||
|
||||
### WO-17 默认规模数据量解释与展示优化
|
||||
|
||||
优先级：P1
|
||||
|
||||
背景：
|
||||
|
||||
- 默认规模理论值是 `5×5×50=1250` 评论，但真实任务不一定达到。
|
||||
- 用户判断这更可能是笔记 / 视频本身评论不足，而不是接口错误。
|
||||
|
||||
目标：
|
||||
|
||||
- 在 UI 和文档中清楚解释“目标上限”和“实际返回”的区别。
|
||||
- 避免用户看到少于 1250 就误以为任务失败。
|
||||
|
||||
包含范围：
|
||||
|
||||
- 任务详情页展示：
|
||||
- 配置目标：5 热点 × 5 内容 × 50 评论
|
||||
- 实际结果：实际热点、实际内容、实际评论
|
||||
- 不足原因提示：平台内容 / 评论不足、接口返回不足、部分内容失败
|
||||
- 报告页展示样本数，避免将样本不足包装成完整全量分析。
|
||||
- 文档补充默认规模解释。
|
||||
|
||||
边界情况：
|
||||
|
||||
- 某个热点只有少量内容。
|
||||
- 某条内容本身评论不足 50。
|
||||
- API 返回空评论但内容存在。
|
||||
- 部分内容失败导致评论不足。
|
||||
|
||||
验收标准：
|
||||
|
||||
- 用户能区分“抓取上限”和“实际抓到数量”。
|
||||
- 默认规模任务少于 1250 时，页面给出合理说明。
|
||||
- 真实失败和自然不足有不同提示。
|
||||
|
||||
建议 commit：
|
||||
|
||||
```text
|
||||
feat: 展示默认规模目标与实际抓取差异
|
||||
```
|
||||
|
||||
待确认：
|
||||
|
||||
- 是否需要在报告里显示“样本不足，不代表完整舆情”的提示。
|
||||
|
||||
## 14. MVP-2 推荐执行顺序
|
||||
|
||||
建议先处理阻塞主链路和演示可信度的问题：
|
||||
|
||||
```text
|
||||
WO-11 全站 500 排查与兜底
|
||||
↓
|
||||
WO-12 导出点击失效修复
|
||||
↓
|
||||
WO-13 抓取进度透明化
|
||||
↓
|
||||
WO-14 Demo 数据方案
|
||||
↓
|
||||
WO-15 公网部署
|
||||
↓
|
||||
WO-16 UI 产品化改版
|
||||
↓
|
||||
WO-17 默认规模数据量解释优化
|
||||
```
|
||||
|
||||
原因：
|
||||
|
||||
- 500 和导出失效会直接破坏验收，优先级最高。
|
||||
- 进度透明化解决“黑盒运行”的核心体验问题。
|
||||
- Demo 数据和公网部署强相关，应该在部署前明确。
|
||||
- UI 改版适合在主链路稳定后进行，避免把 bug 和视觉修改混在一起。
|
||||
|
||||
## 15. MVP-2 待用户确认问题
|
||||
|
||||
以下问题需要用户确认后再进入对应工单开发：
|
||||
|
||||
1. 公网部署选择哪种方式：云服务器 Docker Compose、PaaS、还是临时内网穿透演示。
|
||||
2. 公网访问是否需要密码 / 简单登录。
|
||||
3. 公网用户是否允许直接消耗真实 TikHub 和 AI Key。
|
||||
4. Demo 数据使用真实抓取结果脱敏，还是使用模拟数据。
|
||||
5. 公网 demo 是否允许展示真实评论文本和作者昵称。
|
||||
6. 评论为空时，CSV 导出是下载只有表头的文件，还是按钮禁用并提示暂无评论。
|
||||
7. 任务进度是否需要显示预计剩余时间，还是只显示阶段、运行时长和最近更新时间。
|
||||
8. UI 风格方向：内部数据仪表盘，还是更偏演示型产品页面。
|
||||
|
||||
Reference in New Issue
Block a user