docs: add TDD and task planning documents

docs/TDD.md

@@ -0,0 +1,914 @@
+# TDD.md：小红书 / 抖音热榜评论抓取 + AI 分析报告工具
+
+## 1. 文档信息
+
+- 文档阶段：TDD（Test-Driven Development，测试驱动开发计划）
+- 需求依据：`docs/PRD.md`、`docs/FeatureSummary.md`
+- 技术依据：`docs/DevelopmentPlan.md`
+- UI 依据：`docs/UIDesign.md`
+- 当前目标：定义 MVP 开发前必须先写的测试范围、测试顺序、Mock 策略、验收命令与端到端测试清单
+- 测试原则：先写失败测试，再写最小实现；任何业务代码变更前必须先有对应测试
+
+---
+
+## 2. TDD 总原则
+
+### 2.1 红绿重构流程
+
+每个功能点按以下顺序执行：
+
+1. **Red**：先写一个最小失败测试。
+2. **Verify Red**：运行测试，确认失败原因是目标功能缺失，而不是测试代码错误。
+3. **Green**：写最小实现让测试通过。
+4. **Verify Green**：运行该测试和相关测试，确认通过。
+5. **Refactor**：只在测试通过后清理代码。
+
+禁止事项：
+
+- 禁止先实现后补测试。
+- 禁止为了让测试通过而删除关键断言。
+- 禁止用真实 TikHub / AI API 作为单元测试依赖。
+- 禁止在模板中硬编码中文状态文案，状态展示必须通过映射或 Macro 测试覆盖。
+
+### 2.2 测试分层
+
+| 层级 | 工具 | 目标 |
+|---|---|---|
+| 单元测试 | pytest | 字段映射、配置校验、分页、统计、导出、AI schema |
+| 服务集成测试 | pytest + TestClient + mock httpx | 任务创建、后台流程、平台链路、报告生成 |
+| 模板测试 | pytest + Jinja2 渲染 | 状态 Badge、空状态、导出按钮、标签渲染 |
+| 端到端测试 | Playwright | 首页创建任务、查看报告、导出按钮、手动刷新 |
+| Docker 验收 | docker compose + curl | 启动、`/health`、页面可访问 |
+
+### 2.3 测试目录建议
+
+```text
+tests/
+  conftest.py
+  fixtures/
+    xhs_hot_list.json
+    xhs_search_notes.json
+    xhs_comments_page_1.json
+    xhs_comments_page_2_empty.json
+    douyin_hot_list.json
+    douyin_search_videos.json
+    douyin_comments_page_1.json
+    ai_comments_success.json
+    ai_comments_invalid_json.txt
+  unit/
+    test_config.py
+    test_models.py
+    test_xiaohongshu_mapping.py
+    test_douyin_mapping.py
+    test_comment_pagination.py
+    test_ai_schema.py
+    test_report_stats.py
+    test_export.py
+    test_template_filters.py
+  integration/
+    test_task_creation.py
+    test_task_flow_xiaohongshu.py
+    test_task_flow_douyin.py
+    test_failure_tolerance.py
+    test_routes.py
+  e2e/
+    test_mvp_flow.py
+```
+
+---
+
+## 3. 测试环境与命令
+
+### 3.1 推荐依赖
+
+```text
+pytest
+pytest-cov
+pytest-mock
+respx
+httpx
+beautifulsoup4
+playwright
+```
+
+说明：
+
+- `respx` 用于 mock `httpx.Client` 外部 HTTP 调用。
+- `beautifulsoup4` 用于断言 HTML 片段内容。
+- Playwright 仅覆盖关键页面流程，不替代单元测试。
+
+#### 工具使用原则
+
+- `respx`：用于 mock `httpx.Client` 发出的外部 HTTP 请求（TikHub API、AI API）。
+- `pytest-mock`：用于 mock Python 函数、类方法、`time.sleep` 调用和时间函数。
+- 两者不混用于同一外部请求的 mock。即：若某个测试需要拦截一个 HTTP 请求，必须使用 `respx`，不得用 `pytest-mock.patch("httpx.Client.get")` 替代。
+
+### 3.2 测试数据库隔离与环境变量
+
+#### 测试数据库隔离策略
+
+所有单元测试和集成测试统一使用内存数据库 `sqlite:///:memory:`，不依赖物理 `test.db` 文件，避免测试用例间状态污染（Flaky Tests）。
+
+在 `tests/conftest.py` 中定义函数级别（`scope="function"`）的数据库 fixture：
+
+```python
+@pytest.fixture(scope="function")
+def db_session():
+    engine = create_engine(
+        "sqlite:///:memory:",
+        connect_args={"check_same_thread": False},
+    )
+    Base.metadata.create_all(engine)
+    session = Session(engine)
+    yield session
+    session.close()
+    Base.metadata.drop_all(engine)
+```
+
+每个测试用例运行前自动创建全部表结构，运行后自动销毁，确保测试在绝对隔离的环境中执行。
+
+禁止在集成测试中复用同一 engine 实例跨用例写入数据而不做 teardown。
+
+#### 环境变量
+
+```text
+APP_ENV=test
+DATABASE_URL=sqlite:///:memory:
+TIKHUB_API_KEY=test-token
+TIKHUB_BASE_URL=https://api.tikhub.test
+AI_PROVIDER=openai-compatible
+AI_BASE_URL=https://ai.test
+AI_API_KEY=test-ai-key
+AI_MODEL=test-model
+AI_BATCH_SIZE=20
+AI_CONCURRENCY=2
+AI_MAX_RETRIES=3
+AI_TIMEOUT_SECONDS=30
+```
+
+### 3.3 常用命令
+
+```bash
+pytest tests/unit -q
+pytest tests/integration -q
+pytest tests/unit tests/integration \
+  --cov=app \
+  --cov-branch \
+  --cov-report=term-missing
+pytest tests/e2e -q
+docker compose up --build
+curl -f http://localhost:8000/health
+```
+
+#### 覆盖率豁免配置
+
+在 `pyproject.toml` 的 `[tool.coverage.report]` 节中添加以下配置，将模板层和静态资源排除在覆盖率统计之外：
+
+```toml
+[tool.coverage.report]
+omit = [
+    "app/templates/*",
+    "app/static/*",
+    "tests/*",
+]
+```
+
+全局覆盖率目标维持 80%，`app/services/` 和 `app/platforms/` 下的核心域覆盖率不低于 90%（通过 CI 脚本或 code review 人工把关，不在 pytest 命令层面强制差异化）。
+
+---
+
+## 4. Mock 数据规范
+
+### 4.1 小红书 Mock 样例
+
+`xhs_hot_list.json` 必须覆盖：
+
+- `data.data.items[]` 是真实热榜条目；
+- 外层 `data.data.title` 不应被误用为热点标题；
+- 热点字段包含 `id`、`title`、`score`。
+
+`xhs_search_notes.json` 必须覆盖：
+
+- 至少 2 条 `comments_count > 0` 的笔记；
+- 至少 1 条 `comments_count = 0` 的笔记；
+- 字段包含 `note.id`、`note.title`、`note.desc`、`note.comments_count`。
+
+`xhs_comments_page_1.json` 必须覆盖：
+
+- 评论 ID 同时存在 `comment_id` 和 `id` 时，优先 `comment_id`；
+- 评论正文可来自 `content` 或 `text`；
+- 包含 `like_count`、`create_time`。
+
+### 4.2 抖音 Mock 样例
+
+`douyin_hot_list.json` 必须覆盖：
+
+- 热点字段包含 `query_id`、`title`、`rank`、`hot_score`。
+
+`douyin_search_videos.json` 必须覆盖：
+
+- 视频字段包含 `aweme_info.aweme_id`、`aweme_info.desc`、`aweme_info.author`、`aweme_info.statistics`。
+
+`douyin_comments_page_1.json` 必须覆盖：
+
+- 评论 ID 同时存在 `comment_id` 和 `cid` 时，优先 `comment_id`；
+- 评论正文来自 `text`；
+- 包含 `digg_count`、`create_time`。
+
+### 4.3 AI Mock 样例
+
+成功响应：
+
+```json
+[
+  {
+    "comment_id": "c1",
+    "sentiment": "positive",
+    "labels": ["价格实惠", "质量好"],
+    "reason": "评论表达了明确认可"
+  }
+]
+```
+
+失败响应至少覆盖：
+
+- 非 JSON 文本；
+- JSON Object 而不是 JSON Array；
+- 缺失 `comment_id`；
+- `comment_id` 与输入不匹配；
+- `sentiment` 不在枚举值内；
+- `labels` 超过 3 个；
+- 混入 Markdown 或自然语言前缀。
+
+### 4.4 HTTP 429 Mock Fixture
+
+在 `tests/conftest.py` 中提供可复用的 429 响应 fixture：
+
+```python
+@pytest.fixture
+def mock_429_response():
+    return httpx.Response(
+        status_code=429,
+        headers={"Retry-After": "1"},
+        json={"message": "Too Many Requests"},
+    )
+```
+
+§8.2（分页限流重试）和 §13.3（任务级限流容错）均使用此 fixture，不各自重复定义。
+
+### 4.5 评论字段缺失 Mock 数据
+
+在 `tests/fixtures/` 中新增以下两个文件：
+
+- `xhs_comments_missing_fields.json`：小红书评论列表，其中 `like_count` 和 `create_time` 字段均不存在（非 null，而是 key 完全缺失）。
+- `douyin_comments_missing_fields.json`：抖音评论列表，其中 `digg_count` 和 `create_time` 字段均不存在。
+
+这两个 fixture 用于 §7.2 和 §7.5 的字段缺失测试用例。
+
+### 4.6 AI 全情绪值 Mock 数据
+
+在 `tests/fixtures/ai_comments_success.json` 中确保包含四种 sentiment 值各至少一条评论，用于统计逻辑（`analysis_success_rate`、情绪分布）的测试：
+
+```json
+[
+  {"comment_id": "c001", "sentiment": "positive", "labels": ["品质好"], "reason": ""},
+  {"comment_id": "c002", "sentiment": "negative", "labels": ["物流慢"], "reason": ""},
+  {"comment_id": "c003", "sentiment": "neutral", "labels": [], "reason": ""},
+  {"comment_id": "c004", "sentiment": "unknown", "labels": [], "reason": ""}
+]
+```
+
+若 `ai_comments_success.json` 已有其他用途，新增 `ai_comments_all_sentiments.json` 作为统计测试专用 fixture。
+
+---
+
+## 5. 配置与数据模型测试
+
+### 5.1 配置校验
+
+测试文件：`tests/unit/test_config.py`
+
+用例：
+
+1. 默认配置读取成功。
+2. `hot_limit` 范围为 1–10。
+3. `item_limit_per_hot` 范围为 1–10。
+4. `comment_limit_per_item` 范围为 10–100。
+5. `AI_CONCURRENCY` 默认值为 2。
+6. `AI_MAX_RETRIES` 默认值为 3。
+
+### 5.2 SQLite 初始化
+
+测试文件：`tests/unit/test_models.py`
+
+用例：
+
+1. 应用启动时调用 `Base.metadata.create_all(engine)` 可创建所有表。
+2. SQLite engine 配置包含 `check_same_thread=False` 和 `timeout=10`。
+3. 连接建立后启用 `PRAGMA journal_mode=WAL`。
+
+### 5.3 任务状态模型
+
+测试文件：`tests/unit/test_models.py`
+
+用例：
+
+1. `Task.status` 仅允许 `running`、`success`、`failed`。
+2. 不允许写入 `partial_success` 或 `partial_failed`。
+3. `analysis_status` 允许 `normal`、`insufficient`。
+4. 任务 `status=success` 时，`analysis_success_rate < 0.8` 只更新 `analysis_status='insufficient'`，不改变 `status='success'`。
+5. 任务 `status=failed` 时，`analysis_success_rate` 字段写入实际计算值，`status` 保持 `'failed'` 不变，不因 AI 成功率判断被覆盖为其他值。
+
+---
+
+## 6. 任务创建与恢复测试
+
+### 6.1 创建任务 API
+
+测试文件：`tests/integration/test_task_creation.py`
+
+用例：
+
+1. `POST /api/tasks` 使用合法参数创建任务，返回 `task_id` 和 `status=running`。
+2. 创建任务保存平台和配置字段：
+   - `hot_limit`
+   - `item_limit_per_hot`
+   - `comment_limit_per_item`
+3. `platform` 非法时返回 422。
+4. 配置值越界时返回 422。
+5. 同一平台可重复创建任务，任务彼此独立。
+
+### 6.2 ThreadPoolExecutor 单任务约束
+
+测试文件：`tests/unit/test_task_executor.py`
+
+用例：
+
+1. 任务执行器初始化为 `ThreadPoolExecutor(max_workers=1)`。
+2. 同时提交两个任务时，第二个任务必须等待第一个任务完成后才开始。
+
+#### httpx 使用方式断言
+
+测试文件：`tests/unit/test_task_executor.py`
+
+用例：
+
+1. 后台任务执行函数不是协程：使用 `inspect.iscoroutinefunction(run_task)` 断言返回 `False`，确保其在 `ThreadPoolExecutor` 中以同步方式运行。
+2. 小红书平台客户端实例为 `httpx.Client` 同步类型：`assert isinstance(client._http_client, httpx.Client)`。
+3. 抖音平台客户端实例为 `httpx.Client` 同步类型，同上。
+4. AI 服务客户端发出的请求使用 `httpx.Client`，不存在 `httpx.AsyncClient` 的实例化调用。
+
+### 6.3 僵尸任务恢复
+
+测试文件：`tests/integration/test_task_recovery.py`
+
+用例：
+
+1. 数据库存在 `status=running` 的任务。
+2. 应用 lifespan 启动恢复逻辑执行后，该任务变为 `status=failed`。
+3. `error_stage=system`。
+4. `error_type=unexpected_restart`。
+5. `error_message=系统重启，任务被中断`。
+
+---
+
+## 7. 平台抓取测试
+
+### 7.1 小红书字段映射
+
+测试文件：`tests/unit/test_xiaohongshu_mapping.py`
+
+用例：
+
+1. 热点标题从 `data.data.items[].title` 读取。
+2. 不使用外层 `data.data.title` 作为热点标题。
+3. 热点 `id` 映射到 `source_hot_id`。
+4. `score` 映射到 `heat_value`。
+5. 笔记 `note.id` 映射到 `source_item_id`。
+6. 优先选择 `comments_count > 0` 的笔记。
+7. 有评论笔记不足目标数时，补充 `comments_count = 0` 的笔记。
+8. 平台返回笔记总数不足目标数时，不标记任务失败。
+
+#### 笔记搜索分页限制
+
+测试文件：`tests/unit/test_xiaohongshu_mapping.py`
+
+用例：
+
+1. 搜索笔记接口只请求第一页（`page=1`），不发起后续翻页请求。
+2. 首页返回 `comments_count > 0` 的笔记已满足目标数量时，不发起第二次搜索请求。
+3. 首页返回结果不足目标数量时，执行降级策略（补充 `comments_count = 0` 的笔记），而非翻页搜索。
+
+### 7.2 小红书评论字段映射
+
+测试文件：`tests/unit/test_xiaohongshu_mapping.py`
+
+用例：
+
+1. `source_comment_id` 优先取 `data.get("comment_id")`。
+2. `comment_id` 不存在时回退到 `data.get("id")`。
+3. `content` 不存在时回退到 `text`。
+4. `like_count` 和 `create_time` 正确映射。
+5. 原始评论 JSON 保存到 `raw_data`。
+6. `like_count` 字段缺失时，入库值为 `null`，不抛出异常，不阻断评论抓取流程。
+7. `comment_time`（`create_time` / `create_time_str`）字段缺失时，入库值为 `null`，不抛出异常，不阻断评论抓取流程。
+
+### 7.4 抖音字段映射
+
+测试文件：`tests/unit/test_douyin_mapping.py`
+
+用例：
+
+1. `query_id` 映射到 `source_hot_id`。
+2. `title` 映射到热点标题。
+3. `rank` 映射到热点排名。
+4. `hot_score` 映射到 `heat_value`。
+5. `aweme_info.aweme_id` 映射到 `source_item_id`。
+6. `aweme_info.desc` 映射到标题或摘要。
+
+### 7.5 抖音评论字段映射
+
+测试文件：`tests/unit/test_douyin_mapping.py`
+
+用例：
+
+1. `source_comment_id` 优先取 `data.get("comment_id")`。
+2. `comment_id` 不存在时回退到 `data.get("cid")`。
+3. `text` 映射到 `content`。
+4. `digg_count` 映射到 `like_count`。
+5. `create_time` 映射到 `comment_time`。
+6. `digg_count` 字段缺失时，入库值为 `null`，不抛出异常，不阻断评论抓取流程。
+7. `comment_time`（`create_time` / `create_time_str`）字段缺失时，入库值为 `null`，不抛出异常，不阻断评论抓取流程。
+
+---
+
+## 8. 评论分页、限流与去重测试
+
+### 8.1 评论分页终止条件
+
+测试文件：`tests/unit/test_comment_pagination.py`
+
+用例：
+
+1. 抓取评论数达到 `comment_limit_per_item` 后停止。
+2. API 返回空评论列表后停止。
+3. 达到最大翻页轮次 5 后停止。
+4. API 未返回下一页游标时停止。
+
+### 8.2 分页请求间隔
+
+测试文件：`tests/unit/test_comment_pagination.py`
+
+用例：
+
+1. 每次评论分页请求之间调用 `time.sleep`，间隔值在 1.0 到 2.0 秒范围内（含边界值）。断言方式：`assert 1.0 <= mock_sleep.call_args[0][0] <= 2.0`。
+2. 收到 HTTP 429 后使用指数退避 1s → 2s → 4s。
+3. 429 退避完成后恢复基础分页间隔。
+
+备注：若后续将间隔提取为配置项 `CRAWL_PAGE_INTERVAL_SECONDS`，改为读取配置值后断言，不硬编码数值。
+
+### 8.3 评论去重
+
+测试文件：`tests/unit/test_comment_pagination.py`
+
+用例：
+
+1. 同一任务、同一内容条目、同一评论 ID 不重复入库。
+2. 重复抓取时更新已有记录或跳过重复记录。
+3. 不同任务下相同评论 ID 可分别保存。
+4. 同一内容出现在不同热点下时，按 `task_id + hotspot_id + source_item_id` 保留重复内容条目。
+
+---
+
+## 9. AI 分析测试
+
+### 9.1 Prompt 输入构造
+
+测试文件：`tests/unit/test_ai_schema.py`
+
+用例：
+
+1. 输入给 LLM 的数据为 JSON Array。
+2. 每条输入包含 `comment_id` 和 `content`。
+3. 单条评论内容超过 150 字符时截断为前 150 字符。
+4. Prompt 明确要求原样回填 `comment_id`。
+
+### 9.2 AI 输出 Schema 校验
+
+测试文件：`tests/unit/test_ai_schema.py`
+
+用例：
+
+1. 严格 JSON Array 响应校验通过。
+2. 非 JSON 文本校验失败。
+3. JSON Object 校验失败。
+4. 缺失 `comment_id` 校验失败。
+5. `comment_id` 与输入不匹配时该条评论失败。
+6. `sentiment` 不在枚举值内校验失败。
+7. `labels` 超过 3 个时校验失败。
+8. 空标签数组允许通过，`sentiment` 可为 `unknown`。
+
+### 9.3 AI 重试与降级拆分
+
+测试文件：`tests/unit/test_ai_schema.py`
+
+用例：
+
+1. 单批 AI 请求失败后最多重试 `AI_MAX_RETRIES=3` 次。
+2. 同一批次连续 3 次整批解析失败（含重试）后，该批次所有评论的 `ai_analysis_status` 标记为 `'failed'`，任务继续处理下一批次，不抛出异常。
+3. 当前批次失败不阻塞下一批次。
+
+### 9.4 AI 并发粒度
+
+测试文件：`tests/unit/test_ai_schema.py`
+
+用例：
+
+1. 同一任务内最多 2 个 AI 批量请求同时运行。
+2. 并发粒度为跨内容条目。
+3. 同一内容条目的多批评论串行处理。
+
+### 9.5 AI 成功率与任务质量状态
+
+测试文件：`tests/unit/test_ai_schema.py`
+
+用例：
+
+1. 成功评论数 / 总评论数 >= 80% 时，`analysis_status=normal`。
+2. 成功评论数 / 总评论数 < 80% 时，`analysis_status=insufficient`。
+3. `analysis_status=insufficient` 不改变任务 `status`。
+4. 没有任何内容条目成功时，任务仍为 `failed`。
+
+---
+
+## 10. 报告生成测试
+
+### 10.1 情绪与标签统计
+
+测试文件：`tests/unit/test_report_stats.py`
+
+用例：
+
+1. 正向、负向、中性、未知评论数量正确。
+2. 情绪占比保留合理精度。
+3. 标签按字面值聚合。
+4. Top 5 标签按数量降序。
+5. 空标签不参与标签统计。
+
+### 10.2 典型评论选取
+
+测试文件：`tests/unit/test_report_stats.py`
+
+用例：
+
+1. 每种情绪选取 1–2 条典型评论。
+2. 有点赞数字段时按点赞数降序。
+3. 点赞数缺失时按抓取顺序。
+4. 典型评论文本传给总结 AI 前截断为 150 字符。
+
+### 10.3 内容条目级报告
+
+测试文件：`tests/unit/test_report_stats.py`
+
+用例：
+
+1. 内容条目级报告包含样本评论数量。
+2. 报告统计与评论结构化结果一致。
+3. `report_type=item` 时 `hotspot_id` 和 `content_item_id` 均不为空。
+4. 生成 `markdown_content` 并保存。
+5. 总结 AI 失败时，summary 使用默认文本：`总结生成失败，请查看详细数据`。
+6. `report_type='item'` 时，创建的报告记录 `hotspot_id` 不为空，`content_item_id` 不为空；任一字段为空时 `report_service` 抛出明确异常。
+7. `report_type='hotspot'` 时，创建的报告记录 `hotspot_id` 不为空，`content_item_id` 为空；若 `content_item_id` 非空则抛出明确异常。
+
+### 10.4 热点级报告
+
+测试文件：`tests/unit/test_report_stats.py`
+
+用例：
+
+1. 热点级报告聚合热点下所有内容条目评论。
+2. 内容条目数量、样本数量、情绪数量与评论明细一致。
+3. `report_type=hotspot` 时 `hotspot_id` 不为空，`content_item_id` 为空。
+4. 生成 `markdown_content` 并保存。
+5. 总结 AI 失败不阻断报告创建。
+6. `report_type='item'` 时，创建的报告记录 `hotspot_id` 不为空，`content_item_id` 不为空；任一字段为空时 `report_service` 抛出明确异常。
+7. `report_type='hotspot'` 时，创建的报告记录 `hotspot_id` 不为空，`content_item_id` 为空；若 `content_item_id` 非空则抛出明确异常。
+
+### 10.5 报告总结 AI 请求
+
+测试文件：`tests/unit/test_report_stats.py`
+
+用例：
+
+1. 内容条目级总结 AI 请求的输入包含统计数据摘要（正向 / 中性 / 负向各占比）和典型评论文本（每类至少 1 条）。
+2. 热点级总结 AI 请求的输入包含聚合情绪分布统计、Top 5 标签及出现次数，以及典型评论文本。
+3. 传入总结 AI 的单条评论文本截断为 150 字符，超出部分丢弃，不引发错误。
+4. 总结 AI 请求不使用 JSON Schema 约束（`response_format` 不为 `json_object` 或 `json_schema`），输出期望为纯文本字符串。
+5. 总结 AI 请求超时时，报告中 `summary` 字段写入默认文本 `总结生成失败，请查看上方统计数据`，报告记录正常创建，不抛出异常，不阻断后续报告生成流程。
+6. 总结 AI 返回内容超过字数限制时执行截断：内容条目级总结超过 200 字时截断，热点级超过 300 字时截断。
+
+---
+
+## 11. 导出测试
+
+### 11.1 CSV 导出
+
+测试文件：`tests/unit/test_export.py`
+
+用例：
+
+1. CSV 使用 `UTF-8-SIG` 编码。
+2. CSV 包含平台、任务 ID、热点、内容条目、评论 ID、评论内容、情绪、标签、点赞数、评论时间。
+3. `labels` 入库为 JSON Array 字符串，导出时转换为中文逗号拼接。
+4. 评论内容以 `=`、`+`、`-`、`@` 开头时添加单引号，防 CSV 公式注入。
+5. 导出内容与页面展示数据源一致。
+
+### 11.2 文件名安全处理
+
+测试文件：`tests/unit/test_export.py`
+
+用例：
+
+1. 文件名格式为 `{platform}_{task_id}_{hotspot_keyword}.csv`。
+2. `hotspot_keyword` 超过 20 字符时截断。
+3. `/`、`\`、`:`、`*`、`?`、`"`、`<`、`>`、`|` 替换为 `_`。
+4. 连续多个 `_` 合并为单个 `_`。
+
+### 11.3 Markdown 导出
+
+测试文件：`tests/unit/test_export.py`
+
+用例：
+
+1. 热点级 Markdown 读取 `reports.markdown_content`。
+2. 内容条目级 Markdown 读取 `reports.markdown_content`。
+3. 导出 Markdown 与页面报告使用同一份数据。
+4. 报告不存在时返回 404 或禁用按钮对应状态。
+
+### 11.4 导出路由
+
+测试文件：`tests/integration/test_routes.py`
+
+用例：
+
+1. `GET /api/export/items/{item_id}/comments.csv` 返回 CSV 文件流。
+2. `GET /api/export/hotspots/{hotspot_id}/comments.csv` 返回热点下全部评论 CSV。
+3. `GET /api/export/hotspots/{hotspot_id}.md` 返回热点 Markdown。
+4. `GET /api/export/items/{item_id}.md` 返回内容条目 Markdown。
+
+---
+
+## 12. UI 与模板测试
+
+### 12.1 状态展示
+
+测试文件：`tests/unit/test_template_filters.py`
+
+用例：
+
+1. `running` 渲染为运行中 Badge。
+2. `success` 渲染为已完成 Badge。
+3. `failed` 渲染为失败 Badge。
+4. 任务状态不测试 `partial_success` 或 `partial_failed`。
+5. `analysis_status=insufficient` 渲染 AI 分析不足提示。
+
+### 12.2 表单与校验
+
+测试文件：`tests/integration/test_routes.py`
+
+用例：
+
+1. 首页包含平台选择控件。
+2. 首页包含 `hot_limit`、`item_limit_per_hot`、`comment_limit_per_item` 输入。
+3. 首页展示默认预估规模 1250。
+4. 422 错误可渲染到表单错误区域。
+
+### 12.3 标签渲染
+
+测试文件：`tests/unit/test_template_filters.py`
+
+用例：
+
+1. `from_json` filter 可解析 labels JSON Array 字符串。
+2. 非法 JSON 返回空数组，不导致模板报错。
+3. 标签逐个渲染为 Badge。
+4. 空标签显示 `-`。
+
+### 12.4 空状态
+
+测试文件：`tests/integration/test_routes.py`
+
+用例：
+
+1. 无任务时首页展示空状态。
+2. 任务运行中且热点为空时展示抓取中 Spinner。
+3. 评论为空时内容详情页展示暂无评论数据。
+4. 报告尚未生成时展示报告生成中。
+
+### 12.5 导出按钮状态
+
+测试文件：`tests/integration/test_routes.py`
+
+用例：
+
+1. `task.status=running` 时导出按钮 disabled。
+2. `task.status=failed` 且无成功内容条目时导出按钮 disabled。
+3. `item.status=failed` 时内容条目 CSV 导出按钮 disabled。
+4. 有报告和评论数据时导出按钮可点击。
+
+---
+
+## 13. 服务集成测试
+
+### 13.1 小红书端到端服务流
+
+测试文件：`tests/integration/test_task_flow_xiaohongshu.py`
+
+流程：
+
+1. Mock 小红书热榜接口。
+2. Mock 小红书搜索笔记接口。
+3. Mock 小红书评论分页接口。
+4. Mock AI 评论分析接口。
+5. 创建小红书任务。
+6. 执行任务服务。
+7. 断言任务 `status=success`。
+8. 断言热点、内容条目、评论、报告均入库。
+9. 断言 raw_data 已保存。
+
+### 13.2 抖音端到端服务流
+
+测试文件：`tests/integration/test_task_flow_douyin.py`
+
+流程：
+
+1. Mock 抖音热点接口。
+2. Mock 抖音视频搜索接口。
+3. Mock 抖音评论分页接口。
+4. Mock AI 评论分析接口。
+5. 创建抖音任务。
+6. 执行任务服务。
+7. 断言任务 `status=success`。
+8. 断言热点、内容条目、评论、报告均入库。
+
+### 13.3 单个内容条目失败但任务继续
+
+测试文件：`tests/integration/test_failure_tolerance.py`
+
+用例：
+
+1. 一个内容条目评论接口返回 429 后超过最大重试。
+2. 该内容条目标记 `failed`。
+3. 后续内容条目继续处理。
+4. 至少一个内容条目成功时，任务最终 `status=success`。
+5. 任务展示失败内容条目数和错误摘要。
+
+### 13.4 全局失败
+
+测试文件：`tests/integration/test_failure_tolerance.py`
+
+用例：
+
+1. 热点接口失败时任务 `status=failed`。
+2. 所有内容条目均失败时任务 `status=failed`。
+3. 失败任务包含 `error_stage`、`error_type`、`error_message`。
+
+---
+
+### 13.5 跨热点重复内容条目场景
+
+测试文件：`tests/integration/test_failure_tolerance.py`
+
+用例：
+
+1. 同一 `source_item_id` 同时出现在两个不同热点的搜索结果中时，系统以不同 `hotspot_id` 分别创建两条 `content_items` 记录，断言数据库中存在 2 条该 `source_item_id` 的记录，各自归属于对应的 `hotspot_id`。
+2. 同一任务内，同一热点下相同 `source_item_id` 重复出现时，数据库中该热点下该 `source_item_id` 只保留 1 条记录（去重），不抛出异常，不阻断任务。
+
+---
+
+## 14. Playwright E2E 测试（P2，时间允许时实现）
+
+当前 MVP 不实现本节内容。
+
+原因：在 4 天单人开发周期内，Playwright 环境配置及 AI 长耗时任务的异步等待调优成本较高，性价比低于手工验收。
+
+Day 4 端到端验收完全依赖 §15.2 手工验收清单，后者覆盖了所有 P0 用户流程。
+
+后续版本实现 Playwright 时，须补充以下前提条件：
+
+1. e2e 测试启动独立测试服务器实例（`APP_ENV=test`）。
+2. 外部 API 调用由 `respx` 在进程内拦截，不发起真实网络请求。
+3. 测试前后清理 SQLite 测试数据库（或使用内存数据库）。
+4. 明确运行环境：若使用本地 uvicorn 服务，在 Docker 验收前执行；若在 Docker 环境中运行，须先完成 §15 Docker 验收。
+
+---
+
+## 15. Docker 与手工验收测试
+
+### 15.1 Docker 启动
+
+测试命令：
+
+```bash
+docker compose up --build
+curl -f http://localhost:8000/health
+```
+
+验收：
+
+- Docker Compose 可启动。
+- `/health` 返回 200。
+- 首页可访问。
+- SQLite 文件生成在 `./data/app.db`。
+
+### 15.2 MVP 手工验收清单
+
+1. 创建小红书默认任务。
+2. 任务列表展示创建时间、状态、AI 分析状态、成功 X / 共 Y 条内容条目。
+3. 刷新任务状态。
+4. 查看热点列表。
+5. 查看热点级报告。
+6. 查看内容条目详情。
+7. 查看评论明细。
+8. 导出 CSV 评论明细。
+9. 导出热点 Markdown 报告。
+10. 导出内容条目 Markdown 报告。
+11. 创建抖音默认任务并重复 2–10。
+12. 输入非法配置，确认前端和后端均拒绝。
+
+---
+
+## 16. 覆盖率与发布门槛
+
+### 16.1 最低覆盖要求
+
+- 单元测试覆盖率建议不低于 80%。
+- `platforms/`、`services/ai_service.py`、`services/report_service.py`、`services/export_service.py` 必须有关键行为测试。
+- UI 模板不强制覆盖率数字，但关键状态和导出按钮必须有模板测试或 e2e 测试。
+
+### 16.2 合并前必须通过
+
+```bash
+pytest tests/unit -q
+pytest tests/integration -q
+pytest tests/unit tests/integration \
+  --cov=app \
+  --cov-branch \
+  --cov-report=term-missing \
+  --cov-fail-under=80
+```
+
+# 覆盖率统计豁免 `templates/` 和 `static/` 目录，详见 `pyproject.toml` 配置。
+# branch coverage 对任务状态机和 AI 成功率阈值判断有特殊检测价值。
+
+如修改部署相关文件：
+
+```bash
+docker compose up --build
+curl -f http://localhost:8000/health
+```
+
+---
+
+## 17. 开发顺序建议
+
+### Day 1 测试优先级
+
+1. 配置校验测试。
+2. 数据模型测试。
+3. 任务创建 API 测试。
+4. 僵尸任务恢复测试。
+5. 首页模板基础渲染测试。
+
+### Day 2 测试优先级
+
+1. 小红书字段映射测试。
+2. 小红书评论分页测试。
+3. 小红书降级选择测试。
+4. 抖音字段映射测试。
+5. 429 退避与单条失败继续测试。
+
+### Day 3 测试优先级
+
+1. AI 输入构造测试。
+2. AI 输出 schema 测试。
+3. AI 重试测试。
+4. `analysis_success_rate` 测试。
+5. 报告统计与 Markdown 生成测试。
+
+（依赖 Day 3 第 1-4 条 AI 分析测试完成后方可验证完整集成路径）
+
+### Day 4 测试优先级
+
+1. CSV / Markdown 导出测试。
+2. 模板状态和空状态测试。
+3. ~~Playwright E2E 测试~~（已降级为 P2，见 §14）——Day 4 端到端验收直接执行 §15.2 手工验收清单。
+4. Docker 启动验收。
+
+---
+
+## 18. 变更日志
+
+| 日期 | 版本 | 变更内容 |
+|---|---|---|
+| 2026-07-01 | v1.0 | 基于 PRD、FeatureSummary、DevelopmentPlan、UIDesign 生成 TDD 测试驱动开发计划，覆盖配置、数据模型、任务、平台抓取、评论分页、AI 分析、报告、导出、UI 模板、集成流程、Playwright 与 Docker 验收。 |