meijiali/hot_comment_radar

Fork 0

Files

T

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

2026-07-03 15:26:32 +08:00

28 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: 优化导出文件质量

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 端口已完成。
部署文档和数据清理流程仍待补充。

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

优先级：P1

目标：

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

包含范围：

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

边界情况：

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

验收标准：

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

建议 commit：

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

WO-10 发布候选版本验收

优先级：P0

目标：

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

包含范围：

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

最终验收标准：

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

建议 commit：

release: 标记 MVP 演示候选版本

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 跑通，页面显示已完成，报告摘要正常
遗留问题：任务列表自动刷新和进度条仍待做

28 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. 每次工单完成后的记录模板

28 KiB

Raw Blame History