meijiali/hot_comment_radar

Fork 0

Files

T

meijiali 61bcb2ef86 fix: 优化报告未生成时的导出提示

2026-07-03 18:02:01 +08:00

60 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. 审阅决策摘要

本节来自 MVP-WorkOrders.md 综合审阅报告最终版，作为后续执行的约束。

审阅来源：

双份独立审阅意见合并：全栈专家 INTJ + Kiro。
决策人：用户。
审阅报告定稿时间：2025-07-10。

6.1 高置信度共识

重试 / 容错逻辑是真实验收硬前提：429 指数退避重试 1s -> 2s -> 4s、单条失败隔离、当前条目失败后继续处理，必须在真实环境验收前具备。
单条异常不得导致任务级崩溃：每条评论 / 每个内容条目处理必须隔离异常；AI 失败写入 ai_analysis_status=failed，不因单条异常升级为任务级 failure。
CSV 导出必须同时具备三重防护：公式注入防护、换行符替换、UTF-8-BOM 编码。
任务轮询必须有终止条件：任务进入 success 或 failed 后停止轮询，避免长期制造无意义请求。
Docker SQLite WAL 必须挂载整个目录：使用 ./data:/app/data，保证 .db、.db-wal、.db-shm 同目录持久化。

6.2 分歧决策

分歧项	决策	理由
WO-03 与 WO-05 执行顺序	折中：WO-05 核心逻辑内联为 WO-03 前置步骤，WO-05 保留边界 case 压测	小规模真实验收不能裸奔，但不把所有压测提前
`PRAGMA integrity_check` 配置开关	不加开关，MVP 阶段启动时始终执行	YAGNI，MVP 数据量下成本可接受
CSV 编码策略	统一 UTF-8-BOM	优先保证 Windows Excel 中文不乱码

6.3 确认行动清单

序号	行动	对应工单	优先级
1	指数退避重试 `1s -> 2s -> 4s` 和单条 try-catch 隔离内联到小规模真实验收前置步骤	WO-03	高
2	WO-05 范围缩减为边界 case 压测：连续 429 超限、全部失败降级、并发请求竞争	WO-05	中
3	CSV 导出添加公式注入前缀，首字符为 `= + - @` 时添加 `'`	WO-07	高
4	CSV 导出替换评论内容中的 `\n`、`\r` 为空格	WO-07	高
5	CSV 导出使用 UTF-8-BOM	WO-07	高
6	前端轮询在 `success` / `failed` 时停止	WO-01	中
7	Docker 挂载整个 `./data:/app/data` 目录	WO-08	中
8	AI 分析失败时 UI 展示空状态 / 默认文案，页面不返回 500	WO-02	中
9	后台线程中使用同步 `httpx.Client`，禁止 `httpx.AsyncClient`	WO-03 / WO-05	高
10	每个内容条目处理完立即 commit，不持有长事务	WO-03 / WO-04	中
11	`PRAGMA integrity_check` 启动时始终执行，不加配置开关	WO-06	低

6.4 保留的亮点

新问题处理规则保留：验收中发现不相关问题时先记录，不打断当前工单，防止范围蔓延。
文档工单化保留：用户操作说明作为独立 WO-09，不作为顺手补充，避免文档质量被压缩。
完成记录模板保留：每个工单完成后记录 commit、验证命令、真实任务 ID、验收结论和遗留问题。
导出安全意识保留：CSV 公式注入、换行和编码问题均纳入 WO-07 验收。

7. 工单总览

编号	工单	优先级	目标
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 版本

8. 工单详情

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

优先级：P0

目标：

用户创建任务后，页面能持续反馈任务是否仍在运行。
任务成功、失败、中断后，页面能及时更新。
用户能看到进度，不会误以为系统卡死。

包含范围：

任务详情页自动刷新。
任务列表自动刷新。
任务进度条或进度百分比。
当前处理数量：成功 / 失败 / 总内容数。
失败原因展示：阶段、错误类型、错误消息。
AI 成功率展示。
轮询终止条件：任务进入 success 或 failed 后停止轮询。

边界情况：

status=running 且没有热点：显示“正在抓取热点数据”。
status=running 且已有热点或内容：显示当前进度，不只显示加载中。
status=failed：必须展示失败原因。
系统重启导致任务中断：展示“系统重启，任务被中断”。
analysis_status=insufficient：任务仍可成功，但页面提示 AI 样本不足。

验收标准：

创建 1×1×10 任务后，任务详情页能自动从 running 变为 success 或 failed。
不刷新浏览器也能看到最终状态。
失败任务不再长期显示“正在抓取热点数据”。
运行中任务列表能自动更新状态。
任务终止后不继续轮询，不持续打 API。

建议 commit：

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

当前状态：

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

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

优先级：P0

目标：

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

包含范围：

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

边界情况：

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

验收标准：

热点报告页能清楚展示摘要、样本数、情绪、标签、典型评论。
内容详情页能清楚展示单条内容报告和评论明细。
没有报告时不是空白或 500。
AI 失败或样本不足时有可读提示，不显示异常堆栈。
Markdown 导出内容与页面报告一致。

建议 commit：

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

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

优先级：P0

目标：

在具备基础容错前提下，小红书和抖音都能用真实 TikHub、真实 AI 跑通 1×1×10。
WO-03 不允许裸奔进入真实环境，必须先确认基础重试、单条隔离和同步 HTTP client 约束。

包含范围：

前置内联：TikHub 429 指数退避重试 1s -> 2s -> 4s。
前置内联：单条评论 / 单个内容条目异常隔离，失败记录后继续处理。
前置内联：后台任务只使用同步 httpx.Client，禁止 httpx.AsyncClient。
前置内联：每个内容条目处理完立即 commit，不持有长事务。
小红书真实任务验收。
抖音真实任务验收。
记录任务 ID、状态、热点数、内容数、评论数、报告数、AI 成功率。
如果真实返回不足 10 条评论，记录实际返回数和原因判断。

边界情况：

