geo/docs/plans/2026-05-31-002-test-quality-assurance-system-plan.md

---
title: "test: GEO Platform Quality Assurance System"
type: test
status: active
date: "2026-05-31"
origin: docs/brainstorms/2026-05-31-geo-platform-next-phase-quality-requirements.md
---

## Summary

GEO 平台质量保障体系建设，采用双轨并行策略：轨道一统一测试基础设施（合并分裂目录、完善 CI、建立共享 fixture），轨道二同步推进核心业务 E2E 测试和四项专项测试（性能基线、安全扫描、迁移验证、Agent E2E），确保核心业务流程尽早获得回归保护。

## Problem Frame

GEO 平台经过多轮迭代已具备 33 个 API、8 个 Agent、25+ 前端页面，但测试覆盖严重不足：后端两套测试目录分裂导致 17 个测试被 CI 忽略，前端仅 13 个单元测试且零组件测试，E2E 仅覆盖登录流程，核心业务完全无回归保护。CI 不运行 E2E 测试，无安全扫描，无性能基线。在用户开始使用前，必须建立质量保障体系防止功能回归。

---

## Requirements

### 测试基础设施

R1. 将 `geo/tests/` 下的 17 个测试迁移至 `backend/tests/` 对应子目录，合并两套 conftest.py 的 fixture，删除旧目录

R2. CI 中 `pytest tests/` 命令能发现并运行全部后端测试

R3. 将 `pytest-cov` 正式加入 `backend/requirements.txt`

R4. 建立共享 fixture 体系：数据库会话（含自动 rollback）、认证 mock（JWT token + auth headers）、测试用户创建、httpx AsyncClient

R5. 前端 vitest 覆盖范围扩展至 `lib/api/` 全部 27 个模块和关键页面组件

R6. 更新 `docs/03-开发指南/testing.md` 使其与实际目录结构、CI 配置、fixture 体系一致

### 核心业务 E2E 测试

R7. 编写用户注册→登录→Onboarding→品牌创建的完整 E2E 测试

R8. 编写诊断→查看诊断报告→生成 GEO 方案的 E2E 测试

R9. 编写内容生成→查看内容→效果追踪的 E2E 测试

R10. E2E 测试在 CI 中运行（至少 Chromium），使用 PostgreSQL 和 Redis service container

R11. E2E 测试失败时自动截图和录制视频

### 专项测试

R12. 为 5-10 个高频 API 端点建立性能基线（p50/p95/p99 响应时间），首轮只采集不设阈值

R13. CI 中集成 bandit（Python 安全扫描）和 npm audit（Node.js 依赖安全检查），PR 级别阻断高危漏洞

R14. CI 中添加 Alembic 迁移验证步骤

R15. 编写 Agent 框架端到端测试：任务创建→分发→执行→结果查询的完整链路（至少覆盖 CitationDetector 和 ContentGenerator）

### 前端组件测试

R16. 为 5 个关键页面组件编写 React Testing Library 测试

R17. 为 4 个新 Agent 的前端 API 客户端模块编写单元测试

---

## Key Technical Decisions

KTD1. **双轨并行而非分层递进** — 基础设施统一和 E2E 测试编写同步推进，两者几乎不涉及相同文件，并行没有实质冲突。E2E 测试初期用独立 setup，后续迁移到共享 fixture 是低成本重构。

KTD2. **E2E 测试仅覆盖 Chromium** — 先在一个浏览器上稳定运行，跨浏览器扩展作为后续迭代。Playwright 已配置 3 浏览器但当前 E2E 用例太少，扩展浏览器覆盖的 ROI 不高。

KTD3. **性能测试先建基线再设阈值** — 在没有历史数据时设定 SLA 容易过严或过松。第一轮只采集数据建立基线，第二轮根据基线设定阈值和告警。

KTD4. **Agent E2E 测试优先使用真实 LLM 调用** — 可使用 LLM API Key 进行真实调用测试，确保 Agent 在实际 LLM 响应下的行为正确。CI 中通过环境变量注入 API Key，无 Key 时降级为 mock 模式。

KTD5. **安全扫描集成到 CI 而非独立流程** — bandit 和 npm audit 作为 CI 步骤运行，在 PR 级别就暴露问题。

