geo/docs/plans/2026-05-31-003-feat-geo-monetization-closed-loop-plan.md

---
title: "feat: GEO Platform Monetization Closed Loop"
type: feat
status: completed
date: "2026-05-31"
origin: docs/brainstorms/2026-05-31-geo-next-phase-core-flow-repair-requirements.md
secondary-origin: docs/brainstorms/2026-05-31-geo-platform-monetization-closed-loop-requirements.md
---

## Summary

修复 GEO 诊断系统（当前空输入=0 分）、建设免费 GEO 健康分获客入口、接入真实支付与功能限制、添加 AI 内容生成能力、打通内容分发与效果归因闭环，实现从获客到续费的完整商业变现链路。同时用 API 契约测试驱动核心功能修复，辅以少量 E2E 烟雾测试验证关键用户路径。

## Problem Frame

GEO 平台已具备 8 个 Agent、6 维度诊断框架、内容 Pipeline、知识库 RAG 等模块，但三个致命问题阻断了变现闭环：(1) 诊断系统使用空输入调用，永远返回 0 分，产品核心价值为零；(2) 内容 Pipeline 只做格式化不生成内容，核心付费功能缺失；(3) 支付是模拟的，没有功能限制，用户无付费动力。此外，Onboarding 缺少付费墙触发点、分发没有实际发布集成、监控没有归因逻辑、邮件服务未接入业务系统——各模块存在但互不连通。

## Requirements

Origin: `docs/brainstorms/2026-05-31-geo-next-phase-core-flow-repair-requirements.md`

- R1. 修复诊断系统：实现自动数据采集，让诊断产出非零有差异的评分 → U1
- R2. 添加 AI 内容生成阶段：在 ContentPipeline 前端添加 Stage 0 → U5
- R3. 接入真实支付：微信支付+支付宝+功能限制中间件 → U4
- R4. 建设免费 GEO 健康分公开页面 → U2
- R5. 重设计 Onboarding 流程，嵌入付费墙触发点 → U3
- R6. 执行闭环：内容分发集成微信/知乎/头条 → U5
- R7. 效果归因系统 → U6
- R8. 为诊断 API 编写契约测试 → U1
- R9. 为公开健康分 API 编写契约测试 → U2
- R10. 为内容生成 API 编写契约测试 → U5
- R11. 为支付 API 编写契约测试 → U4
- R12. 编写跨步骤集成测试 → U8
- R13. 编写获客路径 E2E 烟雾测试 → U9
- R14. 编写核心流程 E2E 烟雾测试 → U9
- R15. 完成后端测试目录统一验证 → U8
- R16. 建立共享 fixture 体系 → U8

## Key Technical Decisions

KTD-1. **诊断自动数据采集采用"AI 平台查询+CitationRecord 分析"双通道方案（V1 跳过网站爬取）。** 通过调用现有 AI 平台适配器查询品牌关键词分析引用情况，通过分析已有 CitationRecord 数据聚合引用指标。网站爬取通道留待 V2 迭代，降低首版复杂度。AI 平台查询填充"引用就绪度"维度，CitationRecord 分析填充"E-E-A-T/主题权威"维度，品牌官网 URL 解析填充"内容可提取性/Schema 标记"维度（基于简单 HTTP GET + HTML 解析，非完整爬取）。

KTD-2. **免费 GEO 健康分页面为独立公开页面，不依赖现有 Dashboard。** 新建 `/health-score` 路由，无需认证即可访问。结果缓存 24 小时（按品牌名+竞品哈希），避免重复查询消耗 API 额度。

KTD-3. **支付集成采用微信支付+支付宝双通道。** 使用官方 SDK，后端实现支付回调 Webhook 处理订阅状态更新。

KTD-4. **AI 内容生成集成到现有 ContentPipeline 前端。** 在 Stage 1(RuleValidator) 之前添加 Stage 0(AI Generator)，基于诊断结果+RAG 知识库+LLM 生成初稿，后续阶段不变。

