feat: 完善 MVP-2 演示和进度体验

docs/MVP-WorkOrders.md

@@ -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 风格方向：内部数据仪表盘，还是更偏演示型产品页面。