205 lines
10 KiB
Markdown
205 lines
10 KiB
Markdown
---
|
||
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 个文件)
|