KTD-5. **效果归因采用"内容发布时间窗口+引用变化关联"方案。** 发布内容时记录时间戳和基线引用数据，2-4 周内定期检查引用变化。

KTD-6. **微信公众号采用半自动模式。** 生成内容+格式化+一键复制，用户手动粘贴到公众号编辑器。知乎和头条利用 API 实现自动发布。

KTD-7. **API 契约测试驱动修复，E2E 仅做烟雾测试。** 每个核心 API 先写契约测试定义期望行为，再修复实现。E2E 只覆盖 2 个最关键路径（获客+核心流程），不追求全面覆盖。

## High-Level Technical Design

```mermaid
flowchart TB
    subgraph Phase1["Phase 1: 核心价值修复 + 契约测试"]
        A[品牌名输入] --> B[自动数据采集]
        B --> B1[AI平台查询]
        B --> B2[CitationRecord分析]
        B1 & B2 --> C[GEO诊断引擎]
        C --> D[6维度评分]
        D --> T1[诊断API契约测试]
    end

    subgraph Phase2["Phase 2: 获客入口 + 契约测试"]
        D --> E[免费健康分页面]
        E --> F{查看详细建议?}
        F -->|免费概要| G[注册]
        F -->|完整分析| G
        G --> H{执行优化?}
        H -->|升级付费| I[订阅支付]
        E --> T2[健康分API契约测试]
    end

    subgraph Phase3["Phase 3: 执行闭环 + 契约测试"]
        I --> J[AI内容生成]
        J --> K[人工审核]
        K --> L[发布到平台]
        L --> M[效果归因追踪]
        M --> N[ROI报告]
        N --> O[续费/升级]
        J --> T3[内容生成API契约测试]
        I --> T4[支付API契约测试]
    end

    subgraph Phase4["Phase 4: 集成验证"]
        T1 & T2 & T3 & T4 --> T5[跨步骤集成测试]
        T5 --> T6[E2E烟雾测试]
    end
```

## Implementation Units

### U1. GEO 诊断自动数据采集与修复

**Goal:** 修复当前诊断系统（空输入=0 分），实现自动数据采集填充 GEODiagnosisInput，让诊断产出真实有价值的分数。

**Requirements:** R1, R8

**Dependencies:** 无

**Files:**
- `backend/app/services/diagnosis/geo_diagnosis.py` — 修改诊断服务，添加自动数据采集
- `backend/app/services/diagnosis/data_collector.py` — 新建自动数据采集服务
- `backend/app/api/diagnosis.py` — 修改 API 端点，支持自动采集+异步诊断
- `backend/app/schemas/diagnosis.py` — 新建诊断请求/响应 schema
- `backend/app/models/diagnosis_record.py` — 新建诊断历史记录模型
- `backend/tests/test_api/test_diagnosis_contract.py` — 新建诊断 API 契约测试
- `backend/tests/test_services/test_data_collector.py` — 新建数据采集服务测试

**Approach:**
1. 新建 `DataCollectorService`，两个采集通道（V1）：
   - AI 平台查询通道：复用现有 `ai_engine` 适配器，查询品牌相关关键词，分析引用情况填充"引用就绪度"维度
   - 历史数据通道：从 CitationRecord 聚合已有引用数据，填充"E-E-A-T/主题权威"维度
   - 品牌官网解析：简单 HTTP GET + HTML 解析（检查 Schema 标记、标题层级等），填充"内容可提取性/Schema 标记"维度
2. 修改 `GEODiagnosisService.diagnose()` 接受 `DataCollectorOutput` 作为输入
3. 修改诊断 API 端点：`POST /api/v1/diagnosis/geo/{brand_id}` 触发异步诊断，`GET /api/v1/diagnosis/geo/{brand_id}/result` 轮询结果
4. 诊断结果持久化到 `diagnosis_records` 表，支持历史对比
5. 免费版返回综合分+3 核心维度，付费版返回全部 6 维度
6. **先写契约测试**：定义诊断 API 的期望行为（非零评分、维度结构、免费/付费差异），再修复实现