---

## Implementation Units

### U1. 统一后端测试目录

- **Goal:** 消除测试目录分裂，确保 CI 能发现并运行全部后端测试
- **Requirements:** R1, R2, R3
- **Dependencies:** none
- **Files:**
  - `geo/tests/` (17 files to migrate)
  - `backend/tests/conftest.py` (merge fixtures)
  - `geo/tests/conftest.py` (merge then delete)
  - `backend/requirements.txt` (add pytest-cov)
  - `.github/workflows/ci.yml` (verify pytest discovers all tests)
- **Approach:** 逐个迁移 `geo/tests/` 下的测试文件到 `backend/tests/` 对应子目录（test_api/, test_services/ 等）。合并两套 conftest.py：保留 `backend/tests/conftest.py` 的内存 SQLite 引擎，从 `geo/tests/conftest.py` 迁入 async_client、auth_token、auth_headers、override_get_current_user 等 fixture。删除 `geo/tests/` 目录。将 pytest-cov 加入 requirements.txt。
- **Patterns to follow:** `backend/tests/conftest.py` 现有 fixture 模式（async_engine, async_session, test_user）
- **Test scenarios:**
  - `cd backend && pytest tests/` 发现并运行全部测试（≥77 个）
  - 迁移后的测试功能与迁移前一致
  - CI 中 pytest 命令无需修改即可运行全量测试
- **Verification:** `cd backend && pytest tests/ --tb=short` 全部通过，`geo/tests/` 目录已不存在

### U2. 建立共享 fixture 体系

- **Goal:** 为后端集成测试和 E2E 测试提供可复用的测试基础设施
- **Requirements:** R4
- **Dependencies:** U1
- **Files:**
  - `backend/tests/conftest.py` (enhance with shared fixtures)
  - `backend/tests/fixtures/` (new directory for modular fixtures)
  - `backend/tests/fixtures/auth.py` (authentication fixtures)
  - `backend/tests/fixtures/database.py` (database fixtures)
  - `backend/tests/fixtures/client.py` (httpx client fixtures)
  - `backend/tests/fixtures/brands.py` (brand and competitor test data)
- **Approach:** 在 `backend/tests/fixtures/` 下按领域拆分 fixture 模块。auth.py 提供 override_get_current_user、auth_token、auth_headers。database.py 提供 async_engine、async_session（含自动 rollback）。client.py 提供 async_client（httpx AsyncClient with app）。brands.py 提供预创建的测试品牌和竞品数据。conftest.py 通过 pytest plugin 机制自动加载 fixtures/ 下所有模块。
- **Patterns to follow:** `geo/tests/conftest.py` 中已有的 fixture 实现（async_client, auth_token, override_get_current_user）
- **Test scenarios:**
  - 使用 auth_headers fixture 的测试能成功调用需要认证的 API
  - 使用 async_client fixture 的测试能发送 HTTP 请求到 FastAPI 应用
  - 数据库 fixture 在测试结束后自动 rollback，不污染数据库
  - 多个测试并行运行时 fixture 互不干扰
- **Verification:** 使用新 fixture 编写 2-3 个示例测试并全部通过

### U3. 核心业务 E2E — 用户注册到品牌创建

- **Goal:** 覆盖用户从注册到品牌创建的完整 Onboarding 流程
- **Requirements:** R7, R11
- **Dependencies:** none (独立 setup，不依赖 U2)
- **Files:**
  - `frontend/e2e/tests/onboarding.spec.ts` (new)
  - `frontend/e2e/fixtures/auth.ts` (new, independent setup)
  - `frontend/playwright.config.ts` (verify screenshot/video config)
- **Approach:** 编写 Playwright 测试覆盖：注册新用户→登录→进入 Onboarding→填写品牌名称→添加竞品→选择平台→查看健康报告→完成引导。使用独立 setup（直接调用 API 创建测试数据），后续可迁移到共享 fixture。确保 playwright.config.ts 中 screenshot:on-failure 和 video:retain-on-failure 已配置。
- **Patterns to follow:** `frontend/e2e/tests/login.spec.ts` 现有 E2E 测试模式
- **Test scenarios:**
  - Covers AE1 (from origin): 注册→登录→Onboarding→品牌创建全流程通过
  - 注册时输入无效邮箱显示错误提示
  - 品牌名称为空时无法提交
  - 不添加竞品也能完成 Onboarding
  - 已注册用户登录后直接跳转 Dashboard