平台返回 0 个热点。
热点搜索不到内容。
内容评论不足 10 条。
AI 请求失败或解析失败。
报告摘要生成失败。
单条评论乱码或字段缺失。
单个内容条目失败，但后续内容仍应继续。

验收标准：

两个平台任务最终 status=success。
至少有热点、内容、评论、报告入库。
AI 成功率正常，或有明确不足提示。
页面能查看热点报告、内容详情和评论明细。
单条评论 / 单个内容条目异常不会导致整个任务崩溃。
后台线程中不存在 httpx.AsyncClient 使用。

建议 commit：

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

完成记录：

完成日期：2026-07-03
相关 commit：test: 记录双平台小规模真实验收
验证命令：
- .venv/bin/python -m pytest tests/unit tests/integration -q
- .venv/bin/python -m pytest tests/unit tests/integration --cov=app --cov-branch --cov-report=term-missing
- docker compose up -d --build
- curl -f http://localhost:8000/health
真实任务 ID：
- 小红书：8ae106f4-64dc-4675-a021-f78092926ce6
- 抖音：b295f4b2-d546-4121-99bc-48d166d86bf4
验收结论：
- 小红书 1×1×10：status=success，热点 1，内容 1，评论 10，报告 2，AI 成功率 100%。
- 抖音 1×1×10：status=success，热点 1，内容 1，评论 10，报告 2，AI 成功率 100%。
- 页面可查看任务详情、热点报告、内容详情和评论明细。
- 自动化测试补充了连续 429 的 1s→2s→4s 退避断言，以及单个内容条目失败后继续处理后续条目的容错测试。
- 代码中未发现 httpx.AsyncClient 使用。
遗留问题：无；进入 WO-04 默认规模验收。

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

优先级：P0

目标：

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

包含范围：

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

边界情况：

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

验收标准：

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

建议 commit：

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

完成记录：

完成日期：2026-07-03
相关 commit：test: 记录双平台默认规模真实验收
验证命令：
- docker compose up -d --build
- curl -f http://localhost:8000/health
- 通过 /api/tasks 创建小红书、抖音默认规模任务并轮询至终态
- 通过任务详情页、热点 CSV/Markdown 导出、内容详情页抽样确认页面主链路
真实任务 ID：
- 小红书：4bdf36df-8ae4-4059-af98-602f4872dbaa
- 抖音：378b173a-a70f-4da1-b235-03e7632e614a
验收结论：
- 小红书 5×5×50：status=success，热点 5，内容 25/25 成功，评论 119，报告 30，AI 成功率 100%。
- 抖音 5×5×50：status=success，热点 5，内容 20/20 成功，评论 285，报告 25，AI 成功率约 82.46%。
- 两个平台均未达到理论上限 1250 条评论；原因判断为真实平台/接口返回内容与评论不足，而非任务失败。
- 页面可查看任务详情、热点报告、内容详情和评论明细；热点 Markdown、热点 CSV、内容 Markdown 抽样可导出。
遗留问题：
- 验收中观察到 Uvicorn 进程持有已删除的 SQLite WAL/SHM 文件句柄，导致独立脚本直读 /app/data/app.db 时暂时看不到新任务，但 Web/API 视图正常。归入 WO-06 处理。

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

优先级：P0

目标：

在 WO-03 已内联基础容错后，集中压测更极端的边界 case。
确认连续失败、全部失败、并发竞争等场景不会产生误导性状态或无意义 500。

包含范围：

连续 429 超过最大重试次数后的错误记录。
全部内容条目失败后的任务降级。
AI 全批失败后的 analysis_status=insufficient。
并发创建任务竞争：已有 running 时拒绝新任务。
评论分页中途失败处理。
报告摘要失败后使用默认文案，不阻断报告生成。
确认后台任务仍使用同步 httpx.Client。

边界情况：

热点接口失败：任务失败。
内容搜索失败：当前热点内容失败或跳过。
评论接口失败：当前内容失败，其他内容继续。
AI 失败：评论标记 failed，任务可继续。
报告摘要失败：报告仍创建。
连续 429 超限后：记录 rate_limited，不暴露 API Key。
所有内容失败后：任务 status=failed，错误原因可见。
同时发起两个任务：第二个应返回 400。

验收标准：

mock 测试覆盖失败路径。
连续 429、全部失败、并发竞争均有测试覆盖。
页面能展示失败阶段和错误类型。
没有无意义的 500 页面。

建议 commit：

fix: 完善失败重试与跳过边界

完成记录：

完成日期：2026-07-03
相关 commit：fix: 完善失败重试与跳过边界
验证命令：
- .venv/bin/python -m pytest tests/integration/test_failure_tolerance.py tests/unit/test_report_stats.py tests/integration/test_task_creation.py tests/unit/test_comment_pagination.py tests/unit/test_ai_schema.py -q
- .venv/bin/python -m pytest tests/unit tests/integration -q
- .venv/bin/python -m pytest tests/unit tests/integration --cov=app --cov-branch --cov-report=term-missing
- curl -f http://localhost:8000/health
验收结论：
- 连续 429 超限测试覆盖并断言退避序列 1s→2s→4s，错误类型为 rate_limited 且不泄露 API Key。
- 单个内容条目评论抓取失败时记录 failed item，后续内容继续处理，任务可成功。
- 所有内容条目失败时任务 status=failed，error_stage/error_type/error_message 可见。
- AI 全批失败已有测试覆盖：评论标记 failed，任务 analysis_status=insufficient。
- 报告摘要失败时 item/hotspot 报告仍创建，并使用默认总结文案。
- 已有 running 任务时拒绝新建任务，返回 400。
- 未发现 httpx.AsyncClient 使用。
遗留问题：W04 发现的 SQLite WAL/SHM deleted 句柄问题转入 WO-06。

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

优先级：P0

目标：

避免真实验收时出现数据库损坏、空表化、WAL 状态异常。
数据库异常时能明确提示，而不是页面随机 500。

包含范围：

启动时始终执行 PRAGMA integrity_check，不新增配置开关。
数据库损坏备份策略。
WAL / SHM 文件处理策略。
运行中任务恢复逻辑。
数据目录说明。
验收库和正式库隔离建议。