**Execution note:** 先写诊断 API 契约测试（红色），再实现 DataCollectorService 和修改诊断服务（绿色）。

**Patterns to follow:**
- 复用 `backend/app/services/ai_engine/` 下的平台适配器
- 复用 `backend/app/workers/citation_engine.py` 的查询执行模式
- 异步任务模式参考 `backend/app/services/detection/detection_scheduler.py`
- 契约测试参考 `backend/tests/conftest.py` 中的 async_client fixture

**Test scenarios:**
- 输入有效品牌名，自动采集数据并返回非零诊断分数
- 输入不存在的品牌名，返回低分但非零（基于 AI 平台查询结果）
- 免费用户请求诊断，只返回 3 个核心维度
- 付费用户请求诊断，返回全部 6 维度
- 同一品牌 24 小时内重复请求，返回缓存结果
- 诊断结果持久化，第二次诊断可展示历史对比
- 契约测试：POST /api/v1/diagnosis/geo/{brand_id} 返回 202 + task_id
- 契约测试：GET /api/v1/diagnosis/geo/{brand_id}/result 返回非零 overall_score

**Verification:** 调用 `POST /api/v1/diagnosis/geo/{brand_id}` 返回真实非零评分，且不同品牌评分有差异。契约测试全部通过。

---

### U2. 免费 GEO 健康分公开页面

**Goal:** 建设无需注册即可访问的 GEO 健康分页面，作为获客和市场教育的核心入口。

**Requirements:** R4, R9

**Dependencies:** U1

**Files:**
- `frontend/app/(public)/health-score/page.tsx` — 新建公开健康分页面
- `frontend/app/(public)/health-score/components/ScoreCard.tsx` — 评分卡片组件
- `frontend/app/(public)/health-score/components/CompetitorComparison.tsx` — 竞品对比组件
- `frontend/app/(public)/health-score/components/ShareButton.tsx` — 分享按钮组件
- `frontend/lib/api/health-score.ts` — 健康分 API 客户端
- `backend/app/api/health_score.py` — 新建公开健康分 API（无需认证）
- `backend/app/schemas/health_score.py` — 健康分响应 schema
- `backend/tests/test_api/test_health_score_contract.py` — 新建健康分 API 契约测试

**Approach:**
1. 新建公开路由 `/health-score`，无需登录即可访问
2. 页面核心交互：输入品牌名 → 30 秒内展示 GEO 健康分报告
3. 报告内容：综合评分（大数字+健康等级色标）、3 核心维度雷达图、3 竞品对比柱状图、最严重 3 个问题概要
4. "查看详细修复建议"按钮 → 触发注册弹窗
5. 注册后自动关联本次诊断结果到用户账户
6. 支持生成可分享链接（含品牌名参数）和 PDF 下载
7. 后端：`GET /api/v1/public/health-score?brand=XXX` 无需认证，返回免费版诊断结果
8. 结果缓存 24 小时（Redis），避免重复查询

**Patterns to follow:**
- 前端页面参考 `frontend/app/(dashboard)/onboarding/Step4HealthReport.tsx` 的报告展示模式
- API 参考 `backend/app/api/diagnosis.py` 但无需认证
- 分享功能参考 `backend/app/api/reports.py` 的 PDF 生成

**Test scenarios:**
- 未登录用户输入品牌名，30 秒内看到健康分报告
- 报告包含综合评分、3 维度、3 竞品对比
- 点击"查看详细建议"弹出注册弹窗
- 注册后诊断结果自动关联到账户
- 生成可分享链接，他人打开看到相同报告
- 24 小时内重复查询同一品牌返回缓存结果
- 契约测试：GET /api/v1/public/health-score?brand=XXX 返回 200 + 非零评分
- 契约测试：无品牌名参数返回 422

