meijiali/hot_comment_radar

Fork 0

Files

T

meijiali f756eacf39 docs: 新增 MVP 工单推进计划

2026-07-03 13:50:03 +08:00

16 KiB

Raw Blame History

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. 推荐开发流程

每次开始开发前，先确定当前要做的是哪一个工单。

推荐流程：

选择一个工单。
明确本轮只做该工单范围内的事情。
写或更新测试。
修改代码。
跑本地测试。
重建 Docker 并在 http://localhost:8000 手工验收。
如果验收中发现同工单内 bug，继续修。
如果发现不相关 bug，记录到“后续工单 / 新问题”，不要打断当前工单。
工单达到验收标准后提交一个或几个 commit。

推荐命令：

pytest tests/unit tests/integration -q
docker compose up -d --build
curl -f http://localhost:8000/health

4. Commit 规则

一个工单可以对应一个 commit，也可以对应几个 commit。

适合一个 commit 的情况：

修改范围集中。
验收标准一次性通过。
回滚时希望整体回滚。

适合多个 commit 的情况：

一个工单里有多个清晰子目标。
某个子目标已经独立稳定。
后续问题修复和主要功能实现需要分开表达。

Commit 信息建议：

feat: 优化任务状态与进度体验
fix: 修复报告页空状态展示
fix: 修复抖音评论分页停止条件
test: 补充真实任务状态轮询测试
docs: 更新 MVP 工单计划

Commit 原则：

