# GEO 平台 - TDD 流程规范

## 概述

本文档定义 GEO 平台的测试驱动开发（TDD）工作流程。所有功能开发必须遵循 TDD 原则：先写测试，再写实现，最后重构。

TDD 的核心价值：
- **设计先行**：通过测试用例明确需求和接口设计
- **快速反馈**：自动化测试提供即时的正确性验证
- **安全重构**：测试覆盖确保重构不会破坏功能
- **文档即代码**：测试用例本身就是最准确的接口文档

## RED-GREEN-REFACTOR 循环

### 基本循环

```
         ┌──────────────────────┐
         │   1. RED 编写失败测试   │
         │  写一个会失败的测试用例   │
         └───────────┬──────────┘
                     │
                     ▼
         ┌──────────────────────┐
         │   2. GREEN 通过测试    │
         │  写最少代码让测试通过   │
         └───────────┬──────────┘
                     │
                     ▼
         ┌──────────────────────┐
         │  3. REFACTOR 重构代码  │
         │  优化实现，保持测试通过  │
         └───────────┬──────────┘
                     │
                     └──────▶ 下一个循环
```

### 各阶段要求

#### RED 阶段 - 编写失败测试

- **前提**：已完成需求分析和接口设计
- **动作**：编写一个测试用例，验证某个具体功能点
- **验证**：运行测试，确认测试失败（且失败原因符合预期）
- **原则**：
  - 一次只写一个测试
  - 测试命名清晰表达被测行为
  - 使用 Given-When-Then 结构组织测试代码
  - 测试失败信息应清晰说明期望 vs 实际

**示例（Python + pytest）**：
```python
# tests/test_citation_detector.py

class TestCitationDetector:
    def test_should_detect_direct_brand_reference(self):
        """Given: AI 响应中包含品牌直接引用
           When: 执行引用检测
           Then: 返回引用类型为 direct_quote"""
        # Given
        response = "根据 ExampleBrand 的研究报告显示..."
        brand = "ExampleBrand"
        
        detector = CitationDetector()
        
        # When
        result = detector.detect(response, brand)
        
        # Then
        assert result.reference_type == ReferenceType.DIRECT_QUOTE
        assert result.confidence >= 0.8
```

#### GREEN 阶段 - 通过测试

- **前提**：已有一个失败的测试
- **动作**：编写最少量的生产代码使测试通过
- **验证**：运行测试，确认测试通过
- **原则**：
  - 不择手段让测试通过（可以写丑陋的代码）
  - 不要提前实现未测试的功能
  - 如果测试仍然失败，调试直到通过
  - 如果通过后发现测试有问题，返回 RED 阶段

**示例**：
```python
# app/services/citation_detector.py

class CitationDetector:
    def detect(self, response: str, brand: str) -> DetectionResult:
        # 最小实现：直接返回预期结果
        if brand in response:
            return DetectionResult(
                reference_type=ReferenceType.DIRECT_QUOTE,
                confidence=0.9
            )
        return DetectionResult(
            reference_type=ReferenceType.NO_REFERENCE,
            confidence=1.0
        )
```

#### REFACTOR 阶段 - 重构代码

- **前提**：所有测试通过
- **动作**：优化代码结构、消除重复、提升可读性
- **验证**：持续运行测试，确保测试始终通过
- **原则**：
  - 小步重构，每次改动后运行测试
  - 遵循 SOLID 原则和设计模式
  - 不引入新功能（新功能走新的 TDD 循环）
  - 关注代码异味（重复、过长函数、魔法数字等）

**重构后示例**：
```python
# app/services/citation_detector.py

class CitationDetector:
    def detect(self, response: str, brand: str) -> DetectionResult:
        if not response or not brand:
            raise ValueError("Response and brand are required")
        
        if self._is_direct_reference(response, brand):
            return self._create_result(ReferenceType.DIRECT_QUOTE, 0.9)
        
        if self._is_indirect_reference(response, brand):
            return self._create_result(ReferenceType.INDIRECT_REFERENCE, 0.6)
        
        return self._create_result(ReferenceType.NO_REFERENCE, 1.0)
    
    def _is_direct_reference(self, response: str, brand: str) -> bool:
        return brand in response
    
    def _create_result(self, ref_type: ReferenceType, confidence: float) -> DetectionResult:
        return DetectionResult(reference_type=ref_type, confidence=confidence)
```

## 测试层次

GEO 平台采用四层测试金字塔：