**Verification:** 未登录状态下访问 `/health-score`，输入品牌名后看到完整报告且可分享。契约测试通过。

---

### U3. Onboarding 重设计与转化层

**Goal:** 重设计 Onboarding 流程以"查看 GEO 健康分"为第一步，嵌入付费墙触发点。

**Requirements:** R5

**Dependencies:** U1, U2

**Files:**
- `frontend/app/(dashboard)/onboarding/page.tsx` — 重写 Onboarding 主页面
- `frontend/app/(dashboard)/onboarding/Step0HealthScore.tsx` — 新建第一步：健康分
- `frontend/app/(dashboard)/onboarding/Step1BrandName.tsx` — 修改为简化版
- `frontend/app/(dashboard)/onboarding/Step4HealthReport.tsx` — 修改为含升级提示
- `frontend/app/(dashboard)/onboarding/Step5ActionSuggestions.tsx` — 修改为含执行按钮+付费墙
- `frontend/components/subscription/UpgradePrompt.tsx` — 新建升级提示组件

**Approach:**
1. 新流程：Step0(输入品牌名看健康分) → Step1(注册/登录) → Step2(补充竞品信息) → Step3(查看详细报告+升级提示) → Step4(行动建议+执行按钮)
2. Step0 直接复用 U2 的健康分页面组件，嵌入 Onboarding 流程
3. 在以下场景嵌入升级提示：
   - 查看详细 6 维度分析时 → "升级 Pro 版查看完整分析"
   - 点击执行优化建议时 → "升级 Starter 版开始优化"
   - 查看效果归因报告时 → "升级 Pro 版追踪优化效果"
4. 升级提示组件 `UpgradePrompt` 统一管理，显示当前套餐限制和升级收益

**Patterns to follow:**
- 现有 Onboarding 步骤组件模式（Step1-5 的 props 接口）
- `useOnboardingData` hook 的数据管理模式

**Test scenarios:**
- 新用户进入 Onboarding，第一步看到健康分输入框
- 输入品牌名后看到免费健康分报告
- 注册后继续 Onboarding，看到详细报告含升级提示
- 免费用户点击"执行优化"时看到升级弹窗
- 已完成 Onboarding 的用户不再看到引导

**Verification:** 新用户从健康分开始 Onboarding，在关键节点看到升级提示。

---

### U4. 真实支付集成与功能限制

**Goal:** 接入微信支付+支付宝，实现功能限制中间件，让付费真正生效。

**Requirements:** R3, R11

**Dependencies:** U3

**Files:**
- `backend/app/services/payment/wechat_pay.py` — 新建微信支付服务
- `backend/app/services/payment/alipay.py` — 新建支付宝服务
- `backend/app/services/payment/base.py` — 新建支付基类
- `backend/app/api/payments.py` — 新建支付 API 端点
- `backend/app/middleware/subscription_enforcement.py` — 新建功能限制中间件
- `backend/app/services/subscription.py` — 修改添加真实支付逻辑
- `backend/app/api/subscriptions.py` — 修改添加支付 Webhook
- `backend/app/models/subscription.py` — 修改添加支付相关字段
- `backend/tests/test_api/test_payment_contract.py` — 新建支付 API 契约测试
- `backend/tests/test_services/test_payment.py` — 新建支付服务测试

**Approach:**
1. 支付基类定义统一接口：`create_order`, `verify_callback`, `refund`
2. 微信支付：使用官方 SDK，实现 JSAPI 支付（H5 页面）和 Native 支付（扫码）
3. 支付宝：使用官方 SDK，实现手机网站支付
4. 支付 Webhook：`POST /api/v1/payments/callback/wechat` 和 `/alipay`，验证签名后更新订阅状态
5. 功能限制中间件：在 API 路由层检查用户套餐，超限返回 403+升级提示
6. 限制维度：查询数/品牌数/诊断频率/内容生成数/知识库数/数据保留期
7. **先写契约测试**：定义支付 API 的期望行为（创建订单、回调处理、功能限制）

