# 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 验收。 |