---
date: "2026-05-31"
topic: "geo-next-phase-core-flow-repair"
---

## Summary

GEO 平台下一阶段的核心目标是实施变现闭环（诊断修复→免费获客→付费转化→执行闭环→效果归因），同时用 API 契约测试驱动核心功能修复，辅以少量 E2E 烟雾测试验证关键用户路径。原有的全面质量保障计划（E2E 覆盖、性能基线、安全扫描）降级为上线后工作。

---

## Problem Frame

GEO 平台尚未上线，存在三个致命问题阻断变现闭环：

1. **诊断系统形同虚设** — `backend/app/api/diagnosis.py` 第 75-77 行用 `GEODiagnosisInput()` 空参调用，所有字段默认 False/0，永远返回 0 分。产品核心价值为零。
2. **内容 Pipeline 只格式化不生成** — `backend/app/services/content/content_pipeline.py` 只有 4 个阶段（RuleValidator→SensitiveFilter→SEOOptimizer→HTMLGenerator），没有 AI 内容生成阶段，核心付费功能缺失。
3. **支付是模拟的** — `backend/app/services/subscription.py` 中 `payment_method="模拟支付"`，没有真实支付网关和功能限制中间件，用户无付费动力。

此外，Onboarding 缺少付费墙触发点、分发没有实际发布集成、监控没有归因逻辑、邮件服务未接入业务系统——各模块存在但互不连通。

与此同时，当前的质量保障计划（11 个 IU）将大量投入放在 E2E 测试、性能基线、安全扫描上——这些对未上线且核心功能断裂的产品来说 ROI 不高。核心矛盾：**测试体系是为稳定产品服务的，但产品本身还不稳定。**

---

## Key Decisions

**变现闭环优先于全面测试体系** — 产品核心价值为零（诊断永远 0 分），此时投入 E2E 测试、性能基线、安全扫描无法产生实际价值。先修通变现闭环，让产品可用且有收入，再建设全面质量保障。

**测试角色从"质量保障"转变为"行为契约"** — 不再是"写测试防止回归"，而是"用测试定义正确行为，驱动修复"。为变现闭环的每个新/修改 API 编写契约测试，定义期望行为，驱动实现修复。

**API 契约测试为主，E2E 烟雾测试为辅** — API 测试反馈快（秒级）、定位精确、维护成本低；E2E 只覆盖 1-2 个最关键路径作为安全网。原 QA 计划的 3 个完整 E2E 套件（U3/U4/U5）缩减为 1-2 个烟雾测试。

**获客优先于数据护城河** — 行业基准数据是长期壁垒，但在没有验证付费意愿之前投入风险过高。先用免费 GEO 健康分验证需求，再积累数据资产。

**半自动执行优先于全自动** — 品牌方不会信任 AI 完全自主发布内容。执行闭环采用"AI 生成→人工审核→确认发布"模式。

**中国 AI 平台生态为差异化核心** — 海外 SEO/GEO 工具无法覆盖文心、Kimi、通义、豆包等中国 AI 平台，这是天然护城河。

**性能基线、安全扫描、全面 E2E 推迟到上线后** — 这些投入在有用户之前无法产生实际价值。上线后根据真实数据和用户反馈决定优先级。

---

## Requirements

### 变现闭环核心修复

R1. 修复诊断系统：实现自动数据采集（AI 平台查询+网站爬取+CitationRecord 分析），让 `GEODiagnosisService.diagnose()` 接受真实数据输入，产出非零有差异的评分

R2. 添加 AI 内容生成阶段：在 ContentPipeline 前端添加 Stage 0（AI Generator），基于诊断结果+RAG 知识库+LLM 生成初稿，后续阶段不变

R3. 接入真实支付：微信支付+支付宝双通道，支付 Webhook 处理订阅状态更新，功能限制中间件按套餐控制使用量

### 获客与转化

R4. 建设免费 GEO 健康分公开页面：输入品牌名→30 秒出报告（综合评分+3 核心维度+3 竞品对比），无需注册，结果缓存 24 小时

R5. 重设计 Onboarding 流程：第一步为"查看 GEO 健康分"而非填表，在查看详细建议/执行优化/查看归因报告时嵌入升级提示

R6. 执行闭环：内容分发集成微信（半自动）/知乎（API）/头条（API），发布流程"AI 生成→人工审核→确认发布"

R7. 效果归因系统：追踪已发布内容的 AI 引用变化，2-4 周归因窗口，ROI 计算+A/B 对比报告

### API 契约测试

R8. 为诊断 API 编写契约测试：POST /api/v1/diagnosis 触发异步诊断，GET /api/v1/diagnosis/{id}/result 返回非零评分

R9. 为公开健康分 API 编写契约测试：GET /api/v1/public/health-score?brand=XXX 无需认证，返回综合评分+3 维度+竞品对比

R10. 为内容生成 API 编写契约测试：POST /api/v1/content/generate 基于诊断+RAG 生成内容

R11. 为支付 API 编写契约测试：创建订单→支付回调→订阅激活的完整链路

R12. 编写跨步骤集成测试：品牌创建→诊断→方案→内容生成→效果追踪的完整链路

### E2E 烟雾测试

R13. 编写 1 个获客路径 E2E 烟雾测试：访问健康分页面→输入品牌名→看到报告→点击注册

R14. 编写 1 个核心流程 E2E 烟雾测试：登录→创建品牌→触发诊断→查看诊断结果

### 测试基础设施（延续）

R15. 完成后端测试目录统一验证（原 QA 计划 U1）

R16. 建立共享 fixture 体系（原 QA 计划 U2）：API 契约测试完成后迁移到共享 fixture

---

## Key Flows