**Execution note:** 先写支付 API 契约测试（红色），再实现支付服务（绿色）。

**Patterns to follow:**
- 支付回调参考 `backend/app/api/auth.py` 的 Webhook 处理模式
- 功能限制参考 `backend/app/middleware/rate_limit.py` 的中间件模式
- 订阅逻辑复用 `backend/app/services/subscription.py` 的 PLANS 配置

**Test scenarios:**
- 创建支付订单，返回支付链接/二维码
- 支付成功回调，订阅状态更新为 active
- 免费用户超出查询限制，返回 403+升级提示
- Pro 用户在限制内正常使用
- 支付失败回调，订阅状态不变
- 订阅到期，自动降级为免费版
- 契约测试：POST /api/v1/payments/orders 返回 201 + order_id + pay_url
- 契约测试：POST /api/v1/payments/callback/wechat 验证签名后更新订阅

**Verification:** 完整支付流程：创建订单→支付→回调→订阅激活→功能解锁。契约测试通过。

---

### U5. AI 内容生成与分发集成

**Goal:** 在 ContentPipeline 前端添加 AI 生成阶段，集成知乎/头条 API 发布和微信半自动发布。

**Requirements:** R2, R6, R10

**Dependencies:** U1, U4

**Files:**
- `backend/app/services/content/ai_generator.py` — 新建 AI 内容生成服务
- `backend/app/services/content/content_pipeline.py` — 修改添加 Stage 0
- `backend/app/services/distribution/publishers/zhihu_publisher.py` — 新建知乎发布器
- `backend/app/services/distribution/publishers/toutiao_publisher.py` — 新建头条发布器
- `backend/app/services/distribution/publishers/wechat_publisher.py` — 新建微信半自动发布器
- `backend/app/services/distribution/publish_engine.py` — 新建发布引擎
- `backend/app/api/distribution.py` — 修改添加发布 API
- `backend/tests/test_api/test_content_contract.py` — 新建内容生成 API 契约测试
- `backend/tests/test_services/test_ai_generator.py` — 新建 AI 生成测试
- `backend/tests/test_services/test_publishers.py` — 新建发布器测试

**Approach:**
1. AI 内容生成服务：
   - 输入：诊断结果（问题维度）+ RAG 知识库上下文 + 目标关键词 + 目标平台
   - 调用 LLM 生成初稿，基于诊断结果针对性优化
   - 输出传入现有 Pipeline（RuleValidator → SensitiveFilter → SEOOptimizer → HTMLGenerator）
2. 发布引擎：
   - 知乎：通过知乎创作中心 API 发布文章（需 OAuth 授权）
   - 头条：通过头条号 API 发布文章（需 API Key）
   - 微信：生成格式化内容+复制引导，不直接调用 API
3. 发布流程：AI 生成 → 人工预览/编辑 → 确认发布 → 调用对应 Publisher → 记录发布状态
4. 发布记录关联到 Content 模型，用于后续归因

**Patterns to follow:**
- AI 生成参考 `backend/app/services/content/content_generation_service.py` 的 LLM 调用模式
- RAG 集成参考 `backend/app/services/knowledge/rag_service.py`
- 平台规则复用 `backend/app/services/distribution/platform_rules.py`
- Publisher 模式参考 `backend/app/services/ai_engine/` 的适配器模式

**Test scenarios:**
- 基于诊断结果+知识库上下文生成针对性优化内容
- 生成内容通过 Pipeline 校验（RuleValidator + SensitiveFilter）
- 知乎 API 发布成功，返回文章 URL
- 头条 API 发布成功，返回文章 URL
- 微信半自动模式生成格式化内容+复制引导
- 发布记录保存到 Content 模型，状态为 published
- 契约测试：POST /api/v1/content/generate 返回 201 + content_id + 生成内容

**Verification:** 从诊断建议到内容生成到发布的完整流程可走通。契约测试通过。