边界情况：

Docker 重启时任务正在运行。
data/app.db 损坏。
app.db-wal / app.db-shm 异常。
本地脚本和 Docker 同时访问同一个 SQLite 文件。
数据库为空但用户误以为历史数据还在。
PRAGMA integrity_check 返回非 ok。

验收标准：

PRAGMA integrity_check 可执行。
启动时默认执行 integrity check，不需要 DB_CHECK_ON_STARTUP 之类的开关。
Docker 重启后 running 任务被标记 failed，并显示明确原因。
数据库异常不会让用户误以为任务还在抓取。
文档说明如何重置本地验收数据库。

建议 commit：

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

完成记录：

完成日期：2026-07-03
相关 commit：fix: 增强 SQLite 数据库恢复与异常提示
验证命令：
- .venv/bin/python -m pytest tests/unit/test_db_stability.py tests/integration/test_task_recovery.py -q
- docker compose up -d --build
- curl -f http://localhost:8000/health
- docker compose exec -T app python 检查 PRAGMA integrity_check 与 wal_checkpoint(TRUNCATE)
- .venv/bin/python -m pytest tests/unit tests/integration -q
- .venv/bin/python -m pytest tests/unit tests/integration --cov=app --cov-branch --cov-report=term-missing
验收结论：
- 启动时执行 PRAGMA integrity_check，异常时抛出明确 RuntimeError，不新增配置开关。
- 启动建表后执行 PRAGMA wal_checkpoint(TRUNCATE)，将 WAL 写入主库并截断 WAL 文件。
- Docker 重建后，独立脚本可读到 WO-04 默认规模任务 4bdf36df-8ae4-4059-af98-602f4872dbaa 与 378b173a-a70f-4da1-b235-03e7632e614a。
- Uvicorn 进程不再持有 deleted app.db-wal/app.db-shm 文件句柄。
- Docker 重启后 running 任务恢复逻辑仍通过测试。
遗留问题：
- 数据库损坏备份策略和本地重置说明需要在 WO-09 用户操作文档中补充。

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

优先级：P1

目标：

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

包含范围：

内容评论 CSV。
热点评论 CSV。
内容报告 Markdown。
热点报告 Markdown。
文件名安全处理。
CSV 公式注入防护：首字符为 =, +, -, @ 时添加单引号前缀。
CSV 换行符处理：评论内容中的 \n、\r 替换为空格。
CSV 编码：统一使用 UTF-8-BOM。
报告不存在时禁用导出或返回友好错误。

边界情况：

评论内容以 =, +, -, @ 开头。
评论内容包含换行符或回车符。
中文文件名。
报告不存在。
内容条目失败。
评论为空。

验收标准：

浏览器点击导出能下载文件。
文件名可读且安全。
Markdown 内容与页面一致。
CSV 用 Windows Excel 打开中文不乱码。
CSV 中公式注入内容不会被 Excel 当公式执行。
CSV 中单条评论不会因换行破坏行结构。

建议 commit：

feat: 优化导出文件质量

完成记录：

完成日期：2026-07-03
相关 commit：feat: 优化导出文件质量
验证命令：
- .venv/bin/python -m pytest tests/unit/test_export.py tests/integration/test_routes.py::test_result_pages_render_seeded_data tests/integration/test_routes.py::test_report_pages_render_empty_state_when_report_missing tests/integration/test_routes.py::test_export_routes_return_csv_and_markdown -q
- .venv/bin/python -m pytest tests/unit tests/integration -q
- docker compose up -d --build
- curl -f http://localhost:8000/health
- 抽样检查内容 CSV UTF-8-BOM、CSV 列数、Markdown 总结章节和页面 downloadExport 按钮
- .venv/bin/python -m pytest tests/unit tests/integration --cov=app --cov-branch --cov-report=term-missing
验收结论：
- CSV 导出已覆盖 =、+、-、@ 公式注入前缀防护。
- CSV 导出会替换 \n、\r、\r\n，避免单条评论破坏行结构。
- CSV 导出使用 UTF-8-BOM，抽样文件以 BOM 开头。
- 热点/内容报告和评论导出按钮使用 downloadExport，报告缺失时 Markdown 按钮置灰并提示“报告尚未生成”。
- Markdown 导出读取预生成 report.markdown_content，抽样包含“## 总结”章节。
遗留问题：评论为空时 CSV 仍返回只有表头的文件，后续可在 WO-09 文档说明空文件语义。

WO-08 Docker 与部署前清理

优先级：P1

目标：

让启动、重建、部署方式稳定，不再出现端口混乱或多容器冲突。

包含范围：

固定 Docker Compose 项目名。
固定端口 8000。
数据目录挂载说明。
Docker Compose 挂载整个 ./data:/app/data 目录，不挂载单个 .db 文件。
.env / .env.example 检查。
Docker 重建流程。
部署前清理临时数据库。

边界情况：

旧容器占用 8000。
不同项目名启动出两套容器。
.env 缺少 API Key。
Docker 容器内代码不是最新镜像。
SQLite WAL 生成 .db-wal、.db-shm 文件。

验收标准：

docker compose up -d --build 后只存在一个项目容器。
http://localhost:8000/health 返回 200。
不再需要临时使用 8001。
docker-compose.yml 使用 ./data:/app/data 目录挂载，WAL 相关文件与主库同目录。

建议 commit：

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

当前状态：

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

完成记录：

完成日期：2026-07-03
相关 commit：chore: 整理 Docker 启动与部署配置
验证命令：
- .venv/bin/python -m pytest tests/unit/test_deployment_config.py -q
- docker compose ps
- curl -f http://localhost:8000/health
- .venv/bin/python -m pytest tests/unit tests/integration -q
验收结论：
- docker-compose.yml 固定 name: hot-comments-tool。
- 端口固定为 8000:8000，当前运行容器为 hot-comments-tool-app-1。
- docker-compose.yml 挂载 ./data:/app/data，未挂载单个 app.db 文件。
- 新增 docs/Deployment.md，说明启动、重建、端口占用、环境变量、数据目录和本地验收数据库重置流程。
遗留问题：无；WO-09 会继续补完整用户操作说明。

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