```
                    ▲
                   /│\
                  / │ \        E2E 测试（端到端）
                 /  │  \       覆盖关键用户旅程
                /───┼───\      占比：5%
               /    │    \
              /─────┼─────\    集成测试
             /      │      \   模块间交互验证
            /───────┼───────\  占比：15%
           /        │        \
          /─────────┼─────────\ 单元测试
         /          │          \ 单个函数/类验证
        /───────────┼───────────\ 占比：60%
       /            │            \
      /─────────────┼─────────────\ Agent 测试
     /              │              \ Agent 行为验证
    /───────────────┼───────────────\ 占比：20%
   ───────────────────────────────────
```

### 1. 单元测试（Unit Tests）

| 属性 | 说明 |
|------|------|
| **目标** | 验证单个函数、类或方法的行为 |
| **范围** | 隔离测试，Mock 所有外部依赖 |
| **速度** | 毫秒级，可频繁运行 |
| **工具** | Python: `pytest` + `unittest.mock`；TypeScript: `Jest` |
| **位置** | `tests/unit/` 或与被测代码同目录 `__tests__/` |
| **命名** | `test_{被测单元}_{测试场景}.py` |

**单元测试原则**：
- **FIRST 原则**：Fast（快速）、Independent（独立）、Repeatable（可重复）、Self-validating（自验证）、Timely（及时）
- **AAA 模式**：Arrange（准备）、Act（执行）、Assert（断言）
- **一个断言原则**：每个测试验证一个概念
- **Mock 外部依赖**：数据库、HTTP 请求、文件系统全部 Mock

**示例**：
```python
# tests/unit/test_citation_service.py

class TestCitationService:
    @pytest.fixture
    def mock_repo(self):
        return Mock(spec=CitationRepository)
    
    @pytest.fixture
    def service(self, mock_repo):
        return CitationService(repository=mock_repo)
    
    def test_should_save_citation_with_confidence(self, service, mock_repo):
        # Arrange
        citation = CitationCreate(brand="TestBrand", confidence=0.85)
        mock_repo.save.return_value = Citation(id=1, **citation.dict())
        
        # Act
        result = service.create_citation(citation)
        
        # Assert
        assert result.id == 1
        assert result.confidence == 0.85
        mock_repo.save.assert_called_once()
```

### 2. 集成测试（Integration Tests）

| 属性 | 说明 |
|------|------|
| **目标** | 验证多个模块之间的交互是否正确 |
| **范围** | 数据库、缓存、消息队列等真实组件 |
| **速度** | 秒级，运行频率低于单元测试 |
| **工具** | Python: `pytest` + `TestClient(FastAPI)` + `testcontainers` |
| **位置** | `tests/integration/` |
| **命名** | `test_{模块A}_{模块B}_{交互场景}.py` |

**集成测试原则**：
- 使用真实数据库（测试专用实例或 Docker 容器）
- 每个测试前后清理数据
- 测试事务隔离，失败时回滚
- 不测试外部 AI 平台 API（使用 Mock Server）

**示例**：
```python
# tests/integration/test_query_citation_flow.py

class TestQueryCitationFlow:
    @pytest.fixture
    def client(self, test_db):
        app.dependency_overrides[get_db] = lambda: test_db
        return TestClient(app)
    
    def test_should_create_query_and_detect_citations(self, client):
        # 创建查询
        response = client.post("/api/queries", json={
            "brand": "TestBrand",
            "query_template": "What is the best {brand} product?"
        })
        assert response.status_code == 201
        query_id = response.json()["id"]
        
        # 查询完成后应自动创建引用检测任务
        # 验证数据库状态
        tasks = client.get(f"/api/queries/{query_id}/tasks")
        assert len(tasks.json()) > 0
```

### 3. E2E 测试（End-to-End Tests）

| 属性 | 说明 |
|------|------|
| **目标** | 模拟真实用户操作，验证完整业务流程 |
| **范围** | 前端 + 后端 + 数据库全流程 |
| **速度** | 分钟级，CI 流水线中运行 |
| **工具** | Playwright（前端）+ pytest（后端 API） |
| **位置** | `tests/e2e/` |
| **命名** | `test_{用户旅程}_{场景}.py` |

**E2E 测试场景**：
| 场景 | 说明 | 优先级 |
|------|------|--------|
| 用户注册登录 | 完整注册 → 登录 → 访问仪表盘 | P0 |
| 创建查询 | 登录 → 创建查询 → 查看执行结果 | P0 |
| 引用检测流程 | 查询执行 → 引用检测 → 查看结果 | P0 |
| 订阅升级 | 查看计划 → 升级 → 支付 → 验证权限 | P1 |
| 代理客户管理 | 登录代理账号 → 创建客户 → 执行查询 | P1 |

### 4. Agent 测试（Agent Tests）