---

### U6. 效果归因系统与 ROI 报告

**Goal:** 建设效果归因系统，追踪已发布内容的 AI 引用变化，生成 ROI 报告证明付费价值。

**Requirements:** R7

**Dependencies:** U5

**Files:**
- `backend/app/services/attribution/attribution_engine.py` — 新建归因引擎
- `backend/app/services/attribution/roi_calculator.py` — 新建 ROI 计算器
- `backend/app/api/attribution.py` — 新建归因 API
- `backend/app/models/attribution_record.py` — 新建归因记录模型
- `backend/app/services/monitoring/monitor_service.py` — 修改集成归因
- `frontend/app/(dashboard)/dashboard/roi/page.tsx` — 新建 ROI 报告页面
- `frontend/lib/api/attribution.ts` — 新建归因 API 客户端
- `backend/tests/test_services/test_attribution.py` — 新建归因测试

**Approach:**
1. 归因引擎核心逻辑：
   - 内容发布时记录：发布时间、目标关键词、发布前基线引用数据
   - 定期（每 3 天）检查目标关键词的引用变化
   - 归因判定：引用率上升 + 新引用内容与已发布内容语义相关 → 归因为该内容贡献
   - 归因窗口：2-4 周，窗口内持续追踪
2. ROI 计算器：输入订阅费用+归因引用提升+行业平均引用价值，输出 GEO ROI 百分比
3. A/B 对比报告：优化前诊断分数 vs 当前诊断分数，按维度对比
4. 效果保障：如果 2-4 周内无任何引用提升，提供额外优化建议或延长服务

**Patterns to follow:**
- 监控模式参考 `backend/app/services/monitoring/monitor_service.py`
- 定期任务参考 `backend/app/services/detection/detection_scheduler.py`
- 报告生成参考 `backend/app/api/reports.py`

**Test scenarios:**
- 发布内容后自动创建归因追踪记录
- 3 天后检查引用变化，记录 delta
- 引用率上升且语义相关，归因为该内容贡献
- 归因窗口结束后生成 ROI 报告
- 优化前后 A/B 对比报告展示各维度变化
- 无引用提升时提供额外优化建议

**Verification:** 发布内容→2-4 周后→归因报告展示引用提升和 ROI。

---

### U7. 邮件集成与 Dashboard 变现 UI

**Goal:** 将 EmailService 接入业务系统（周报、续费提醒），Dashboard 添加订阅状态、用量进度、ROI 面板。

**Requirements:** R7 (邮件部分)

**Dependencies:** U4, U6

**Files:**
- `backend/app/services/email_service.py` — 修改添加新模板
- `backend/app/services/email/email_scheduler.py` — 新建邮件调度器
- `backend/app/templates/geo_weekly_report.html` — 新建周报模板
- `backend/app/templates/renewal_reminder.html` — 新建续费提醒模板
- `backend/app/templates/trial_expiring.html` — 新建试用期到期模板
- `frontend/app/(dashboard)/dashboard/page.tsx` — 修改添加变现 UI
- `frontend/components/subscription/SubscriptionStatus.tsx` — 新建订阅状态组件
- `frontend/components/subscription/UsageProgress.tsx` — 新建用量进度组件
- `frontend/components/dashboard/ROICard.tsx` — 新建 ROI 卡片组件

**Approach:**
1. 邮件模板新增：GEO 变化周报、续费提醒（到期前 7 天/3 天/1 天）、试用期到期提醒、欢迎邮件
2. 邮件调度器：APScheduler 定时任务，每周一发送周报，每日检查续费提醒
3. Dashboard 变现 UI：顶部订阅状态栏、用量进度条、ROI 卡片、功能锁定 UI
4. 配置真实 SMTP（支持 SendGrid/阿里云邮件推送）

