110 lines
4.8 KiB
Markdown
110 lines
4.8 KiB
Markdown
---
|
||
date: "2026-06-01"
|
||
topic: geo-launch-readiness
|
||
---
|
||
|
||
## Summary
|
||
|
||
GEO 平台变现闭环代码已全部落地（Plan 003），但从未端到端运行过。本需求定义一个"部署+验证"冲刺：先将系统部署到类生产环境，再在部署环境中验证完整变现闭环（注册→诊断→健康分→付费墙→支付→解锁），直到新用户可完成全链路操作。
|
||
|
||
## Problem Frame
|
||
|
||
Plan 003 完成了 9 个实施单元的代码编写——诊断数据采集、免费健康分页面、Onboarding 重设计、支付集成、AI 内容生成、效果归因、邮件集成、契约测试、E2E 烟雾测试。但这些代码从未作为完整系统运行过。后端服务能否启动、前端能否构建、数据库迁移能否执行、前后端联调是否通畅——全部未知。在代码从未跑过的状态下，任何单点修复都是盲目的；只有让系统先跑起来，才能发现真正的阻塞问题。
|
||
|
||
## Key Decisions
|
||
|
||
**部署优先于功能验证。** 本地跑通不等于可上线。部署问题（数据库迁移、环境变量、CORS、静态资源）往往是上线前最大的意外。先解决部署，再在部署环境中验证流程，一步到位。
|
||
|
||
**支付用 mock 模式验证。** 真实微信/支付宝 SDK 接入涉及商户审核、证书配置，是独立的长期工作。本次验证用 mock 支付确认付费墙逻辑正确即可，真实支付接入作为后续计划。
|
||
|
||
**阻塞驱动，不追求完美。** 遇到问题修到能继续往下走即可，不做全面重构或优化。目标是跑通闭环，不是打磨每个细节。
|
||
|
||
## Requirements
|
||
|
||
**部署就绪**
|
||
|
||
R1. 后端服务可在 Docker Compose 环境中启动，所有 API 端点可访问
|
||
|
||
R2. 前端构建产物可被部署并提供页面访问
|
||
|
||
R3. 数据库迁移可从空库执行到最新版本，所有表和索引正确创建
|
||
|
||
R4. 环境变量配置完整，第三方服务密钥缺失时优雅降级为 mock 模式
|
||
|
||
**核心流程可跑通**
|
||
|
||
R5. 新用户可完成注册并登录，获得有效 JWT
|
||
|
||
R6. 登录用户可创建品牌，触发诊断，获得非零健康分
|
||
|
||
R7. 免费用户访问付费功能时触发付费墙，显示升级提示
|
||
|
||
R8. 用户可发起支付（mock 模式），支付完成后配额刷新、付费功能解锁
|
||
|
||
R9. 公开健康分页面无需注册即可访问，输入品牌名可生成报告
|
||
|
||
**端到端验证**
|
||
|
||
R10. 完整变现闭环可在部署环境中走通：注册→诊断→健康分→付费墙→支付→解锁
|
||
|
||
**代码质量（2026-06-01 复盘新增）**
|
||
|
||
R11. Dockerfile 健康检查端点与实际 API 端点一致（当前 `/api/health` 不存在，应为 `/health`）
|
||
|
||
R12. 测试环境配置完整，`.env.test` 包含必需的 JWT_SECRET
|
||
|
||
R13. 前端页面统一使用 API 客户端，认证 token 正确传递（reports、lifecycle/new 页面绕过了统一客户端）
|
||
|
||
## Key Flows
|
||
|
||
- F1. 完整变现闭环验证
|
||
- **Trigger:** 新用户访问平台
|
||
- **Steps:** 注册账号 → 登录 → 创建品牌 → 触发诊断 → 查看非零健康分 → 尝试付费功能 → 触发付费墙 → 发起 mock 支付 → 支付完成 → 付费功能解锁
|
||
- **Outcome:** 用户完成从获客到付费的完整链路
|
||
- **Covers:** R5, R6, R7, R8, R10
|
||
|
||
- F2. 公开健康分获客路径
|
||
- **Trigger:** 未注册用户访问公开健康分页面
|
||
- **Steps:** 输入品牌名 → 系统生成 GEO 健康分报告 → 显示关键指标和问题 → 引导注册查看完整报告
|
||
- **Outcome:** 用户被引导进入注册流程
|
||
- **Covers:** R9, R10
|
||
|
||
## Scope Boundaries
|
||
|
||
**In scope:**
|
||
- Docker Compose 部署配置
|
||
- 数据库迁移执行
|
||
- 核心流程端到端验证
|
||
- 阻塞问题修复
|
||
|
||
**Deferred for later:**
|
||
- 真实微信/支付宝 SDK 接入
|
||
- CI/CD 流水线
|
||
- 性能优化和压力测试
|
||
- 生产环境域名和 HTTPS
|
||
- 完整测试覆盖
|
||
|
||
**Outside this sprint:**
|
||
- UI 打磨和视觉优化
|
||
- 新功能开发
|
||
- 代码重构
|
||
|
||
## Dependencies / Assumptions
|
||
|
||
- PostgreSQL 15 + pgvector 扩展可用（Docker 容器已配置）
|
||
- Redis 7 可用（会话和缓存）
|
||
- 第三方 API 密钥（DeepSeek、OpenAI 等）可能未配置，系统需支持 mock 降级
|
||
- LLM API 调用成本可控（诊断和内容生成会消耗 token）
|
||
|
||
## Outstanding Questions
|
||
|
||
**Resolved:**
|
||
- Docker Compose 配置已完整，包含 db (PostgreSQL 15) + redis (Redis 7) + backend (FastAPI) + frontend (Next.js) 四个服务，开发和生产两套配置均就绪
|
||
- 数据库迁移策略：使用 `create_all` + `stamp head`（KTD2）
|
||
- 前端部署方式：独立容器，开发模式用 `npm run dev`，生产模式用 standalone `node server.js`
|
||
- pgvector 扩展安装：通过 init-db.sh 从源码编译安装（KTD3）
|
||
- 验证方式：本地裸跑优先，Docker 部署后续（KTD6）
|
||
|
||
**Open:**
|
||
- 前端 reports 和 lifecycle/new 页面绕过统一 API 客户端，是否在本次修复？（当前标记为 deferred）
|