- **Verification:** `cd frontend && npx playwright test onboarding` 通过

### U4. 核心业务 E2E — 诊断到 GEO 方案

- **Goal:** 覆盖诊断→方案生成的核心业务闭环
- **Requirements:** R8, R11
- **Dependencies:** U3 (需要已登录用户和品牌)
- **Files:**
  - `frontend/e2e/tests/diagnosis-strategy.spec.ts` (new)
- **Approach:** 在 U3 创建的品牌基础上，编写：进入诊断页面→触发诊断→查看诊断报告→点击"基于诊断制定 GEO 方案"→查看方案详情。诊断和方案生成可能需要较长时间，使用适当的等待策略。
- **Patterns to follow:** `frontend/e2e/tests/login.spec.ts` 现有 E2E 测试模式
- **Test scenarios:**
  - Covers AE2 (from origin): 诊断→报告→方案生成全流程通过
  - 诊断页面正确显示品牌评分
  - 方案生成后显示行动项列表
  - 方案行动项状态可更新
- **Verification:** `cd frontend && npx playwright test diagnosis-strategy` 通过

### U5. 核心业务 E2E — 内容生成到效果追踪

- **Goal:** 覆盖内容生成→查看→效果追踪的内容工坊流程
- **Requirements:** R9, R11
- **Dependencies:** U3 (需要已登录用户和品牌)
- **Files:**
  - `frontend/e2e/tests/content-monitoring.spec.ts` (new)
- **Approach:** 编写：进入内容工坊→输入关键词→生成内容→查看生成结果→进入效果追踪页面→查看监测数据。内容生成可能需要 LLM 调用，使用较长超时或 mock。
- **Patterns to follow:** `frontend/e2e/tests/login.spec.ts` 现有 E2E 测试模式
- **Test scenarios:**
  - Covers AE3 (from origin): 内容生成→查看→效果追踪全流程通过
  - 内容生成页面正确显示生成状态
  - 生成完成后内容可查看
  - 效果追踪页面显示监测数据
- **Verification:** `cd frontend && npx playwright test content-monitoring` 通过

### U6. CI 集成 E2E 测试

- **Goal:** 将 E2E 测试纳入 CI 流水线
- **Requirements:** R10
- **Dependencies:** U3, U4, U5
- **Files:**
  - `.github/workflows/ci.yml` (add E2E step)
  - `.github/workflows/pr-check.yml` (add E2E step)
- **Approach:** 在 CI 中添加 E2E 测试步骤：启动 PostgreSQL 和 Redis service container → 启动后端服务 → 启动前端服务 → 运行 Playwright 测试。仅运行 Chromium 项目以控制时间。E2E 步骤放在单元测试之后，允许失败但不阻塞（初期），稳定后改为阻塞。
- **Patterns to follow:** 现有 CI 中 PostgreSQL 和 Redis service container 配置
- **Test scenarios:**
  - PR 提交时 CI 自动运行 E2E 测试
  - E2E 测试失败时 CI 标记为失败
  - 截图和视频作为 artifact 上传
- **Verification:** 提交一个测试 PR，观察 CI 中 E2E 步骤是否正确运行

### U7. 性能基线测试

- **Goal:** 为高频 API 端点建立性能基线数据
- **Requirements:** R12
- **Dependencies:** U2
- **Files:**
  - `backend/tests/performance/` (new directory)
  - `backend/tests/performance/__init__.py` (new)
  - `backend/tests/performance/test_api_baseline.py` (new)
  - `backend/tests/performance/conftest.py` (new)
