---
date: "2026-05-31"
topic: "geo-platform-next-phase-quality"
---

## Summary

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

## Problem Frame

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

---

## Key Decisions

**双轨并行而非分层递进** — 基础设施统一和 E2E 测试编写同步推进，因为两者几乎不涉及相同文件，并行没有实质冲突。E2E 测试初期用独立 setup，后续迁移到共享 fixture 是低成本重构。如果等基础设施全部就绪再写 E2E，核心流程的回归保护会延迟数周。

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

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

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

---

## Requirements

### 轨道一：测试基础设施

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

R2. CI 中 `pytest tests/` 命令能发现并运行全部后端测试（迁移后应 ≥77 个）

R3. 将 `pytest-cov` 正式加入 `backend/requirements.txt`，不再依赖 CI 中临时安装

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 迁移验证步骤：`alembic upgrade head` 在空数据库上成功执行

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

### 前端组件测试

R16. 为 5 个关键页面组件编写 React Testing Library 测试：Dashboard、品牌详情、诊断页、策略页、内容编辑器

R17. 为 4 个新 Agent 的前端 API 客户端模块编写单元测试：monitoring.ts、competitor-analysis.ts、schema-advisor.ts、trends.ts

---

## Key Flows

- F1. 双轨并行执行流程
  - **Trigger:** 需求文档确认后启动
  - **Actors:** 开发者
  - **Steps:** (1) 轨道一：统一测试目录→合并 fixture→修复 CI→扩展 vitest 覆盖 (2) 轨道二：编写核心 E2E→集成 CI E2E 步骤→编写专项测试 (3) 两条轨道完成后汇合：E2E 测试迁移到共享 fixture (4) 更新文档
  - **Outcome:** 完整的质量保障体系，CI 全量运行，核心流程有回归保护

- F2. E2E 测试编写流程
  - **Trigger:** 开始编写某个业务流程的 E2E 测试
  - **Actors:** 开发者
  - **Steps:** (1) 定义用户旅程步骤 (2) 编写 Playwright 测试用独立 setup (3) 本地验证通过 (4) 提交并在 CI 中验证 (5) 后续迁移到共享 fixture
  - **Outcome:** 可在 CI 中稳定运行的 E2E 测试

---

## Acceptance Examples

- AE1. **测试目录统一** — Covers R1, R2
  - **Given:** `geo/tests/` 下有 17 个测试文件
  - **When:** 迁移完成并运行 `cd backend && pytest tests/`
  - **Then:** 全部测试被发现且通过，`geo/tests/` 目录已删除

- AE2. **核心业务 E2E** — Covers R7, R8, R9
  - **Given:** 后端服务 + PostgreSQL + Redis 运行
  - **When:** 执行 Playwright E2E 测试
  - **Then:** 注册→登录→Onboarding→品牌创建→诊断→方案→内容生成→效果追踪 全流程通过

- AE3. **CI 安全扫描** — Covers R13
  - **Given:** PR 中引入了有已知漏洞的依赖
  - **When:** CI 运行 PR Check
  - **Then:** bandit 或 npm audit 报告高危漏洞，PR 被标记为检查失败

- AE4. **性能基线** — Covers R12
  - **Given:** 性能测试首次运行
  - **When:** 对 `/api/v1/dashboard/stats` 发送 100 次请求
  - **Then:** 采集 p50/p95/p99 响应时间并保存为基线数据，不设阈值不阻断

- AE5. **迁移验证** — Covers R14
  - **Given:** 新增了 Alembic 迁移脚本
  - **When:** CI 在空数据库上执行 `alembic upgrade head`
  - **Then:** 迁移成功执行，无报错

---

## Success Criteria

- 后端全部测试（≥77 个）在 CI 中通过，无目录分裂
- 核心业务 E2E 测试（≥3 条用户旅程）在 CI 中稳定运行
- 前端 vitest 覆盖率从当前极低水平提升至 lib/api/ 模块 80%+
- CI 流水线包含：lint + 单元测试 + E2E 测试 + 安全扫描 + 迁移验证
- 5-10 个高频 API 端点有性能基线数据
- Agent 框架端到端测试覆盖至少 2 个 Agent
- testing.md 与实际项目结构一致

---

## Scope Boundaries

**Deferred for later:**

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

**Outside this product's identity:**

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

---

## Dependencies / Assumptions

- CI 环境（GitHub Actions）支持 PostgreSQL 和 Redis service container
- E2E 测试需要后端服务可启动（所有依赖可用）
- Agent E2E 测试需要至少一个 LLM Provider 的 API Key 可用（或使用 mock）
- 性能基线数据需要在相对稳定的环境下采集，避免 CI 共享 runner 的噪声
- 当前 `geo/tests/conftest.py` 中的 fixture（async_client、auth_token 等）可正确迁移

---

## 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 个文件）
- 现有后端测试：`backend/tests/`（~60 个）+ `geo/tests/`（17 个）
- 现有前端测试：`frontend/__tests__/`（13 个）