优先级：P1

目标：

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

包含范围：

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

边界情况：

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

验收标准：

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

建议 commit：

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

完成记录：

完成日期：2026-07-03
相关 commit：docs: 补充本地验收和部署说明
验证命令：
- .venv/bin/python -m pytest tests/unit/test_docs.py -q
- .venv/bin/python -m pytest tests/unit tests/integration -q
- curl -f http://localhost:8000/health
验收结论：
- 新增 docs/UserGuide.md，覆盖启动、创建任务、小规模验收、默认规模验收、报告查看、导出、常见问题和数据库重置。
- 用户指南明确固定入口 http://localhost:8000，说明不要临时改 8001。
- 文档说明 API Key 缺失、任务长期 running、评论数量少于上限、报告摘要失败等排查方式。
- 新增文档测试，防止关键章节被误删。
遗留问题：无；进入 WO-10 发布候选验收。

WO-10 发布候选版本验收

优先级：P0

目标：

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

包含范围：

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

最终验收标准：

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

建议 commit：

release: 标记 MVP 演示候选版本

完成记录：

完成日期：2026-07-03
相关 commit：release: 标记 MVP 演示候选版本
验证命令：
- .venv/bin/python -m pytest tests/unit tests/integration -q
- .venv/bin/python -m pytest tests/unit tests/integration --cov=app --cov-branch --cov-report=term-missing
- curl -f http://localhost:8000/health
- docker compose ps
- docker compose exec -T app python 检查 PRAGMA integrity_check 与 wal_checkpoint(TRUNCATE)
- 抽样检查任务详情页、热点报告页、内容详情页、CSV 导出、Markdown 导出
发布候选验收结论：
- 自动化测试：87 passed, 1 warning。
- 覆盖率：TOTAL 90%；重点模块 app/platforms/douyin.py 87%、app/platforms/xiaohongshu.py 83%、app/services/ai_service.py 95%、app/services/report_service.py 91%、app/services/export_service.py 92%。
- Docker：hot-comments-tool-app-1 运行在 http://localhost:8000，health 返回 ok。
- 数据库：integrity_check=ok，wal_checkpoint(TRUNCATE)=True。
- 小红书小规模 1×1×10：8ae106f4-64dc-4675-a021-f78092926ce6，success，内容 1/1，AI 成功率 100%。
- 抖音小规模 1×1×10：b295f4b2-d546-4121-99bc-48d166d86bf4，success，内容 1/1，AI 成功率 100%。
- 小红书默认规模 5×5×50：4bdf36df-8ae4-4059-af98-602f4872dbaa，success，内容 25/25，评论 119，报告 30，AI 成功率 100%。
- 抖音默认规模 5×5×50：378b173a-a70f-4da1-b235-03e7632e614a，success，内容 20/20，评论 285，报告 25，AI 成功率约 82.46%。
- 页面主链路：任务详情、热点报告、内容详情均可访问并展示 AI 总结、情绪分布、标签、典型评论和评论明细。
- 导出链路：CSV 带 UTF-8-BOM 且列结构正常，Markdown 包含“## 总结”章节。
已知问题：
- 默认规模评论数低于理论上限 1250，原因判断为真实平台/接口返回不足，不是任务失败。
- app/platforms/base.py 覆盖率为 76%，低于 80%，但不在本轮重点模块清单内；后续可针对网络错误和解析边界继续补测。

9. 新问题处理规则

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

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

示例：

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

10. 建议后续推进顺序

建议顺序：

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

原因：

先解决用户看得到的“卡住感”和状态透明。
再打磨核心报告页面。
再做带基础容错前置的小规模真实验收。
默认规模验收后，再用 WO-05 集中压测连续 429、全批失败、并发竞争等边界。
最后整理部署、文档和发布候选版本。

执行链路：

WO-01 任务详情页 + 轮询终止
  ↓
WO-02 数据可视化 + AI 失败空状态降级
  ↓
WO-03 小规模真实验收
  ├── 前置内联：429 指数退避
  ├── 前置内联：单条 try-catch 隔离
  └── 前置内联：httpx 同步 Client 确认
  ↓
WO-04 默认规模验收
  ↓
WO-05 边界 case 压测：连续 429 超限、全批失败降级、并发竞争
  ↓
WO-06 SQLite WAL + integrity_check，不加开关
  ↓
WO-07 导出：UTF-8-BOM + 公式注入防护 + 换行替换
  ↓
WO-08 Docker Compose + 目录挂载
  ↓
WO-09 文档与用户操作说明
  ↓
WO-10 收尾与 P1 评估

11. 与 AGENTS.md 约束的对齐确认

本工单计划与 AGENTS.md 的关键约束兼容：

MVP P0 功能不可裁剪：WO-03 内联基础容错，WO-05 保留边界压测。
后台任务使用同步 HTTP：WO-03 / WO-05 明确禁止 httpx.AsyncClient。
错误隔离：WO-03 要求单条评论 / 单个内容条目异常不升级为任务级崩溃。
报告预生成：WO-02 / WO-07 继续要求页面和导出读取同一份报告数据。
数据库与 Docker：WO-06 / WO-08 明确 WAL 目录挂载和启动时 integrity check。
测试优先：每个工单验收前必须运行 pytest tests/unit tests/integration -q，涉及核心服务时补对应测试。

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

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

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

示例：

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

13. MVP-2 新问题与产品化工单

本节记录 MVP 演示候选版本之后，用户在网页人工验收阶段发现的新问题和新增需求。

当前原则：

不覆盖 WO-01 到 WO-10 的完成记录。
新问题按 MVP-2 工单继续推进。
阻塞主链路的问题优先修复。
不清楚的产品决策必须先确认，不擅自替用户决定。
每个工单完成后继续按“完成日期 / commit / 验证命令 / 验收结论 / 遗留问题”记录。

MVP-2 工单总览