**Patterns to follow:**
- 邮件模板参考 `backend/app/services/email_service.py` 现有模板格式
- Dashboard 组件参考 `frontend/app/(dashboard)/dashboard/page.tsx` 的 KPI 卡片模式
- 订阅状态参考 `backend/app/services/subscription.py` 的 PLANS 配置

**Test scenarios:**
- 每周一自动发送 GEO 变化周报给注册用户
- 订阅到期前 7 天发送续费提醒
- 试用期到期前 3 天发送提醒
- Dashboard 显示当前套餐和用量进度
- 超出用量时显示升级提示
- ROI 卡片展示引用率提升和归因内容

**Verification:** 注册用户收到周报邮件，Dashboard 显示订阅状态和 ROI 数据。

---

### U8. API 契约集成测试与测试基础设施

**Goal:** 编写跨步骤集成测试验证完整链路，完成后端测试基础设施统一。

**Requirements:** R12, R15, R16

**Dependencies:** U1, U2, U4, U5

**Files:**
- `backend/tests/test_integration/test_monetization_flow.py` — 新建变现闭环集成测试
- `backend/tests/conftest.py` — 增强 fixture 体系
- `backend/tests/fixtures/auth.py` — 新建认证 fixture 模块
- `backend/tests/fixtures/database.py` — 新建数据库 fixture 模块
- `backend/tests/fixtures/client.py` — 新建 httpx 客户端 fixture 模块
- `backend/tests/fixtures/brands.py` — 新建品牌测试数据 fixture 模块

**Approach:**
1. 编写跨步骤集成测试：品牌创建→诊断→方案→内容生成→效果追踪的完整链路
2. 验证 U1-U5 的 API 契约测试在集成场景下仍然通过
3. 完成后端测试目录统一验证（原 QA 计划 U1）
4. 建立共享 fixture 体系：按领域拆分到 `backend/tests/fixtures/` 下
   - 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：预创建的测试品牌和竞品数据
5. conftest.py 通过 pytest plugin 机制自动加载 fixtures/ 下所有模块

**Patterns to follow:**
- `backend/tests/conftest.py` 现有 fixture 模式
- `backend/tests/test_integration/test_business_flow.py` 现有集成测试模式

**Test scenarios:**
- 品牌创建→诊断→方案→内容生成→效果追踪全链路通过
- 数据在步骤间正确传递（品牌 ID、诊断结果 ID、内容 ID）
- 共享 fixture 可被其他测试复用
- 数据库 fixture 在测试结束后自动 rollback
- 多个测试并行运行时 fixture 互不干扰

**Verification:** `cd backend && pytest tests/test_integration/test_monetization_flow.py --tb=short` 通过。`cd backend && pytest tests/ -q` 全部测试被发现且无新增失败。

---

### U9. E2E 烟雾测试

**Goal:** 编写 2 个关键路径的 Playwright E2E 烟雾测试，验证最核心的用户路径端到端可用。

**Requirements:** R13, R14

**Dependencies:** U2, U3

**Files:**
- `frontend/e2e/tests/health-score-smoke.spec.ts` — 新建获客路径烟雾测试
- `frontend/e2e/tests/core-flow-smoke.spec.ts` — 新建核心流程烟雾测试

**Approach:**
1. 获客路径烟雾测试：访问健康分页面→输入品牌名→看到报告→点击注册
2. 核心流程烟雾测试：登录→创建品牌→触发诊断→查看诊断结果
3. 使用独立 setup（直接调用 API 创建测试数据），不依赖共享 fixture
4. 确保截图和视频录制配置正确（screenshot:on-failure, video:retain-on-failure）

**Patterns to follow:**
- `frontend/e2e/tests/login.spec.ts` 现有 E2E 测试模式
- `frontend/e2e/pages/login.page.ts` Page Object 模式

**Test scenarios:**
- 获客路径：未登录→访问 /health-score→输入品牌名→30 秒内看到报告→点击注册→注册弹窗出现
- 核心流程：登录→创建品牌→品牌出现在 Dashboard→触发诊断→诊断结果非零
- 测试失败时自动截图保存

