docs: 新增 MVP 工单推进计划

docs/MVP-WorkOrders.md

@@ -0,0 +1,613 @@
+# MVP 工单与版本推进计划
+
+## 1. 文档目的
+
+这份文档用于把后续开发从“零散修改”整理成“按工单推进”的节奏。
+
+每个工单代表一组相关目标。一个工单可以包含多个小改动，但必须有清晰边界、验收标准和对应 commit。开发时优先把当前工单做稳定，不要频繁切换到不相关问题。
+
+本项目当前最重要目标仍然是：让小红书 / 抖音热榜评论抓取工具在本机 Docker 环境下稳定跑通、页面可演示、报告可查看、数据可导出，最终达到可部署演示的产品化 MVP。
+
+## 2. 当前版本状态
+
+当前基线来自：
+
+- `9bad7b6 feat: 提交热榜评论分析工具 MVP 基线`
+
+已在 MVP-1 基线上追加的修复：
+
+- `0a3477c fix: 修复报告摘要生成并稳定默认端口`
+  - 修复报告摘要 AI 未接入导致总是显示“总结生成失败”的问题。
+  - 评论级 AI 使用 JSON Array prompt。
+  - 报告摘要 AI 使用纯文本 prompt。
+  - 抖音评论支持分页，不再只取第一页 20 条。
+  - Docker Compose 固定项目名 `hot-comments-tool`，稳定使用 `8000` 端口。
+
+- `b9291f9 fix: 增加任务详情自动刷新`
+  - 运行中任务详情页自动轮询任务状态。
+  - 任务成功或失败后自动刷新页面。
+  - 任务详情页“手动刷新”刷新当前页，不再跳回首页。
+
+当前验证记录：
+
+- 本地测试：`69 passed, 1 warning`
+- Docker 入口：`http://localhost:8000`
+- 健康检查：`GET /health -> {"status":"ok"}`
+- 小红书 `1 × 1 × 10` 真实任务已跑通一次，抓到 9 条真实评论，报告摘要正常生成。
+- 抖音默认参数 `5 × 5 × 50` 真实任务已跑通一次，但真实接口只返回 20 个可映射内容、237 条评论，未达到理论上限 25 个内容 / 1250 条评论。
+
+## 3. 推荐开发流程
+
+每次开始开发前，先确定当前要做的是哪一个工单。
+
+推荐流程：
+
+1. 选择一个工单。
+2. 明确本轮只做该工单范围内的事情。
+3. 写或更新测试。
+4. 修改代码。
+5. 跑本地测试。
+6. 重建 Docker 并在 `http://localhost:8000` 手工验收。
+7. 如果验收中发现同工单内 bug，继续修。
+8. 如果发现不相关 bug，记录到“后续工单 / 新问题”，不要打断当前工单。
+9. 工单达到验收标准后提交一个或几个 commit。
+
+推荐命令：
+
+```bash
+pytest tests/unit tests/integration -q
+docker compose up -d --build
+curl -f http://localhost:8000/health
+```
+
+## 4. Commit 规则
+
+一个工单可以对应一个 commit，也可以对应几个 commit。
+
+适合一个 commit 的情况：
+
+- 修改范围集中。
+- 验收标准一次性通过。
+- 回滚时希望整体回滚。
+
+适合多个 commit 的情况：
+
+- 一个工单里有多个清晰子目标。
+- 某个子目标已经独立稳定。
+- 后续问题修复和主要功能实现需要分开表达。
+
+Commit 信息建议：
+
+```text
+feat: 优化任务状态与进度体验
+fix: 修复报告页空状态展示
+fix: 修复抖音评论分页停止条件
+test: 补充真实任务状态轮询测试
+docs: 更新 MVP 工单计划
+```
+
+Commit 原则：
+
+- 不提交 `.env`、真实 API Key、真实 AI Key。
+- 不提交运行数据库文件，例如 `data/*.db`。
+- 不把不相关问题混进同一个 commit。
+- 每个 commit 信息要能回答：这次改动解决了什么目标。
+
+## 5. 验收分层
+
+每个工单完成前至少做以下验证：
+
+### 5.1 自动化测试
+
+必须跑：
+
+```bash
+pytest tests/unit tests/integration -q
+```
+
+如果改了报告、导出、平台抓取、AI 服务，应优先补对应测试。
+
+### 5.2 Docker 验收
+
+必须确认：
+
+```bash
+docker compose up -d --build
+curl -f http://localhost:8000/health
+```
+
+浏览器打开：
+
+```text
+http://localhost:8000
+```
+
+### 5.3 真实任务验收
+
+常用轻量验收：
+
+- 小红书：`1 热点 × 1 内容 × 10 评论`
+- 抖音：`1 热点 × 1 内容 × 10 评论`
+
+默认规模验收：
+
+- 小红书：`5 热点 × 5 内容 × 50 评论`
+- 抖音：`5 热点 × 5 内容 × 50 评论`
+
+注意：真实接口返回数量可能不足理论上限。验收时要区分：
+
+- 任务是否成功。
+- 是否有热点、内容、评论、报告入库。
+- AI 成功率是否正常。
+- 页面是否能展示和导出。
+- 实际返回不足是否来自平台数据本身。
+
+## 6. 工单总览
+
+| 编号 | 工单 | 优先级 | 目标 |
+|---|---|---|---|
+| WO-01 | 任务状态与进度体验优化 | P0 | 让长任务不再像卡住，状态清晰可见 |
+| WO-02 | 报告页和内容详情页产品化打磨 | P0 | 报告更像可演示产品，而不是工程输出 |
+| WO-03 | 双平台真实小规模验收 | P0 | 小红书 / 抖音 `1×1×10` 都稳定跑通 |
+| WO-04 | 双平台默认规模验收 | P0 | 小红书 / 抖音默认规模完成真实验收并记录限制 |
+| WO-05 | 失败、限流和跳过边界验证 | P0 | 429、超时、单条失败不拖垮任务 |
+| WO-06 | SQLite 数据库稳定性与恢复策略 | P0 | 避免数据库损坏、空表化和运行中任务误导 |
+| WO-07 | 导出链路验收与文件质量优化 | P1 | CSV / Markdown 导出稳定、命名清晰、内容一致 |
+| WO-08 | Docker 与部署前清理 | P1 | 固定启动方式、数据目录、环境变量和部署文档 |
+| WO-09 | 文档与用户操作说明 | P1 | 让非开发者也能启动、创建任务、查看报告 |
+| WO-10 | 发布候选版本验收 | P0 | 汇总所有验收，形成可演示 MVP 版本 |
+
+## 7. 工单详情
+
+### WO-01 任务状态与进度体验优化
+
+优先级：P0
+
+目标：
+
+- 用户创建任务后，页面能持续反馈任务是否仍在运行。
+- 任务成功、失败、中断后，页面能及时更新。
+- 用户能看到进度，不会误以为系统卡死。
+
+包含范围：
+
+- 任务详情页自动刷新。
+- 任务列表自动刷新。
+- 任务进度条或进度百分比。
+- 当前处理数量：成功 / 失败 / 总内容数。
+- 失败原因展示：阶段、错误类型、错误消息。
+- AI 成功率展示。
+
+边界情况：
+
+- `status=running` 且没有热点：显示“正在抓取热点数据”。
+- `status=running` 且已有热点或内容：显示当前进度，不只显示加载中。
+- `status=failed`：必须展示失败原因。
+- 系统重启导致任务中断：展示“系统重启，任务被中断”。
+- `analysis_status=insufficient`：任务仍可成功，但页面提示 AI 样本不足。
+
+验收标准：
+
+- 创建 `1×1×10` 任务后，任务详情页能自动从 running 变为 success 或 failed。
+- 不刷新浏览器也能看到最终状态。
+- 失败任务不再长期显示“正在抓取热点数据”。
+- 运行中任务列表能自动更新状态。
+
+建议 commit：
+
+```text
+feat: 优化任务状态与进度体验
+```
+
+当前状态：
+
+- 任务详情页自动刷新已完成。
+- 任务列表自动刷新、进度条、AI 成功率突出展示仍待做。
+
+### WO-02 报告页和内容详情页产品化打磨
+
+优先级：P0
+
+目标：
+
+- 报告页面更适合演示和阅读。
+- 用户能快速理解评论情绪、标签、典型评论和 AI 总结。
+
+包含范围：
+
+- 热点报告页布局优化。
+- 内容详情页布局优化。
+- AI 总结区域突出展示。
+- 情绪分布展示更直观。
+- Top 标签展示更清晰。
+- 评论列表展示情绪、标签、点赞数。
+- 报告尚未生成时的空状态。
+- 报告生成失败时的提示。
+
+边界情况：
+
+- 评论数量为 0。
+- AI 总结失败。
+- 报告记录不存在。
+- 标签为空。
+- AI 成功率低于 80%。
+- 内容条目失败但同热点下其他内容成功。
+
+验收标准：
+
+- 热点报告页能清楚展示摘要、样本数、情绪、标签、典型评论。
+- 内容详情页能清楚展示单条内容报告和评论明细。
+- 没有报告时不是空白或 500。
+- Markdown 导出内容与页面报告一致。
+
+建议 commit：
+
+```text
+feat: 打磨报告页和内容详情页
+```
+
+### WO-03 双平台真实小规模验收
+
+优先级：P0
+
+目标：
+
+- 小红书和抖音都能用真实 TikHub、真实 AI 跑通 `1×1×10`。
+
+包含范围：
+
+- 小红书真实任务验收。
+- 抖音真实任务验收。
+- 记录任务 ID、状态、热点数、内容数、评论数、报告数、AI 成功率。
+- 如果真实返回不足 10 条评论，记录实际返回数和原因判断。
+
+边界情况：
+
+- 平台返回 0 个热点。
+- 热点搜索不到内容。
+- 内容评论不足 10 条。
+- AI 请求失败或解析失败。
+- 报告摘要生成失败。
+
+验收标准：
+
+- 两个平台任务最终 `status=success`。
+- 至少有热点、内容、评论、报告入库。
+- AI 成功率正常，或有明确不足提示。
+- 页面能查看热点报告、内容详情和评论明细。
+
+建议 commit：
+
+```text
+test: 记录双平台小规模真实验收
+```
+
+### WO-04 双平台默认规模验收
+
+优先级：P0
+
+目标：
+
+- 验证默认规模 `5×5×50` 在真实接口下的表现。
+
+包含范围：
+
+- 小红书默认规模真实验收。
+- 抖音默认规模真实验收。
+- 记录任务结果和真实接口限制。
+- 区分“代码失败”和“平台返回不足”。
+
+边界情况：
+
+- 搜索每个热点返回内容不足 5 条。
+- 部分内容评论不足 50 条。
+- TikHub 429 限流。
+- TikHub 超时。
+- AI 调用耗时长。
+- SQLite 写入压力增加。
+
+验收标准：
+
+- 任务能完成或给出明确失败原因。
+- 成功内容条目都有报告。
+- 热点级报告生成。
+- AI 摘要不再出现批量兜底失败。
+- 对未达到理论数量的原因有记录。
+
+建议 commit：
+
+```text
+test: 记录双平台默认规模真实验收
+```
+
+### WO-05 失败、限流和跳过边界验证
+
+优先级：P0
+
+目标：
+
+- 确认单个接口失败不会拖垮整个任务。
+- 确认 429 和超时有重试和降级。
+
+包含范围：
+
+- TikHub 429 指数退避。
+- 评论分页中途失败处理。
+- 单个内容抓取失败后继续下一个内容。
+- AI 评论分析失败后标记该批次失败。
+- 报告摘要失败后使用默认文案，不阻断报告生成。
+
+边界情况：
+
+- 热点接口失败：任务失败。
+- 内容搜索失败：当前热点内容失败或跳过。
+- 评论接口失败：当前内容失败，其他内容继续。
+- AI 失败：评论标记 failed，任务可继续。
+- 报告摘要失败：报告仍创建。
+
+验收标准：
+
+- mock 测试覆盖失败路径。
+- 页面能展示失败阶段和错误类型。
+- 没有无意义的 500 页面。
+
+建议 commit：
+
+```text
+fix: 完善失败重试与跳过边界
+```
+
+### WO-06 SQLite 数据库稳定性与恢复策略
+
+优先级：P0
+
+目标：
+
+- 避免真实验收时出现数据库损坏、空表化、WAL 状态异常。
+- 数据库异常时能明确提示，而不是页面随机 500。
+
+包含范围：
+
+- 启动时数据库 integrity check。
+- 数据库损坏备份策略。
+- WAL / SHM 文件处理策略。
+- 运行中任务恢复逻辑。
+- 数据目录说明。
+- 验收库和正式库隔离建议。
+
+边界情况：
+
+- Docker 重启时任务正在运行。
+- `data/app.db` 损坏。
+- `app.db-wal` / `app.db-shm` 异常。
+- 本地脚本和 Docker 同时访问同一个 SQLite 文件。
+- 数据库为空但用户误以为历史数据还在。
+
+验收标准：
+
+- `PRAGMA integrity_check` 可执行。
+- Docker 重启后 running 任务被标记 failed，并显示明确原因。
+- 数据库异常不会让用户误以为任务还在抓取。
+- 文档说明如何重置本地验收数据库。
+
+建议 commit：
+
+```text
+fix: 增强 SQLite 数据库恢复与异常提示
+```
+
+### WO-07 导出链路验收与文件质量优化
+
+优先级：P1
+
+目标：
+
+- CSV / Markdown 导出可用于演示和交付。
+
+包含范围：
+
+- 内容评论 CSV。
+- 热点评论 CSV。
+- 内容报告 Markdown。
+- 热点报告 Markdown。
+- 文件名安全处理。
+- CSV 注入防护。
+- 报告不存在时禁用导出或返回友好错误。
+
+边界情况：
+
+- 评论内容以 `=`, `+`, `-`, `@` 开头。
+- 中文文件名。
+- 报告不存在。
+- 内容条目失败。
+- 评论为空。
+
+验收标准：
+
+- 浏览器点击导出能下载文件。
+- 文件名可读且安全。
+- Markdown 内容与页面一致。
+- CSV 用 Excel 打开不乱码。
+
+建议 commit：
+
+```text
+feat: 优化导出文件质量
+```
+
+### WO-08 Docker 与部署前清理
+
+优先级：P1
+
+目标：
+
+- 让启动、重建、部署方式稳定，不再出现端口混乱或多容器冲突。
+
+包含范围：
+
+- 固定 Docker Compose 项目名。
+- 固定端口 `8000`。
+- 数据目录挂载说明。
+- `.env` / `.env.example` 检查。
+- Docker 重建流程。
+- 部署前清理临时数据库。
+
+边界情况：
+
+- 旧容器占用 8000。
+- 不同项目名启动出两套容器。
+- `.env` 缺少 API Key。
+- Docker 容器内代码不是最新镜像。
+
+验收标准：
+
+- `docker compose up -d --build` 后只存在一个项目容器。
+- `http://localhost:8000/health` 返回 200。
+- 不再需要临时使用 8001。
+
+建议 commit：
+
+```text
+chore: 整理 Docker 启动与部署配置
+```
+
+当前状态：
+
+- 固定项目名和 8000 端口已完成。
+- 部署文档和数据清理流程仍待补充。
+
+### WO-09 文档与用户操作说明
+
+优先级：P1
+
+目标：
+
+- 让后续自己或其他人能按文档启动、验收、排查。
+
+包含范围：
+
+- 本地启动说明。
+- Docker 启动说明。
+- 创建任务说明。
+- 小规模验收说明。
+- 默认规模验收说明。
+- 常见问题。
+- 数据库重置说明。
+
+边界情况：
+
+- 端口占用。
+- API Key 缺失。
+- 任务长期 running。
+- 报告摘要失败。
+- 评论数量少于请求上限。
+- 数据库损坏或空表。
+
+验收标准：
+
+- 按文档可以从零启动服务。
+- 按文档可以完成一次小红书和抖音小规模验收。
+- 常见问题能指导用户判断下一步。
+
+建议 commit：
+
+```text
+docs: 补充本地验收和部署说明
+```
+
+### WO-10 发布候选版本验收
+
+优先级：P0
+
+目标：
+
+- 在所有 P0 工单完成后，形成一个可演示、可部署的 MVP 发布候选版本。
+
+包含范围：
+
+- 全量测试。
+- Docker 健康检查。
+- 双平台小规模验收。
+- 双平台默认规模验收。
+- 页面主链路验收。
+- 导出验收。
+- 已知问题清单。
+
+最终验收标准：
+
+- 首页能创建任务。
+- 任务运行状态清晰。
+- 小红书和抖音都能跑通真实任务。
+- 评论级 AI 情绪和标签正常。
+- 热点报告和内容报告都有 AI 总结。
+- 报告和评论页面可查看。
+- CSV 和 Markdown 可导出。
+- Docker 固定运行在 8000。
+- 数据库异常和任务失败有明确提示。
+- 文档说明如何启动、验收和排查。
+
+建议 commit：
+
+```text
+release: 标记 MVP 演示候选版本
+```
+
+## 8. 新问题处理规则
+
+验收时发现新问题，先判断归属：
+
+- 属于当前工单：直接修，和当前工单一起提交。
+- 不属于当前工单：记录到对应工单或新建问题，不立即切换。
+- 是阻塞主链路的问题：可以暂停当前工单，先开一个 `fix:` commit 处理。
+
+示例：
+
+- 当前做 WO-01，发现任务详情页不会刷新：属于当前工单，直接修。
+- 当前做 WO-01，发现 CSV 乱码：记录到 WO-07，不要马上切走。
+- 当前做任何工单，发现 Docker 起不来：阻塞验收，可先修 WO-08 相关问题。
+
+## 9. 建议后续推进顺序
+
+建议顺序：
+
+1. WO-01 任务状态与进度体验优化
+2. WO-02 报告页和内容详情页产品化打磨
+3. WO-03 双平台真实小规模验收
+4. WO-05 失败、限流和跳过边界验证
+5. WO-06 SQLite 数据库稳定性与恢复策略
+6. WO-04 双平台默认规模验收
+7. WO-07 导出链路验收与文件质量优化
+8. WO-08 Docker 与部署前清理
+9. WO-09 文档与用户操作说明
+10. WO-10 发布候选版本验收
+
+原因：
+
+- 先解决用户看得到的“卡住感”和状态透明。
+- 再打磨核心报告页面。
+- 再做真实接口验收和稳定性压测。
+- 最后整理部署、文档和发布候选版本。
+
+## 10. 每次工单完成后的记录模板
+
+完成一个工单后，在该工单下补充记录：
+
+```text
+完成日期：
+相关 commit：
+验证命令：
+真实任务 ID：
+验收结论：
+遗留问题：
+```
+
+示例：
+
+```text
+完成日期：2026-07-03
+相关 commit：b9291f9 fix: 增加任务详情自动刷新
+验证命令：pytest tests/unit tests/integration -q
+真实任务 ID：ba8c2bf1-ec69-408e-a328-f87db8e29f54
+验收结论：小红书 1×1×10 跑通，页面显示已完成，报告摘要正常
+遗留问题：任务列表自动刷新和进度条仍待做
+```