fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/docs/brainstorms/2026-05-31-geo-platform-nex...

7.7 KiB
Raw Permalink Blame History

date topic
2026-05-31 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 个）