**Verification:** `cd frontend && npx playwright test health-score-smoke core-flow-smoke` 通过。

## Scope Boundaries

**Deferred for later:**

- 网站爬取通道（诊断数据采集 V2）
- 全面 E2E 测试覆盖（原 QA 计划 U3/U4/U5 → 上线后逐步扩展）
- 性能基线测试（原 QA 计划 U7 → 上线后有真实负载后建立）
- CI 安全扫描（原 QA 计划 U8 → 上线后集成）
- Alembic 迁移验证（原 QA 计划 U8 → 上线后添加）
- 前端组件测试（原 QA 计划 U10 → 上线后扩展）
- 行业 GEO 基准数据积累
- API 市场开放和第三方集成
- 白标报告和专属客户成功经理
- 多语言和国际 AI 平台支持
- 知识库自动构建（从品牌官网自动提取 GEO 相关信息结构）
- 批量内容生成（一次生成多平台内容）
- 内容日历和排期执行系统

**Outside this product's identity:**

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

**Deferred to follow-up work:**

- E2E 测试迁移到共享 fixture（U9 完成后，将独立 setup 替换为 U8 的共享 fixture）
- 性能基线设定阈值和告警（上线后根据数据设定合理阈值）
- 跨浏览器 E2E 扩展（稳定 Chromium 后再扩展）
- 知乎/头条 API OAuth 授权完整流程
- 批量内容生成

## Open Questions

- 微信公众号 OAuth 授权流程的具体实现方案需在 U5 实施时确认
- 知乎和头条 API 的申请和审核周期可能影响 U5 的交付时间
- 诊断自动数据采集的品牌官网解析可能遇到反爬机制，需准备降级方案
- 真实 SMTP 配置需要用户提供邮件服务商账号信息
- 效果归因的具体技术实现方案（基于引用检测还是基于评分变化）
- 付费版定价是否需要调整（当前 ¥199/599/1999 是否匹配价值感知）

## Risks & Dependencies

| Risk | Impact | Mitigation |
|------|--------|------------|
| 诊断数据采集不准确 | 用户不信任健康分，获客失效 | 先用 AI 平台查询数据（已有适配器），品牌官网解析作为增强 |
| 微信/知乎/头条 API 审核不通过 | 分发集成延期 | 微信降级为半自动，知乎/头条备选手动发布 |
| 支付 SDK 集成复杂度超预期 | 付费闭环延期 | 先实现支付宝（文档更友好），微信支付后续迭代 |
| GEO 效果归因窗口内无可见提升 | 用户认为产品无效 | 提供效果保障机制，延长归因窗口或提供额外优化 |
| 免费诊断 API 调用成本过高 | 运营成本失控 | 24 小时缓存+频率限制+深度限制 |
| LLM API Key 不可用影响内容生成 | 核心付费功能不可用 | 支持多 LLM Provider 降级，至少保证一个可用 |

## Sources & Research

- Origin requirements: `docs/brainstorms/2026-05-31-geo-next-phase-core-flow-repair-requirements.md`
- Secondary origin: `docs/brainstorms/2026-05-31-geo-platform-monetization-closed-loop-requirements.md`
- QA plan (downscoped): `docs/plans/2026-05-31-002-test-quality-assurance-system-plan.md`
- Existing diagnosis system: `backend/app/services/diagnosis/geo_diagnosis.py`
- Diagnosis API root cause: `backend/app/api/diagnosis.py` line 75 (`GEODiagnosisInput()`)
- Existing content pipeline: `backend/app/services/content/content_pipeline.py`
- Existing distribution rules: `backend/app/services/distribution/platform_rules.py`
- Existing monitoring: `backend/app/services/monitoring/monitor_service.py`
- Existing subscription: `backend/app/services/subscription.py`
- Existing email: `backend/app/services/email_service.py`
- Existing E2E tests: `frontend/e2e/tests/`