- **Approach:** 使用 httpx AsyncClient 对 5-10 个高频端点（dashboard/stats, brands, queries, citations, content/generate, strategy/generate, monitoring/brand/{id}, analytics/overview, diagnosis, ai-engines/query）发送多次请求，采集 p50/p95/p99 响应时间，输出为 JSON 基线文件。首轮只采集不设阈值。使用 pytest-benchmark 或自定义计时逻辑。
- **Patterns to follow:** `backend/tests/` 现有测试结构
- **Test scenarios:**
  - Covers AE4 (from origin): 对 dashboard/stats 发送 100 次请求采集性能数据
  - 基线数据以 JSON 格式保存
  - 性能测试可在本地和 CI 中运行
  - 首轮不设阈值不阻断
- **Verification:** `cd backend && pytest tests/performance/ --tb=short` 运行并输出基线数据

### U8. CI 安全扫描和迁移验证

- **Goal:** 在 CI 中集成安全扫描和数据库迁移验证
- **Requirements:** R13, R14
- **Dependencies:** none
- **Files:**
  - `.github/workflows/ci.yml` (add security scan and migration steps)
  - `.github/workflows/pr-check.yml` (add security scan and migration steps)
- **Approach:** 在 CI 中添加：1) `pip install bandit && bandit -r backend/app/ -ll` 扫描 Python 代码安全问题；2) `cd frontend && npm audit --audit-level=high` 检查 Node.js 依赖漏洞；3) `cd backend && alembic upgrade head` 在空数据库上验证迁移。安全扫描发现高危问题时 CI 失败。
- **Patterns to follow:** 现有 CI 步骤结构
- **Test scenarios:**
  - Covers AE3 (from origin): PR 中引入有漏洞依赖时 CI 报告失败
  - Covers AE5 (from origin): 新增迁移脚本时 CI 验证迁移可执行
  - bandit 扫描 Python 代码中的安全问题
  - npm audit 检查前端依赖漏洞
  - alembic upgrade head 在空数据库上成功执行
- **Verification:** 提交测试 PR，观察 CI 中安全扫描和迁移验证步骤

### U9. Agent 框架 E2E 测试

- **Goal:** 测试 Agent 框架的完整任务调度链路
- **Requirements:** R15
- **Dependencies:** U2
- **Files:**
  - `backend/tests/test_agent_framework/` (new or extend existing)
  - `backend/tests/test_agent_framework/test_e2e_citation.py` (new)
  - `backend/tests/test_agent_framework/test_e2e_content.py` (new)
- **Approach:** 测试完整链路：创建 Agent 任务→Dispatcher 分发→Agent 执行→结果写入数据库→查询结果。至少覆盖 CitationDetector（citation_detect 任务）和 ContentGenerator（content_generate 任务）。优先使用真实 LLM API Key 调用，CI 中通过环境变量注入；无 Key 时降级为 mock 模式使用预定义响应。
- **Patterns to follow:** `backend/tests/test_agent_framework/` 现有 Agent 测试模式
- **Test scenarios:**
  - CitationDetector: 创建 citation_detect 任务→执行→结果包含引用数据
  - ContentGenerator: 创建 content_generate 任务→执行→结果包含生成内容
  - 任务状态从 pending→running→completed 正确流转
  - 任务失败时状态变为 failed 并记录错误信息
  - 无 Redis 时 Agent 以 standalone 模式运行
- **Verification:** `cd backend && pytest tests/test_agent_framework/test_e2e_*.py --tb=short` 通过

### U10. 前端组件和 API 客户端测试

- **Goal:** 扩展前端测试覆盖至关键组件和新 API 客户端模块
- **Requirements:** R16, R17
- **Dependencies:** none
- **Files:**
  - `frontend/__tests__/components/` (new directory)
  - `frontend/__tests__/components/dashboard.test.tsx` (new)
  - `frontend/__tests__/components/brand-detail.test.tsx` (new)
  - `frontend/__tests__/components/diagnosis.test.tsx` (new)
  - `frontend/__tests__/components/strategy.test.tsx` (new)
  - `frontend/__tests__/components/content-editor.test.tsx` (new)
  - `frontend/__tests__/api/monitoring.test.ts` (new)
  - `frontend/__tests__/api/competitor-analysis.test.ts` (new)
  - `frontend/__tests__/api/schema-advisor.test.ts` (new)
  - `frontend/__tests__/api/trends.test.ts` (new)
  - `frontend/vitest.config.ts` (extend coverage include)