本轮用户反馈确认的主线工单如下。执行时先修本地核心链路，再做页面信息简化，最后进入公网部署；公网部署不是当前按钮 500、导出失效、任务卡住的根因，不能优先于本地可用性修复。

编号	工单	优先级	目标
WO-11	全站 Internal Server Error 排查与兜底	P0	解决点击按钮或刷新页面出现 500 的阻塞问题
WO-12	导出 Markdown / CSV 点击失效修复	P0	恢复报告和评论导出主链路
WO-13	抓取任务进度透明化与耗时预期	P0	降低长任务黑盒感，让用户知道任务是否真的在推进
WO-15	公网部署方案与上线验收	P0	本地核心链路稳定后，从本机 Docker 演示推进到可公网访问的部署
WO-16	UI 信息简化与产品化文案清理	P1	简化任务 ID、时间、规模、标题和错误文案，移除演示页脚
WO-18	长时间 running 但无进度排查	P0	定位任务是否真实运行，避免页面状态与数据库事实不一致

保留工单：WO-14 Demo 数据方案、WO-17 默认规模数据量解释、WO-19 前端错误提示统一仍可作为后续补充，但本轮不插队到上述主线之前。

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：

fix: 修复页面刷新和按钮点击的 500 错误

待确认：

用户需要提供或复现最容易触发 500 的页面 URL 与按钮名称；如果无法提供，则开发时先从当前浏览器打开的任务详情页开始排查。

完成记录：

完成日期：2026-07-03
相关改动：
- 补充路由回归测试，覆盖任务详情页、热点报告页、内容详情页、导出接口在数据库 I/O error 下的 503 兜底。
- 补充缺失任务、缺失热点、缺失内容页面的 404 兜底测试，确保不是裸 500。
- 核查当前实现已有 OperationalError / SQLAlchemyError 全局 handler：API 返回 503 JSON，HTML 页面返回数据库不可用友好页。
验证命令：
- docker cp tests/. hot-comments-tool-app-1:/app/tests/
- docker exec hot-comments-tool-app-1 sh -lc 'python -m pytest /app/tests/integration/test_routes.py -q'
验证结果：
- 19 passed, 1 warning
验收结论：
- 已知高频页面路由和导出入口在数据库 I/O error 下不会返回裸 Internal Server Error。
- 缺失任务、热点、内容不会返回 500。
- 服务端日志仍保留异常信息，页面/API 返回可理解错误。
遗留问题：
- 轮询接口偶发 503 时，前端当前只是静默返回，用户看不到“最近一次同步失败”提示；归入 WO-19 / WO-13 前端提示优化。
- 当前本机 Python .venv 仍未完成依赖安装，本轮测试通过运行容器执行。

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：

fix: 修复报告和评论导出点击失效

待确认：

评论为空时，用户希望“下载只有表头的 CSV”，还是“按钮禁用并提示暂无评论”。

完成记录：

完成日期：2026-07-03
相关改动：
- 在热点报告页和内容详情页的报告生成中状态增加可见提示：Markdown 报告将在分析完成后开放下载；评论 CSV 可先导出已抓取的数据。
- 保留 Markdown 按钮的 disabled 状态和 title，避免报告未生成时误触。
- 保留 CSV 导出入口，允许先导出已抓取评论。
- 补充集成测试，覆盖报告缺失时的可见提示和 CSV 入口。
验证命令：
- docker cp app/. hot-comments-tool-app-1:/app/app/
- docker cp tests/. hot-comments-tool-app-1:/app/tests/
- docker exec hot-comments-tool-app-1 sh -lc 'python -m pytest /app/tests/integration/test_routes.py -q'
- curl -s http://localhost:8000/hotspots/6fea3e86-5954-43b6-b727-33a03d3b418a/report | rg -n "Markdown 报告|导出热点评论 CSV|报告生成中|导出 Markdown"
- curl -s -D /tmp/wo12-csv-headers.txt http://localhost:8000/api/export/hotspots/6fea3e86-5954-43b6-b727-33a03d3b418a/comments.csv -o /tmp/wo12-hotspot-comments.csv
验证结果：
- 路由集成测试：19 passed, 1 warning
- 当前热点页显示 Markdown 未开放下载的解释文案。
- 当前热点 CSV 导出接口 GET 返回 200，Content-Disposition 包含 UTF-8 文件名，文件大小 4978 bytes。
- 当前热点 Markdown 导出仍返回 404 报告不存在，原因是该 running 任务尚未生成热点级报告；页面已给出可见解释。
验收结论：
- 报告未生成时，导出 Markdown 不再表现为“点不动”而无解释。
- CSV 可先导出已抓取评论。
遗留问题：
- 评论为空时继续沿用“下载只有表头的 CSV”的既有策略；如需改为禁用按钮，需要用户另行确认。
- 当前任务仍停在 AI 分析中，热点级 Markdown 需要任务完成并生成报告后才能下载；归入 WO-13 的进度透明化和卡住提示。

WO-13 抓取任务进度透明化与耗时预期

优先级：P0

背景：

用户反馈：开始抓取后虽然显示运行中，但不知道具体需要多少时间，也不知道系统是否真的在抓取。
当前体验仍有黑盒感，尤其是默认规模任务会等待较久。

目标：

让任务详情页清楚展示当前阶段、已完成数量、失败数量、最近更新时间和粗略耗时预期。
用户能判断任务是否仍在推进、是否卡住、卡在哪个阶段。

包含范围：

后端记录或计算任务阶段：
- 获取热点中
- 搜索内容中
- 抓取评论中
- AI 分析中
- 生成报告中
- 已完成 / 已失败
展示当前进度：
- 热点：已获取 / 目标
- 内容：已处理 / 总数
- 评论：已抓取数量
- AI：成功率 / 失败数
- 报告：已生成数量
展示任务开始时间、运行时长、最近更新时间。
给出非承诺式耗时提示，例如“小规模通常较快，默认规模可能需要数分钟，取决于 TikHub 与 AI 响应速度”。
如果一段时间没有进度更新，展示“可能仍在等待外部接口响应”的提示。

