From 6a2ced0a07c7749e320d4d5a05380ce24ab521cc Mon Sep 17 00:00:00 2001
From: meijiali <你的邮箱@xxx.com>
Date: Fri, 3 Jul 2026 14:12:43 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=88=E5=B9=B6=20MVP=20=E5=B7=A5?=
 =?UTF-8?q?=E5=8D=95=E5=AE=A1=E9=98=85=E5=86=B3=E7=AD=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/MVP-WorkOrders.md | 158 +++++++++++++++++++++++++++++++++++------
 1 file changed, 138 insertions(+), 20 deletions(-)

diff --git a/docs/MVP-WorkOrders.md b/docs/MVP-WorkOrders.md
index 82883c3..4f64eca 100644
--- a/docs/MVP-WorkOrders.md
+++ b/docs/MVP-WorkOrders.md
@@ -142,22 +142,71 @@ http://localhost:8000
 - 页面是否能展示和导出。
 - 实际返回不足是否来自平台数据本身。
 
-## 6. 工单总览
+## 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-03 | 双平台真实小规模验收 | P0 | 带基础容错前置，小红书 / 抖音 `1×1×10` 都稳定跑通 |
 | WO-04 | 双平台默认规模验收 | P0 | 小红书 / 抖音默认规模完成真实验收并记录限制 |
-| WO-05 | 失败、限流和跳过边界验证 | P0 | 429、超时、单条失败不拖垮任务 |
+| 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. 工单详情
+## 8. 工单详情
 
 ### WO-01 任务状态与进度体验优化
 
@@ -177,6 +226,7 @@ http://localhost:8000
 - 当前处理数量：成功 / 失败 / 总内容数。
 - 失败原因展示：阶段、错误类型、错误消息。
 - AI 成功率展示。
+- 轮询终止条件：任务进入 `success` 或 `failed` 后停止轮询。
 
 边界情况：
 
@@ -192,6 +242,7 @@ http://localhost:8000
 - 不刷新浏览器也能看到最终状态。
 - 失败任务不再长期显示“正在抓取热点数据”。
 - 运行中任务列表能自动更新状态。
+- 任务终止后不继续轮询，不持续打 API。
 
 建议 commit：
 
@@ -223,6 +274,7 @@ feat: 优化任务状态与进度体验
 - 评论列表展示情绪、标签、点赞数。
 - 报告尚未生成时的空状态。
 - 报告生成失败时的提示。
+- AI 分析失败或样本不足时的默认文案 / 空状态。
 
 边界情况：
 
@@ -232,12 +284,14 @@ feat: 优化任务状态与进度体验
 - 标签为空。
 - AI 成功率低于 80%。
 - 内容条目失败但同热点下其他内容成功。
+- AI 分析失败时，页面不得返回 500。
 
 验收标准：
 
 - 热点报告页能清楚展示摘要、样本数、情绪、标签、典型评论。
 - 内容详情页能清楚展示单条内容报告和评论明细。
 - 没有报告时不是空白或 500。
+- AI 失败或样本不足时有可读提示，不显示异常堆栈。
 - Markdown 导出内容与页面报告一致。
 
 建议 commit：
@@ -252,10 +306,15 @@ feat: 打磨报告页和内容详情页
 
 目标：
 
-- 小红书和抖音都能用真实 TikHub、真实 AI 跑通 `1×1×10`。
+- 在具备基础容错前提下，小红书和抖音都能用真实 TikHub、真实 AI 跑通 `1×1×10`。
+- WO-03 不允许裸奔进入真实环境，必须先确认基础重试、单条隔离和同步 HTTP client 约束。
 
 包含范围：
 
+- 前置内联：TikHub 429 指数退避重试 `1s -> 2s -> 4s`。
+- 前置内联：单条评论 / 单个内容条目异常隔离，失败记录后继续处理。
+- 前置内联：后台任务只使用同步 `httpx.Client`，禁止 `httpx.AsyncClient`。
+- 前置内联：每个内容条目处理完立即 commit，不持有长事务。
 - 小红书真实任务验收。
 - 抖音真实任务验收。
 - 记录任务 ID、状态、热点数、内容数、评论数、报告数、AI 成功率。
@@ -268,6 +327,8 @@ feat: 打磨报告页和内容详情页
 - 内容评论不足 10 条。
 - AI 请求失败或解析失败。
 - 报告摘要生成失败。
+- 单条评论乱码或字段缺失。
+- 单个内容条目失败，但后续内容仍应继续。
 
 验收标准：
 
@@ -275,6 +336,8 @@ feat: 打磨报告页和内容详情页
 - 至少有热点、内容、评论、报告入库。
 - AI 成功率正常，或有明确不足提示。
 - 页面能查看热点报告、内容详情和评论明细。
+- 单条评论 / 单个内容条目异常不会导致整个任务崩溃。
+- 后台线程中不存在 `httpx.AsyncClient` 使用。
 
 建议 commit：
 
@@ -326,16 +389,18 @@ test: 记录双平台默认规模真实验收
 
 目标：
 
-- 确认单个接口失败不会拖垮整个任务。
-- 确认 429 和超时有重试和降级。
+- 在 WO-03 已内联基础容错后，集中压测更极端的边界 case。
+- 确认连续失败、全部失败、并发竞争等场景不会产生误导性状态或无意义 500。
 
 包含范围：
 
-- TikHub 429 指数退避。
+- 连续 429 超过最大重试次数后的错误记录。
+- 全部内容条目失败后的任务降级。
+- AI 全批失败后的 `analysis_status=insufficient`。
+- 并发创建任务竞争：已有 running 时拒绝新任务。
 - 评论分页中途失败处理。