| 属性 | 说明 |
|------|------|
| **目标** | 验证 AI Agent 的行为和输出质量 |
| **范围** | Agent 的输入处理和输出生成 |
| **速度** | 秒级到分钟级 |
| **工具** | `pytest` + 自定义断言 |
| **位置** | `tests/agent/` |
| **命名** | `test_{agent_name}_{场景}.py` |

**Agent 测试特殊要求**：
- 使用固定的测试输入，验证输出结构和质量
- 对 AI 生成内容使用语义断言（非精确匹配）
- 评估指标：准确率、召回率、F1 分数
- 定期使用回归测试集验证 Agent 性能

**示例**：
```python
# tests/agent/test_citation_detector.py

class TestCitationDetectorAgent:
    @pytest.fixture
    def detector(self):
        return CitationDetector()
    
    def test_should_detect_brand_in_response(self, detector):
        response = "ExampleBrand is a leading company in AI."
        result = detector.detect(response, "ExampleBrand")
        
        assert result.is_referenced is True
        assert result.confidence >= 0.8
    
    def test_should_not_detect_false_positive(self, detector):
        response = "BrandX is a competitor, not ExampleBrand."
        result = detector.detect(response, "ExampleBrand")
        
        assert result.is_referenced is False
```

## 开发步骤规范

每个功能模块的开发必须遵循以下步骤：

### Step 1：需求文档

- 阅读并理解需求文档（本文档体系中的 `01-requirements/`）
- 明确功能边界、输入输出、异常场景
- 与产品经理确认需求理解无误
- 输出：功能开发任务清单

### Step 2：测试用例设计

- 基于需求编写测试用例列表
- 覆盖：正常场景、边界条件、异常处理
- 使用 Given-When-Then 格式描述
- 输出：测试用例文档

```markdown
## 测试用例：引用检测功能

### TC-001: 直接引用检测
- **Given**: AI 响应包含品牌名
- **When**: 执行引用检测
- **Then**: 返回 DIRECT_QUOTE 类型，置信度 >= 0.8

### TC-002: 未引用检测
- **Given**: AI 响应不包含品牌名
- **When**: 执行引用检测
- **Then**: 返回 NO_REFERENCE 类型，置信度 = 1.0

### TC-003: 空响应处理
- **Given**: AI 响应为空字符串
- **When**: 执行引用检测
- **Then**: 抛出 ValueError
```

### Step 3：编写失败测试

- 将测试用例转化为代码
- 运行测试，确认失败（RED）
- 提交代码（commit message: `test: add failing tests for citation detection`）

### Step 4：实现功能

- 编写最少代码使测试通过（GREEN）
- 不追求完美，先让测试通过
- 运行测试，确认通过
- 提交代码（commit message: `feat: implement citation detection`）

### Step 5：重构优化

- 审视代码，消除重复和坏味道
- 应用设计模式，提升可维护性
- 持续运行测试，确保始终通过
- 提交代码（commit message: `refactor: improve citation detection readability`）

### Step 6：集成测试

- 编写模块间的集成测试
- 验证模块协作是否正确
- 修复集成中发现的问题
- 提交代码（commit message: `test: add integration tests for query-citation flow`）

### Step 7：更新文档

- 更新模块指南文档
- 更新 API 文档（如果有接口变更）
- 更新 CHANGELOG
- 提交代码（commit message: `docs: update citation module documentation`）

## 测试覆盖要求

| 层级 | 覆盖率目标 | 检查方式 |
|------|------------|----------|
| 单元测试 | >= 80% | `pytest --cov` |
| 集成测试 | 覆盖所有 API 端点 | 手动检查 |
| E2E 测试 | 覆盖所有 P0 用户旅程 | 手动检查 |
| Agent 测试 | 覆盖核心场景 | 手动检查 |

### 覆盖率排除项

以下代码不计入覆盖率统计：
- 第三方库封装代码
- 纯数据定义（DTO、常量）
- 自动生成的代码（ORM 模型、迁移脚本）
- 调试和日志代码

## 测试运行规范

### 本地开发

```bash
# 运行所有单元测试
pytest tests/unit -v

# 运行特定模块测试
pytest tests/unit/test_citation_service.py -v

# 运行集成测试（需要本地数据库）
pytest tests/integration -v

# 运行全部测试
pytest -v

# 生成覆盖率报告
pytest --cov=app --cov-report=html

# 运行特定标记的测试
pytest -m "slow" -v
```

### CI/CD 流水线

```yaml
# .github/workflows/test.yml
jobs:
  test:
    steps:
      - name: Run Unit Tests
        run: pytest tests/unit --cov=app --cov-fail-under=80
      
      - name: Run Integration Tests
        run: pytest tests/integration
      
      - name: Run E2E Tests
        run: pytest tests/e2e
      
      - name: Upload Coverage
        uses: codecov/codecov-action@v3
```