边界情况：

刚开始运行，热点还没入库。
已抓到热点但还没抓到内容。
某个内容失败但任务继续。
外部接口慢但未超时。
AI 请求慢。
Docker 重启导致任务中断。

验收标准：

创建任务后，任务详情页能看到阶段和进度数字变化。
用户不需要打开日志，也能知道任务大概处于哪个阶段。
任务长时间无变化时有提示，不再只显示“正在抓取热点数据，请稍候...”。
终态为 success / failed 后停止轮询。

建议 commit：

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：

feat: 增加可复现 demo 数据

待确认：

demo 数据使用真实抓取结果脱敏，还是使用模拟数据。
是否允许在公网演示中展示真实评论文本和作者昵称。
demo 数据是否需要提供“一键恢复”能力。

WO-15 公网部署方案与上线验收

优先级：P0

背景：

用户明确需要公网部署，而不仅是本机 Docker 访问。
本轮反馈确认：部署应排在本地核心功能稳定之后。先修复按钮 500、导出失效、running 卡住和进度黑盒，再把系统暴露给其他人使用。

目标：

选择并落地公网部署方式，提供可访问 URL。
确保环境变量、数据目录、端口、健康检查、重启策略清楚可靠。

包含范围：

确认部署目标：
- 云服务器 Docker Compose
- PaaS 平台
- 内网穿透 / 临时演示链接
配置环境变量和密钥管理。
配置持久化数据目录。
配置反向代理或公网端口。
配置健康检查和重启策略。
更新部署文档。

边界情况：

API Key 不应暴露在仓库或页面。
公网访问可能产生额外抓取成本。
多人同时点击创建任务。
SQLite 在公网多人使用下的并发限制。
没有登录权限时，任何知道地址的人都能创建抓取任务。

验收标准：

用户可以通过公网 URL 打开首页。
公网环境能查看 demo 数据。
公网环境能创建至少一个小规模任务。
健康检查可访问。
重启后数据不丢失，或文档明确说明数据生命周期。

建议 commit：

docs: 补充公网部署方案

或如果包含实际部署配置：

chore: 增加公网部署配置

待确认：

部署平台选择。
是否需要访问密码 / 简单登录。
是否允许公网用户直接消耗真实 TikHub 和 AI Key。
是否需要限制同一时间只能运行一个任务。

WO-16 UI 信息简化与产品化文案清理

优先级：P1

背景：

用户明确希望后续修改 UI。
当前页面主链路可用，但仍需要提升产品化观感。
本轮明确反馈：任务 ID、创建时间、创建规模、任务名称和失败原因显示过长或过技术化，影响实际使用。

目标：

在不破坏功能的前提下，让首页、任务列表、任务详情、报告页、内容详情页更适合实际使用和演示。
列表和详情页默认展示短编号，避免直接暴露完整 UUID。
清理用户界面上的内部英文错误枚举和演示性质文案。

包含范围：

任务 ID 展示为顺序号，例如 #1、#2、#3；完整 UUID 只保留在详情或排查信息中。
创建时间展示为 YYYY-MM-DD HH:mm，不显示秒、毫秒或时区冗余字符。
创建规模展示为紧凑格式，例如 小红书 · 5热点 × 5内容 × 50评论。
任务列表、任务详情标题和面包屑不要出现过长字符串。
失败状态不直接展示 system / unexpected_restart 等内部英文枚举；改为中文解释或隐藏技术细节。
移除页脚 内部演示工具 | 仅供学习参考。
保持首页、任务列表、任务详情、报告页、内容详情页基本布局稳定，避免把 UI 清理和大规模视觉重设计混在一起。

边界情况：

文本过长。
评论列表很多。
无报告 / 无评论 / AI 失败。
默认规模任务 running 很久。
导出按钮不可用。

验收标准：

页面不会出现文字重叠、按钮挤压、信息难以扫描。
主要 CTA 明确。
运行中和失败态清楚。
UI 改动不影响创建任务、查看报告和导出。
任务列表和详情页默认显示顺序号，不直接铺开完整 UUID。
创建时间、创建规模和任务标题短而可读。
用户界面不出现 system / unexpected_restart 等内部错误枚举。
页脚不再展示 内部演示工具 | 仅供学习参考。

建议 commit：

feat: 优化 MVP 页面产品化体验

待确认：

UI 风格方向：更偏数据仪表盘、内部工具，还是偏演示型产品页面。
是否需要提供简单品牌名 / Logo / 说明文案。

WO-17 默认规模数据量解释与展示优化

优先级：P1

背景：

默认规模理论值是 5×5×50=1250 评论，但真实任务不一定达到。
用户判断这更可能是笔记 / 视频本身评论不足，而不是接口错误。

目标：

在 UI 和文档中清楚解释“目标上限”和“实际返回”的区别。
避免用户看到少于 1250 就误以为任务失败。

包含范围：

任务详情页展示：
- 配置目标：5 热点 × 5 内容 × 50 评论
- 实际结果：实际热点、实际内容、实际评论
- 不足原因提示：平台内容 / 评论不足、接口返回不足、部分内容失败
报告页展示样本数，避免将样本不足包装成完整全量分析。
文档补充默认规模解释。

边界情况：

某个热点只有少量内容。
某条内容本身评论不足 50。
API 返回空评论但内容存在。
部分内容失败导致评论不足。

验收标准：

用户能区分“抓取上限”和“实际抓到数量”。
默认规模任务少于 1250 时，页面给出合理说明。
真实失败和自然不足有不同提示。

建议 commit：

feat: 展示默认规模目标与实际抓取差异

待确认：

是否需要在报告里显示“样本不足，不代表完整舆情”的提示。

WO-18 长时间 running 但无进度排查

优先级：P0

背景：