- F1. 变现闭环主流程
  - **Trigger:** 品牌市场人员访问平台
  - **Actors:** 品牌市场人员, 平台系统
  - **Steps:** (1) 输入品牌名查看免费 GEO 健康分 (2) 看到震撼的评分和竞品对比 (3) 注册查看详细建议 (4) 升级付费版执行优化 (5) AI 生成优化内容 (6) 人工审核确认发布 (7) 2-4 周后查看效果归因报告 (8) 续费
  - **Outcome:** 用户完成从"不知道 GEO"到"付费执行优化"到"续费"的完整闭环

- F2. API 契约驱动修复流程
  - **Trigger:** 开始修复某个断裂环节
  - **Actors:** 开发者
  - **Steps:** (1) 编写该环节的 API 契约测试，定义期望的输入/输出 (2) 运行测试，确认失败（红色） (3) 修复后端实现 (4) 运行测试，确认通过（绿色） (5) 编写下一个环节的契约测试 (6) 重复直到全链路通过
  - **Outcome:** 核心流程每步都有契约保护，断裂点被精确定位和修复

---

## Acceptance Examples

- AE1. **诊断系统修复** — Covers R1, R8
  - **Given:** 品牌已创建
  - **When:** 调用诊断 API 并传入品牌 ID
  - **Then:** 返回非零评分，且不同品牌评分有差异；免费版返回 3 核心维度，付费版返回全部 6 维度

- AE2. **免费健康分获客** — Covers R4, R9
  - **Given:** 未注册用户访问健康分页面
  - **When:** 输入品牌名
  - **Then:** 30 秒内生成包含综合评分、3 维度、3 竞品对比的报告；24 小时内重复查询返回缓存

- AE3. **AI 内容生成** — Covers R2, R10
  - **Given:** 付费用户有诊断结果和知识库
  - **When:** 触发内容生成
  - **Then:** 基于诊断问题+RAG 上下文生成针对性优化内容，内容通过 Pipeline 校验

- AE4. **支付闭环** — Covers R3, R11
  - **Given:** 用户选择升级套餐
  - **When:** 完成支付
  - **Then:** 订阅状态更新为 active，功能限制中间件解锁对应功能

- AE5. **E2E 烟雾测试** — Covers R13, R14
  - **Given:** 前后端服务运行
  - **When:** 执行 Playwright E2E 烟雾测试
  - **Then:** 获客路径和核心流程路径通过

---

## Success Criteria

- 诊断系统产出真实非零评分，不同品牌有差异
- 免费 GEO 健康分页面可公开访问，30 秒内出报告
- AI 内容生成基于诊断结果产出可用内容
- 支付闭环可走通（创建订单→支付→激活→功能解锁）
- 核心流程 API 契约测试全部通过
- 2 个 E2E 烟雾测试通过

---

## Scope Boundaries

**Deferred for later:**

- 全面 E2E 测试覆盖（原 QA 计划 U3/U4/U5 → 上线后逐步扩展）
- 性能基线测试（原 QA 计划 U7 → 上线后有真实负载后建立）
- CI 安全扫描（原 QA 计划 U8 → 上线后集成）
- Alembic 迁移验证（原 QA 计划 U8 → 上线后添加）
- 前端组件测试（原 QA 计划 U10 → 上线后扩展）
- 行业 GEO 基准数据积累
- API 市场开放和第三方集成
- 白标报告和专属客户成功经理
- 多语言和国际 AI 平台支持

**Outside this product's identity:**

- 传统 SEO 工具功能（关键词排名、外链分析等）
- 广告投放和营销自动化
- 社交媒体管理
- 基础设施级别的渗透测试

---

## Dependencies / Assumptions

- 变现闭环实施计划已存在：`docs/plans/2026-05-31-003-feat-geo-monetization-closed-loop-plan.md`
- 诊断自动数据采集依赖现有 AI 平台适配器（`backend/app/services/ai_engine/`）
- AI 内容生成依赖 LLM API Key 可用
- 支付集成需要微信支付和支付宝商户号
- 知乎/头条 API 发布需要 OAuth 授权和 API Key
- API 契约测试使用 httpx AsyncClient + 内存 SQLite，不依赖外部服务
- E2E 烟雾测试需要前后端服务同时运行
- 假设品牌方看到 GEO 健康分后会意识到问题并产生付费意愿（未验证，需 MVP 验证）

---

## Outstanding Questions

**Deferred to Planning:**

- 效果归因的具体技术实现方案（基于引用检测还是基于评分变化）
- 付费版定价是否需要调整（当前 ¥199/599/1999 是否匹配价值感知）
- 微信公众号 OAuth 授权流程的具体实现方案
- 知乎和头条 API 的申请和审核周期
- 诊断自动数据采集的网站爬取可能遇到反爬机制的降级方案

---

## Sources / Research

- 变现闭环需求文档：`docs/brainstorms/2026-05-31-geo-platform-monetization-closed-loop-requirements.md`
- 变现闭环实施计划：`docs/plans/2026-05-31-003-feat-geo-monetization-closed-loop-plan.md`
- 质量保障需求文档：`docs/brainstorms/2026-05-31-geo-platform-next-phase-quality-requirements.md`
- 质量保障实施计划：`docs/plans/2026-05-31-002-test-quality-assurance-system-plan.md`
- 诊断系统根因：`backend/app/api/diagnosis.py` 第 75-77 行（空参调用）
- 内容 Pipeline：`backend/app/services/content/content_pipeline.py`（4 阶段，无 AI 生成）
- 订阅服务：`backend/app/services/subscription.py`（模拟支付）
- 现有后端测试：`backend/tests/` (~90 个文件)
- 现有 E2E 测试：`frontend/e2e/tests/` (7 个文件)
