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

title	type	status	date	origin
test: GEO Platform Quality Assurance System	test	active	2026-05-31	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