用户反馈任务详情页显示“运行中”，但等待接近 3 小时仍无明显进度。
用户提供的任务 ID：d1107382-9343-4d8f-9f4f-a1232712bacb。
2026-07-03 本地核查结果：
- data/app.db 中该任务记录不存在。
- 该任务对应的热点、内容、评论、报告数量均为 0。
- 当前 data/app.db 仍是旧 schema，tasks 表缺少 current_stage 和 last_progress_at 字段。
- Docker 日志中出现过针对该任务 ID 的 SQL 查询，并伴随 sqlite3.OperationalError: disk I/O error。
这说明当前问题不能简单归类为“TikHub 慢”，需要先确认页面、容器、数据库文件和任务状态是否一致。

依赖：

依赖 WO-11 中的数据库 I/O 兜底与恢复策略。
依赖 WO-13 中的任务阶段和最近进度字段。
依赖 Docker 当前只运行一套 hot-comments-tool-app-1 容器。
开发前必须先确认当前浏览器页面访问的是最新容器和最新镜像。

目标：

明确判断一个显示为 running 的任务到底是否真实存在、是否仍有后台线程在执行、是否已经被数据库错误中断。
页面不再只显示“运行中”，而是能显示最近进度时间、阶段、已抓数量和卡住提示。
对数据库中不存在的任务 ID，页面应显示“任务不存在或数据已恢复/迁移”，而不是长期运行中。

包含范围：

增加任务详情排查命令或文档步骤：
- 查 tasks 表。
- 查热点、内容、评论、报告数量。
- 查最近容器日志。
- 查 DB schema 是否包含进度字段。
后端在启动时确保旧 SQLite 自动补齐 current_stage、last_progress_at。
如果旧页面打开了不存在的任务 ID，应返回清晰 404 页面或友好提示。
如果任务 running 但 last_progress_at 长时间不变，应在页面提示“可能等待外部接口或后台任务已异常，请查看日志/刷新状态”。
记录一次针对 d1107382-9343-4d8f-9f4f-a1232712bacb 的复盘结果。

边界情况：

浏览器打开的是旧任务 URL，但数据库已经恢复或切换。
Docker 容器运行的是旧镜像，本地代码已经更新但容器没有 rebuild。
SQLite WAL / SHM 文件和主库不一致导致查询异常。
后台线程已停止，但任务状态仍停留在 running。
任务记录存在，但所有计数都为 0。
任务记录不存在，但前端仍在轮询该 ID。

验收标准：

对 d1107382-9343-4d8f-9f4f-a1232712bacb 的状态有明确结论，并写入完成记录。
不存在的任务详情页不会误导用户以为仍在抓取。
running 任务页面能看到阶段、最近进度时间和数量。
running 任务长时间无变化时，页面出现明确提示。
Docker 重建后旧 DB schema 自动补齐进度字段。

建议 commit：

fix: 排查并修复任务 running 无进度状态

Git 流程：

从当前 MVP-2 commit 后开始新改动。
先提交测试或复现记录，再提交修复代码。
完成后运行相关测试和 Docker 健康检查。
单独 commit，不与 UI 大改或公网部署混在一起。
验收通过后再 push。

待确认：

对“长时间无变化”的阈值，第一版是否使用 10 分钟作为提示阈值。
不存在的任务 ID 页面是否保留 404，还是跳回首页并显示提示。

完成记录：

完成日期：2026-07-03
相关 commit：本记录对应 WO-18 排查与运行环境恢复，代码侧未新增业务逻辑；当前源码中已有 ensure_sqlite_schema_compat()、hydrate_task_progress() 和启动恢复 running 任务逻辑。
核查任务 ID：d1107382-9343-4d8f-9f4f-a1232712bacb
核查结论：
- data/app.db 中该任务记录不存在。
- 该任务对应热点、内容、评论、报告数量均为 0。
- 旧运行容器中的 app.db 模块缺少 ensure_sqlite_schema_compat()，说明浏览器访问的是旧镜像 / 旧代码。
- 旧 data/app.db 的 tasks 表缺少 current_stage 和 last_progress_at 字段，旧容器不会自动补齐。
- 点击该任务页和报告页出现 500 的直接错误是 sqlite3.OperationalError: disk I/O error。
- 将当前 app/ 代码同步到正在运行的容器并重启后，旧库已自动补齐 current_stage 和 last_progress_at 字段。
- 同步后 /tasks/d1107382-9343-4d8f-9f4f-a1232712bacb 返回 200，并显示失败状态“系统重启，任务被中断”，不再无限显示 running。
- 同步后 /hotspots/914665b3-258d-417c-9e5d-f627acdfb99e/report 返回 200。
验证命令：
- docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'
- curl -i -s http://localhost:8000/health
- sqlite3 data/app.db ".schema tasks"
- sqlite3 data/app.db "SELECT ... FROM tasks WHERE id='d1107382-9343-4d8f-9f4f-a1232712bacb';"
- curl -i -s http://localhost:8000/tasks/d1107382-9343-4d8f-9f4f-a1232712bacb
- curl -i -s http://localhost:8000/hotspots/914665b3-258d-417c-9e5d-f627acdfb99e/report
验收结论：
- WO-18 的主要根因是运行容器未加载当前代码，叠加旧 SQLite schema 和 SQLite I/O 异常。
- 当前本机服务已恢复到可访问状态，旧任务不再表现为无限 running。
- tasks 表已具备 current_stage 和 last_progress_at 字段。
遗留问题：
- docker compose up -d --build 因构建阶段下载 uv 网络卡住被中断，本轮采用 docker cp app/. hot-comments-tool-app-1:/app/app/ && docker restart hot-comments-tool-app-1 临时同步运行环境；后续 WO-15 部署前仍需完成一次正常镜像重建。
- 本机 .venv 缺少依赖，uv run pytest ... 因依赖下载卡住未完成；需要在网络恢复后补跑自动化测试。
- 页面仍显示长 UUID、内部错误枚举和页脚演示文案，这些归入 WO-16。
- 全站数据库异常友好兜底仍归入 WO-11 / WO-19，不在 WO-18 内混修。

WO-19 Internal Network Error / 500 统一排查与前端错误提示

优先级：P0

背景：