不提交 .env、真实 API Key、真实 AI Key。
不提交运行数据库文件，例如 data/*.db。
不把不相关问题混进同一个 commit。
每个 commit 信息要能回答：这次改动解决了什么目标。

5. 验收分层

每个工单完成前至少做以下验证：

5.1 自动化测试

必须跑：

pytest tests/unit tests/integration -q

如果改了报告、导出、平台抓取、AI 服务，应优先补对应测试。

5.2 Docker 验收

必须确认：

docker compose up -d --build
curl -f http://localhost:8000/health

浏览器打开：

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：

feat: 优化任务状态与进度体验

当前状态：

任务详情页自动刷新已完成。
任务列表自动刷新、进度条、AI 成功率突出展示仍待做。

WO-02 报告页和内容详情页产品化打磨

优先级：P0

目标：

报告页面更适合演示和阅读。
用户能快速理解评论情绪、标签、典型评论和 AI 总结。

包含范围：

热点报告页布局优化。
内容详情页布局优化。
AI 总结区域突出展示。
情绪分布展示更直观。
Top 标签展示更清晰。
评论列表展示情绪、标签、点赞数。
报告尚未生成时的空状态。
报告生成失败时的提示。

边界情况：

评论数量为 0。
AI 总结失败。
报告记录不存在。
标签为空。
AI 成功率低于 80%。
内容条目失败但同热点下其他内容成功。

验收标准：

热点报告页能清楚展示摘要、样本数、情绪、标签、典型评论。
内容详情页能清楚展示单条内容报告和评论明细。
没有报告时不是空白或 500。
Markdown 导出内容与页面报告一致。

建议 commit：

feat: 打磨报告页和内容详情页

WO-03 双平台真实小规模验收

优先级：P0

目标：

小红书和抖音都能用真实 TikHub、真实 AI 跑通 1×1×10。

包含范围：

小红书真实任务验收。
抖音真实任务验收。
记录任务 ID、状态、热点数、内容数、评论数、报告数、AI 成功率。
如果真实返回不足 10 条评论，记录实际返回数和原因判断。

边界情况：

平台返回 0 个热点。
热点搜索不到内容。
内容评论不足 10 条。
AI 请求失败或解析失败。
报告摘要生成失败。

验收标准：

两个平台任务最终 status=success。
至少有热点、内容、评论、报告入库。
AI 成功率正常，或有明确不足提示。
页面能查看热点报告、内容详情和评论明细。

建议 commit：

test: 记录双平台小规模真实验收

WO-04 双平台默认规模验收

优先级：P0

目标：

验证默认规模 5×5×50 在真实接口下的表现。

包含范围：

小红书默认规模真实验收。
抖音默认规模真实验收。
记录任务结果和真实接口限制。
区分“代码失败”和“平台返回不足”。

边界情况：

搜索每个热点返回内容不足 5 条。
部分内容评论不足 50 条。
TikHub 429 限流。
TikHub 超时。
AI 调用耗时长。
SQLite 写入压力增加。

验收标准：

任务能完成或给出明确失败原因。
成功内容条目都有报告。
热点级报告生成。
AI 摘要不再出现批量兜底失败。
对未达到理论数量的原因有记录。

建议 commit：

test: 记录双平台默认规模真实验收

WO-05 失败、限流和跳过边界验证

优先级：P0

目标：

确认单个接口失败不会拖垮整个任务。
确认 429 和超时有重试和降级。

包含范围：

TikHub 429 指数退避。
评论分页中途失败处理。
单个内容抓取失败后继续下一个内容。
AI 评论分析失败后标记该批次失败。
报告摘要失败后使用默认文案，不阻断报告生成。

边界情况：

热点接口失败：任务失败。
内容搜索失败：当前热点内容失败或跳过。
评论接口失败：当前内容失败，其他内容继续。
AI 失败：评论标记 failed，任务可继续。
报告摘要失败：报告仍创建。

验收标准：

mock 测试覆盖失败路径。
页面能展示失败阶段和错误类型。
没有无意义的 500 页面。

建议 commit：

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：

fix: 增强 SQLite 数据库恢复与异常提示

WO-07 导出链路验收与文件质量优化

优先级：P1

目标：

CSV / Markdown 导出可用于演示和交付。

包含范围：

内容评论 CSV。
热点评论 CSV。
内容报告 Markdown。
热点报告 Markdown。
文件名安全处理。
CSV 注入防护。
报告不存在时禁用导出或返回友好错误。

边界情况：

评论内容以 =, +, -, @ 开头。
中文文件名。
报告不存在。
内容条目失败。
评论为空。

验收标准：

浏览器点击导出能下载文件。
文件名可读且安全。
Markdown 内容与页面一致。
CSV 用 Excel 打开不乱码。

建议 commit：

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：

chore: 整理 Docker 启动与部署配置

当前状态：

固定项目名和 8000 端口已完成。
部署文档和数据清理流程仍待补充。

WO-09 文档与用户操作说明

优先级：P1

目标：

让后续自己或其他人能按文档启动、验收、排查。

包含范围：

本地启动说明。
Docker 启动说明。
创建任务说明。
小规模验收说明。
默认规模验收说明。
常见问题。
数据库重置说明。

边界情况：

端口占用。
API Key 缺失。
任务长期 running。
报告摘要失败。
评论数量少于请求上限。
数据库损坏或空表。

验收标准：

按文档可以从零启动服务。
按文档可以完成一次小红书和抖音小规模验收。
常见问题能指导用户判断下一步。

建议 commit：

docs: 补充本地验收和部署说明

WO-10 发布候选版本验收

优先级：P0

目标：

在所有 P0 工单完成后，形成一个可演示、可部署的 MVP 发布候选版本。

包含范围：

全量测试。
Docker 健康检查。
双平台小规模验收。
双平台默认规模验收。
页面主链路验收。
导出验收。
已知问题清单。

最终验收标准：

首页能创建任务。
任务运行状态清晰。
小红书和抖音都能跑通真实任务。
评论级 AI 情绪和标签正常。
热点报告和内容报告都有 AI 总结。
报告和评论页面可查看。
CSV 和 Markdown 可导出。
Docker 固定运行在 8000。
数据库异常和任务失败有明确提示。
文档说明如何启动、验收和排查。

建议 commit：

release: 标记 MVP 演示候选版本

8. 新问题处理规则

验收时发现新问题，先判断归属：

属于当前工单：直接修，和当前工单一起提交。
不属于当前工单：记录到对应工单或新建问题，不立即切换。
是阻塞主链路的问题：可以暂停当前工单，先开一个 fix: commit 处理。

示例：

当前做 WO-01，发现任务详情页不会刷新：属于当前工单，直接修。
当前做 WO-01，发现 CSV 乱码：记录到 WO-07，不要马上切走。
当前做任何工单，发现 Docker 起不来：阻塞验收，可先修 WO-08 相关问题。

9. 建议后续推进顺序

建议顺序：

WO-01 任务状态与进度体验优化
WO-02 报告页和内容详情页产品化打磨
WO-03 双平台真实小规模验收
WO-05 失败、限流和跳过边界验证
WO-06 SQLite 数据库稳定性与恢复策略
WO-04 双平台默认规模验收
WO-07 导出链路验收与文件质量优化
WO-08 Docker 与部署前清理
WO-09 文档与用户操作说明
WO-10 发布候选版本验收

原因：

先解决用户看得到的“卡住感”和状态透明。
再打磨核心报告页面。
再做真实接口验收和稳定性压测。
最后整理部署、文档和发布候选版本。

10. 每次工单完成后的记录模板

完成一个工单后，在该工单下补充记录：

完成日期：
相关 commit：
验证命令：
真实任务 ID：
验收结论：
遗留问题：

示例：

完成日期：2026-07-03
相关 commit：b9291f9 fix: 增加任务详情自动刷新
验证命令：pytest tests/unit tests/integration -q
真实任务 ID：ba8c2bf1-ec69-408e-a328-f87db8e29f54
验收结论：小红书 1×1×10 跑通，页面显示已完成，报告摘要正常
遗留问题：任务列表自动刷新和进度条仍待做

16 KiB Raw Blame History Unescape Escape

MVP 工单与版本推进计划

1. 文档目的

2. 当前版本状态

3. 推荐开发流程

4. Commit 规则

5. 验收分层

5.1 自动化测试

5.2 Docker 验收

5.3 真实任务验收

6. 工单总览

7. 工单详情

WO-01 任务状态与进度体验优化

WO-02 报告页和内容详情页产品化打磨

WO-03 双平台真实小规模验收

WO-04 双平台默认规模验收

WO-05 失败、限流和跳过边界验证

WO-06 SQLite 数据库稳定性与恢复策略

WO-07 导出链路验收与文件质量优化

WO-08 Docker 与部署前清理

WO-09 文档与用户操作说明

WO-10 发布候选版本验收

8. 新问题处理规则

9. 建议后续推进顺序

10. 每次工单完成后的记录模板

16 KiB

Raw Blame History