### 测试标记（Markers）

| 标记 | 说明 | 运行方式 |
|------|------|----------|
| `unit` | 单元测试 | `pytest -m unit` |
| `integration` | 集成测试 | `pytest -m integration` |
| `e2e` | E2E 测试 | `pytest -m e2e` |
| `agent` | Agent 测试 | `pytest -m agent` |
| `slow` | 耗时测试 | `pytest -m "not slow"`（默认跳过） |
| `flaky` | 不稳定测试 | `pytest -m "not flaky"`（默认跳过） |

## 测试数据管理

### Fixtures

- 使用 `pytest.fixture` 管理测试数据
- 通用 fixtures 放在 `tests/conftest.py`
- 模块级 fixtures 放在测试文件内或同级 `conftest.py`

```python
# tests/conftest.py

@pytest.fixture(scope="function")
def test_db():
    """每个测试函数创建一个独立的数据库会话"""
    db = TestingSessionLocal()
    try:
        yield db
    finally:
        db.rollback()
        db.close()

@pytest.fixture(scope="session")
def test_user():
    """测试用户数据"""
    return {
        "email": "test@example.com",
        "password": "TestPassword123!",
        "name": "Test User"
    }
```

### 工厂模式

复杂对象使用工厂函数创建：

```python
# tests/factories.py

class QueryFactory:
    @staticmethod
    def create(brand="TestBrand", **kwargs):
        defaults = {
            "brand": brand,
            "query_template": f"What is the best {brand} product?",
            "platforms": ["chatgpt", "kimi"]
        }
        defaults.update(kwargs)
        return Query(**defaults)
```

## 前端测试规范

### 组件测试（Jest + React Testing Library）

```typescript
// components/__tests__/CitationCard.test.tsx

import { render, screen } from '@testing-library/react';
import { CitationCard } from '../CitationCard';

describe('CitationCard', () => {
  it('should display citation type and confidence', () => {
    // Arrange
    const citation = {
      type: 'direct_quote',
      confidence: 0.9,
      snippet: 'ExampleBrand is...'
    };
    
    // Act
    render(<CitationCard citation={citation} />);
    
    // Assert
    expect(screen.getByText('直接引用')).toBeInTheDocument();
    expect(screen.getByText('90%')).toBeInTheDocument();
  });
});
```

### E2E 测试（Playwright）

```typescript
// tests/e2e/query-flow.spec.ts

import { test, expect } from '@playwright/test';

test('user can create and execute a query', async ({ page }) => {
  // 登录
  await page.goto('/login');
  await page.fill('[name="email"]', 'test@example.com');
  await page.fill('[name="password"]', 'password');
  await page.click('button[type="submit"]');
  
  // 创建查询
  await page.click('text=新建查询');
  await page.fill('[name="brand"]', 'TestBrand');
  await page.click('text=执行查询');
  
  // 验证结果
  await expect(page.locator('text=查询执行中')).toBeVisible();
  await expect(page.locator('text=检测完成')).toBeVisible({ timeout: 30000 });
});
```

## 反模式与禁忌

### 禁止事项

| 反模式 | 说明 | 后果 |
|--------|------|------|
| 不写测试直接实现 | 开发完成后再补测试 | 测试成为验证工具而非设计工具 |
| 测试依赖外部服务 | 单元测试调用真实 API | 测试不稳定、速度慢 |
| 测试间共享状态 | 测试修改全局状态 | 测试顺序依赖，偶发失败 |
| 过度 Mock | Mock 过多导致测试无意义 | 无法发现真实集成问题 |
| 测试代码重复 | 大量复制粘贴测试代码 | 维护困难，变更成本高 |
| 忽略失败测试 | 跳过或注释失败测试 | 测试套件失去保护作用 |
| 测试实现细节 | 测试私有方法和内部状态 | 重构困难，脆弱测试 |

### 测试异味（Test Smells）

| 异味 | 症状 | 解决方式 |
|------|------|----------|
| 神秘访客 | 测试使用未定义的魔法值 | 使用命名常量或工厂 |
| 断言轮盘 | 大量断言难以定位失败 | 拆分为独立测试 |
| 重复代码 | 多个测试有相同准备代码 | 提取为 fixture |
| 沉睡的蜗牛 | 使用 sleep 等待异步 | 使用显式等待或回调 |
| 过多前置条件 | 测试准备代码超过 10 行 | 提取辅助方法 |

---

*本文档定义 GEO 平台的 TDD 开发流程，所有开发人员必须严格遵守。*