- **Approach:** 使用 React Testing Library 为 5 个关键页面组件编写渲染和交互测试。使用 vitest 为 4 个新 API 客户端模块编写单元测试（mock fetchWithAuth，验证正确的 URL 和参数传递）。扩展 vitest.config.ts 的 coverage.include 配置。
- **Patterns to follow:** `frontend/__tests__/` 现有测试模式（hooks, stores, lib）
- **Test scenarios:**
  - Dashboard 组件正确渲染评分和平台数据
  - 品牌详情页正确显示 GEO 评分维度
  - 诊断页触发诊断后显示结果
  - 策略页显示 GEO 方案和行动项
  - 内容编辑器正确渲染和提交
  - monitoring.ts API 客户端调用正确的端点
  - competitor-analysis.ts API 客户端传递正确的参数
  - schema-advisor.ts API 客户端处理响应
  - trends.ts API 客户端处理查询参数
- **Verification:** `cd frontend && npm run test:ci` 通过，覆盖率报告显示 lib/api/ 模块覆盖

### U11. 更新测试策略文档

- **Goal:** 使文档与实际项目结构和 CI 配置一致
- **Requirements:** R6
- **Dependencies:** U1, U2, U6, U8
- **Files:**
  - `docs/03-开发指南/testing.md` (update)
- **Approach:** 更新 testing.md 中的目录结构描述（test_api/, test_services/ 等按领域分类），更新 fixture 体系说明（fixtures/ 模块化 fixture），更新 CI 配置示例（包含 E2E 步骤、安全扫描、迁移验证），添加 E2E 测试编写指南。
- **Patterns to follow:** 现有 testing.md 文档风格
- **Test scenarios:**
  - Test expectation: none — documentation update
- **Verification:** 文档内容与实际项目结构一致

---

## Scope Boundaries

**Deferred for later:**

- 跨浏览器 E2E 测试（Firefox / WebKit）
- 覆盖率报告上传第三方服务（Codecov / Coveralls）
- 测试数据工厂（factory-boy / faker）
- PR 评论中显示覆盖率变化
- 生产环境监控告警集成

**Outside this product's identity:**

- 新业务功能开发
- UI/UX 改进和设计优化
- 基础设施级别的渗透测试
- 移动端适配测试

### Deferred to Follow-Up Work

- E2E 测试迁移到共享 fixture（U3/U4/U5 完成后，将独立 setup 替换为 U2 的共享 fixture）
- 性能基线设定阈值和告警（U7 采集基线后，根据数据设定合理阈值）
- 跨浏览器 E2E 扩展（稳定 Chromium 后再扩展）

---

## Risks & Dependencies

- **E2E 测试稳定性** — 依赖后端服务启动和数据库初始化，CI 环境可能比本地更不稳定。缓解：E2E 初期允许失败不阻塞，稳定后再改为阻塞。
- **LLM 依赖** — 内容生成和诊断 E2E 测试可能需要 LLM 调用。缓解：使用 mock 或较长超时，Agent E2E 使用 mock LLM。
- **测试目录迁移风险** — 旧测试可能依赖 `geo/tests/conftest.py` 的特定 fixture，迁移后可能需要调整 import 路径。缓解：逐个迁移并验证。
- **CI 时间增长** — 添加 E2E、安全扫描、迁移验证会延长 CI 运行时间。缓解：E2E 仅 Chromium，安全扫描仅高危阻断，迁移验证快速执行。

---

## Sources & Research

- 现有测试配置：`backend/pyproject.toml`, `frontend/vitest.config.ts`, `frontend/playwright.config.ts`
- CI 配置：`.github/workflows/ci.yml`, `.github/workflows/pr-check.yml`
- 测试策略文档：`docs/03-开发指南/testing.md`
- 现有 E2E 测试：`frontend/e2e/tests/` (7 files)
- 现有后端测试：`backend/tests/` (~60 files) + `geo/tests/` (17 files)
- 现有前端测试：`frontend/__tests__/` (13 files)
- Origin document: `docs/brainstorms/2026-05-31-geo-platform-next-phase-quality-requirements.md`