-- 单个内容抓取失败后继续下一个内容。
-- AI 评论分析失败后标记该批次失败。
 - 报告摘要失败后使用默认文案，不阻断报告生成。
+- 确认后台任务仍使用同步 `httpx.Client`。
 
 边界情况：
 
@@ -344,10 +409,14 @@ test: 记录双平台默认规模真实验收
 - 评论接口失败：当前内容失败，其他内容继续。
 - AI 失败：评论标记 failed，任务可继续。
 - 报告摘要失败：报告仍创建。
+- 连续 429 超限后：记录 `rate_limited`，不暴露 API Key。
+- 所有内容失败后：任务 `status=failed`，错误原因可见。
+- 同时发起两个任务：第二个应返回 400。
 
 验收标准：
 
 - mock 测试覆盖失败路径。
+- 连续 429、全部失败、并发竞争均有测试覆盖。
 - 页面能展示失败阶段和错误类型。
 - 没有无意义的 500 页面。
 
@@ -368,7 +437,7 @@ fix: 完善失败重试与跳过边界
 
 包含范围：
 
-- 启动时数据库 integrity check。
+- 启动时始终执行 `PRAGMA integrity_check`，不新增配置开关。
 - 数据库损坏备份策略。
 - WAL / SHM 文件处理策略。
 - 运行中任务恢复逻辑。
@@ -382,10 +451,12 @@ fix: 完善失败重试与跳过边界
 - `app.db-wal` / `app.db-shm` 异常。
 - 本地脚本和 Docker 同时访问同一个 SQLite 文件。
 - 数据库为空但用户误以为历史数据还在。
+- `PRAGMA integrity_check` 返回非 `ok`。
 
 验收标准：
 
 - `PRAGMA integrity_check` 可执行。
+- 启动时默认执行 integrity check，不需要 `DB_CHECK_ON_STARTUP` 之类的开关。
 - Docker 重启后 running 任务被标记 failed，并显示明确原因。
 - 数据库异常不会让用户误以为任务还在抓取。
 - 文档说明如何重置本地验收数据库。
@@ -411,12 +482,15 @@ fix: 增强 SQLite 数据库恢复与异常提示
 - 内容报告 Markdown。
 - 热点报告 Markdown。
 - 文件名安全处理。
-- CSV 注入防护。
+- CSV 公式注入防护：首字符为 `=`, `+`, `-`, `@` 时添加单引号前缀。
+- CSV 换行符处理：评论内容中的 `\n`、`\r` 替换为空格。
+- CSV 编码：统一使用 UTF-8-BOM。
 - 报告不存在时禁用导出或返回友好错误。
 
 边界情况：
 
 - 评论内容以 `=`, `+`, `-`, `@` 开头。
+- 评论内容包含换行符或回车符。
 - 中文文件名。
 - 报告不存在。
 - 内容条目失败。
@@ -427,7 +501,9 @@ fix: 增强 SQLite 数据库恢复与异常提示
 - 浏览器点击导出能下载文件。
 - 文件名可读且安全。
 - Markdown 内容与页面一致。
-- CSV 用 Excel 打开不乱码。
+- CSV 用 Windows Excel 打开中文不乱码。
+- CSV 中公式注入内容不会被 Excel 当公式执行。
+- CSV 中单条评论不会因换行破坏行结构。
 
 建议 commit：
 
@@ -448,6 +524,7 @@ feat: 优化导出文件质量
 - 固定 Docker Compose 项目名。
 - 固定端口 `8000`。
 - 数据目录挂载说明。
+- Docker Compose 挂载整个 `./data:/app/data` 目录，不挂载单个 `.db` 文件。
 - `.env` / `.env.example` 检查。
 - Docker 重建流程。
 - 部署前清理临时数据库。
@@ -458,12 +535,14 @@ feat: 优化导出文件质量
 - 不同项目名启动出两套容器。
 - `.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：
 
@@ -552,7 +631,7 @@ docs: 补充本地验收和部署说明
 release: 标记 MVP 演示候选版本
 ```
 
-## 8. 新问题处理规则
+## 9. 新问题处理规则
 
 验收时发现新问题，先判断归属：
 
@@ -566,16 +645,16 @@ release: 标记 MVP 演示候选版本
 - 当前做 WO-01，发现 CSV 乱码：记录到 WO-07，不要马上切走。
 - 当前做任何工单，发现 Docker 起不来：阻塞验收，可先修 WO-08 相关问题。
 
-## 9. 建议后续推进顺序
+## 10. 建议后续推进顺序
 
 建议顺序：
 
 1. WO-01 任务状态与进度体验优化
 2. WO-02 报告页和内容详情页产品化打磨
 3. WO-03 双平台真实小规模验收
-4. WO-05 失败、限流和跳过边界验证
-5. WO-06 SQLite 数据库稳定性与恢复策略
-6. WO-04 双平台默认规模验收
+4. WO-04 双平台默认规模验收
+5. WO-05 失败、限流和跳过边界压测
+6. WO-06 SQLite 数据库稳定性与恢复策略
 7. WO-07 导出链路验收与文件质量优化
 8. WO-08 Docker 与部署前清理
 9. WO-09 文档与用户操作说明
@@ -585,10 +664,49 @@ release: 标记 MVP 演示候选版本
 
 - 先解决用户看得到的“卡住感”和状态透明。
 - 再打磨核心报告页面。
-- 再做真实接口验收和稳定性压测。
+- 再做带基础容错前置的小规模真实验收。
+- 默认规模验收后，再用 WO-05 集中压测连续 429、全批失败、并发竞争等边界。
 - 最后整理部署、文档和发布候选版本。
 
-## 10. 每次工单完成后的记录模板
+执行链路：
+
+```text
+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. 每次工单完成后的记录模板
 
 完成一个工单后，在该工单下补充记录：