用户反馈点击查找、刷新、导出等功能时会看到 Internal Network Error 或 Internal Server Error。
当前 Docker 日志已确认首页请求曾因 sqlite3.OperationalError: disk I/O error 返回 500。
MVP-2 已新增数据库异常兜底，但当前运行容器可能仍是旧镜像，且前端对不同失败类型的提示还不够统一。

依赖：

依赖 WO-11 的数据库异常处理、备份和恢复策略。
依赖 WO-12 的导出失败前端提示。
依赖 WO-18 先确认当前容器、数据库和任务状态一致。
需要保留服务端详细日志，不能为了前端友好提示吞掉真实错误。

目标：

区分并展示三类错误：
- 数据库不可用：提示“数据库暂时不可用，正在恢复或请稍后重试”。
- 网络请求失败：提示“网络连接异常，请检查服务是否运行”。
- 业务不可用：例如报告不存在、任务已存在 running、参数错误。
前端按钮不再“点不动”或静默失败。
页面刷新和局部 API 失败时，不直接暴露裸 500。

包含范围：

梳理所有前端 fetch 调用：
- 创建任务。
- 任务详情轮询。
- 任务列表轮询。
- Markdown / CSV 导出。
为非 2xx 响应读取 detail 并展示。
为网络异常展示统一文案。
后端 API 错误统一返回 JSON { "detail": "..." }。
页面路由发生数据库异常时展示友好错误页。
增加测试覆盖：
- /api/tasks 数据库异常返回 503 JSON。
- 页面路由数据库异常返回 503 友好页。
- 导出接口 404 / 503 前端能提示明确原因。

边界情况：

服务未启动，浏览器 fetch 直接失败。
容器正在重启，短时间连接被拒绝。
数据库 I/O error。
任务不存在。
报告尚未生成。
评论为空但 CSV 仍应下载表头。
轮询接口失败时不能无限弹窗打扰用户。

验收标准：

点击创建任务、刷新、导出、查看报告时，失败都有明确提示。
数据库异常不再展示裸 Internal Server Error 页面。
导出按钮失败后能恢复可点击状态。
轮询失败时页面有温和提示，不误报任务完成。
服务端日志仍保留完整异常栈，方便继续排查。

建议 commit：

fix: 统一网络和服务端错误提示

Git 流程：

独立于 WO-18 提交，避免把任务状态修复和全局错误提示混在一起。
每完成一个错误入口的修复，可以按需拆成小 commit。
每个 commit 信息写清楚入口，例如 fix: 优化导出失败提示、fix: 优化任务轮询错误提示。
本地验收后再 push。

待确认：

前端错误提示第一版使用页面内 alert 区域，还是保留浏览器 alert()。
轮询失败是否需要显示“最近一次状态同步失败”的时间。

14. MVP-2 推荐执行顺序

建议先处理阻塞主链路和演示可信度的问题：

WO-18 长时间 running 但无进度排查
  ↓
WO-11 全站 500 排查与兜底
  ↓
WO-12 导出点击失效修复
  ↓
WO-13 抓取进度透明化
  ↓
WO-16 UI 信息简化与产品化文案清理
  ↓
WO-15 公网部署

原因：

500 和导出失效会直接破坏验收，优先级最高。
当前验收中新发现 running 状态和数据库事实不一致，因此 WO-18 / WO-19 应先于继续做公网部署和 UI 大改。
进度透明化解决“黑盒运行”的核心体验问题。
UI 信息简化适合在主链路稳定后进行，避免把 bug 和展示修改混在一起。
公网部署排在最后，避免把本地已知坏链路发布出去。

15. MVP-2 待用户确认问题

以下问题需要用户确认后再进入对应工单开发：

WO-18：对“长时间无变化”的提示阈值，第一版是否使用 10 分钟。
WO-18：不存在的任务 ID 页面保留 404，还是跳回首页并显示提示。
WO-12：评论为空时，CSV 导出是下载只有表头的文件，还是按钮禁用并提示暂无评论。
WO-13：任务进度是否需要显示预计剩余时间，还是只显示阶段、运行时长和最近更新时间。
WO-15：公网部署选择哪种方式：云服务器 Docker Compose、PaaS、还是临时内网穿透演示。
WO-15：公网访问是否需要密码 / 简单登录。
WO-15：公网用户是否允许直接消耗真实 TikHub 和 AI Key。
WO-16：后续如果做大规模视觉改版，UI 风格方向是内部数据仪表盘，还是更偏演示型产品页面。

已确认默认：

任务 ID 展示采用顺序号 #1/#2/#3，完整 UUID 只保留在详情或排查信息中。
本轮问题记录在 docs/MVP-WorkOrders.md，不新建 docs/IssueInbox.md。
公网部署排在本地核心功能稳定之后。
文档或代码无法确认的问题必须先询问用户，不擅自决定产品行为。

60 KiB Raw Blame History Unescape Escape

MVP 工单与版本推进计划

1. 文档目的

2. 当前版本状态

3. 推荐开发流程

4. Commit 规则

5. 验收分层

5.1 自动化测试

5.2 Docker 验收

5.3 真实任务验收

6. 审阅决策摘要

6.1 高置信度共识

6.2 分歧决策

6.3 确认行动清单

6.4 保留的亮点

7. 工单总览

8. 工单详情

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

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

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

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

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

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

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

WO-08 Docker 与部署前清理

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

WO-10 发布候选版本验收

9. 新问题处理规则

10. 建议后续推进顺序

11. 与 AGENTS.md 约束的对齐确认

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

13. MVP-2 新问题与产品化工单

MVP-2 工单总览

WO-11 全站 Internal Server Error 排查与兜底

WO-12 导出 Markdown / CSV 点击失效修复

WO-13 抓取任务进度透明化与耗时预期

WO-14 Demo 数据保留与新任务并存体验

WO-15 公网部署方案与上线验收

WO-16 UI 信息简化与产品化文案清理

WO-17 默认规模数据量解释与展示优化

WO-18 长时间 running 但无进度排查

WO-19 Internal Network Error / 500 统一排查与前端错误提示

14. MVP-2 推荐执行顺序

15. MVP-2 待用户确认问题

60 KiB

Raw Blame History