geo/docs/plans/2026-06-02-007-chore-geo-launch-sprint-plan.md

---
title: "chore: GEO Platform Launch Sprint — Dual-Track to Billable Launch"
type: chore
status: completed
date: 2026-06-02
origin: docs/brainstorms/2026-06-02-geo-launch-sprint-requirements.md
---

# GEO Platform Launch Sprint — Dual-Track to Billable Launch

## Summary

双轨并行推进 GEO 平台到可收费上线状态：轨道A解决部署验证、生产环境配置和安全加固让系统可运行；轨道B并行建设完整测试体系、平台规则中心测试补全和支付SDK集成让系统可收费且质量有保障。研究阶段发现 R2/R3/R6 在代码层面已修复，转为验证确认；支付SDK当前为骨架状态需真实API接入。

## Problem Frame

GEO 平台核心功能开发已完成（8个AI Agent、6阶段内容管线、5维品牌评分、前端可视化），但从未作为完整产品端到端运行。6个现有计划中标记完成的关键事项实际未验证：生产环境配置缺失、支付为mock模式、测试体系大部分未建立、规则中心30个测试用例全部未完成。系统处于"代码写完但不可运行、不可收费、不可信赖"的状态。

---

## Requirements

**轨道A — 上线阻塞项**

- R1. Docker Compose一键启动成功，前后端均可访问，CORS配置正确
- R2. Dockerfile HEALTHCHECK端点验证通过（代码已修复为`/health`，需确认运行时行为）
- R3. `.env.test` JWT_SECRET验证可用（代码已配置，需确认测试环境运行正常）
- R4. 前端浏览器认证流程完整可用（注册→登录→token刷新→401处理）
- R5. 生产环境安全配置完整：Redis密码认证、PostgreSQL强密码、`.env.production`文件创建、生产镜像切换为pgvector
- R6. DateTime timezone验证通过（代码已全部使用`DateTime(timezone=True)`，需确认asyncpg运行时无报错）
- R7. 诊断评分非零场景验证通过，品牌健康评分计算逻辑正确

**轨道B — 功能完善项**

- R8. 后端测试目录统一，散落的测试文件迁移到标准目录结构
- R9. 共享fixture系统扩展，测试数据工厂可复用
- R10. E2E测试覆盖诊断-策略流程和内容-监控流程
- R11. CI集成E2E测试，性能基线建立
- R12. CI安全扫描和迁移验证集成
- R13. 测试文档更新
- R14. 平台规则中心RuleValidator、SensitiveFilter、SEOOptimizer、HTMLGenerator、ContentPipeline测试用例补全至30个
- R15. 微信支付和支付宝真实SDK集成，未配置时降级mock模式
- R16. 归因系统窗口可配置（当前硬编码28天），2-4周窗口验证通过

---

## Key Technical Decisions

- **生产PostgreSQL镜像切换为pgvector**: `docker-compose.prod.yml`使用`postgres:15-alpine`缺少pgvector扩展，切换为`pgvector/pgvector:pg15`以支持向量搜索功能 (see origin)
- **支付SDK集成策略**: 代码层面完成真实API调用集成，`_is_configured()`检测未配置时自动降级为MockGateway，SDK申请在功能验证后进行 (see origin)
- **测试体系在时区迁移验证后搭建**: R6验证通过后再开始R8-R13，避免测试数据因迁移失效 (see origin)
- **双轨并行而非顺序推进**: 轨道A和轨道B同时推进，速度优先但需协调交叉依赖 (see origin)
- **已有测试文件保留而非重写**: `test_content_pipeline/`已有6个测试文件，在其基础上补全至30个用例

---

## High-Level Technical Design

```mermaid
flowchart TB
    subgraph TrackA["轨道A — 上线阻塞"]
        U1[U1. Docker Compose部署验证] --> U2[U2. 生产环境安全配置]
        U2 --> U3[U3. 浏览器认证流验证]
        U3 --> U4[U4. DateTime/评分运行时验证]
    end

    subgraph TrackB["轨道B — 功能完善"]
        U5[U5. 测试体系基础设施] --> U6[U6. E2E测试+CI集成]
        U5 --> U7[U7. 规则中心测试补全]
        U6 --> U8[U8. 支付SDK集成+归因窗口]
    end

    U4 -.->|验证通过| U5
    U2 -.->|环境就绪| U6
```

---

## Implementation Units

### U1. Docker Compose Deployment Verification

**Goal:** 验证 Docker Compose 一键启动成功，前后端可访问，CORS配置正确

**Requirements:** R1, R2, R3

**Dependencies:** none

**Files:**
- `docker-compose.yml`
- `docker-compose.prod.yml`
- `backend/Dockerfile`
- `frontend/Dockerfile`
- `.env.example`
- `backend/.env.test`
- `backend/tests/test_infrastructure/test_docker_health.py`

**Approach:** 从 `.env.example` 创建 `.env` 文件，执行 `docker compose up --build`，验证所有服务启动成功。确认后端 `/health` 端点返回200，前端3000端口可访问，CORS头正确返回。验证 `.env.test` 中 JWT_SECRET 在测试环境中生效。生产docker-compose需切换PostgreSQL镜像为pgvector。

**Patterns to follow:** 现有 `docker-compose.yml` 开发环境配置模式

**Test scenarios:**
- Docker Compose up: 所有4个服务(backend, frontend, db, redis)启动成功，无错误日志
- Backend health: `GET /health` 返回200和健康状态JSON
- Frontend access: `GET http://localhost:3000` 返回200
- CORS headers: 开发模式允许所有来源，生产模式仅允许配置的来源
- JWT_SECRET in test: pytest运行时使用`.env.test`中的JWT_SECRET，认证fixture正常工作

**Verification:** `docker compose up --build` 成功，`curl http://localhost:8000/health` 返回200，`curl http://localhost:3000` 返回HTML

---

### U2. Production Environment Security Configuration

**Goal:** 创建生产环境安全配置，包括Redis密码、PostgreSQL强密码、`.env.production`文件、pgvector镜像切换

**Requirements:** R5

**Dependencies:** U1

**Files:**
- `docker-compose.prod.yml`
- `.env.production.example`
- `.env.production` (新建)
- `backend/app/config.py`
- `backend/alembic/env.py`

**Approach:** 1) 将 `docker-compose.prod.yml` 中 PostgreSQL 镜像从 `postgres:15-alpine` 切换为 `pgvector/pgvector:pg15`；2) 从 `.env.production.example` 创建 `.env.production`，替换所有 `CHANGE_ME` 占位符为强密码/密钥；3) 确认 Redis 密码配置在生产 docker-compose 中生效；4) 验证 Alembic 迁移在生产数据库上可执行。

**Patterns to follow:** 现有 `docker-compose.prod.yml` 双网络架构，`.env.production.example` 变量结构

**Test scenarios:**
- Production compose up: `docker compose -f docker-compose.prod.yml up` 启动成功
- Redis auth: 无密码连接被拒绝，使用配置密码连接成功
- PostgreSQL auth: 默认密码被拒绝，使用强密码连接成功
- pgvector extension: `CREATE EXTENSION IF NOT EXISTS vector` 在生产数据库中执行成功
- Alembic migration: `alembic upgrade head` 在生产数据库上执行成功
- Network isolation: 外部无法直接访问PostgreSQL和Redis端口

**Verification:** 生产docker-compose启动成功，Redis/PostgreSQL密码认证生效，pgvector扩展可用，Alembic迁移成功

---

### U3. Browser Authentication Flow Verification

**Goal:** 验证前端浏览器认证流程完整可用，包括注册、登录、token刷新、401处理

**Requirements:** R4

**Dependencies:** U1

**Files:**
- `frontend/lib/api/client.ts`
- `frontend/lib/auth.ts`
- `frontend/app/(auth)/login/page.tsx`
- `frontend/app/(auth)/register/page.tsx`
- `frontend/app/api/auth/[...nextauth]/route.ts`
- `frontend/e2e/tests/login.spec.ts`
- `frontend/e2e/tests/login-redirect.spec.ts`
- `frontend/e2e/tests/login-access.spec.ts`

**Approach:** 使用现有Playwright E2E测试验证完整认证流程。确认NextAuth JWT策略工作正常，refreshAccessToken轮换机制正确，fetchWithAuth的401自动重试逻辑有效。若现有E2E测试覆盖不足则补充。

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

**Test scenarios:**
- Registration: 新用户注册成功，跳转到onboarding页面
- Login: 已注册用户登录成功，跳转到dashboard
- Token refresh: access token过期后自动刷新，用户无感知
- 401 handling: API返回401时自动重试一次（刷新token后），仍失败则跳转登录页
- Session persistence: 刷新页面后保持登录状态

**Verification:** Playwright E2E认证测试全部通过，手动浏览器验证注册→登录→使用→刷新→登出流程

---

### U4. DateTime Timezone and Scoring Runtime Verification

**Goal:** 验证DateTime timezone配置在asyncpg运行时无报错，诊断评分非零场景正确

**Requirements:** R6, R7

**Dependencies:** U2

**Files:**
- `backend/app/models/` (所有含DateTime列的模型)
- `backend/alembic/versions/a79329c23b20_initial_complete_schema.py`
- `backend/app/services/scoring/scoring_service.py`
- `backend/app/services/attribution/attribution_engine.py`
- `backend/tests/test_models/`
- `backend/tests/test_services/test_scoring.py`

**Approach:** 1) 连接生产PostgreSQL（asyncpg驱动），执行涉及DateTime列的CRUD操作，确认无timezone相关运行时错误；2) 创建品牌评分记录，验证5维度评分计算逻辑产生非零分数；3) 验证归因窗口计算正确。

**Patterns to follow:** 现有 `tests/test_models/` 和 `tests/test_services/` 测试模式

**Test scenarios:**
- DateTime CRUD: 创建/读取/更新含DateTime列的记录，asyncpg不报timezone错误
- DateTime round-trip: 写入带时区的datetime，读取后时区信息保留
- Scoring non-zero: 对有引用数据的品牌执行评分，5个维度均产生非零分数
- Health score calculation: 品牌健康评分 = 加权总分，等级划分正确(excellent/good/pass/danger)
- Attribution window: 归因窗口从start_at到window_end_at计算正确，28天后状态变为completed

**Verification:** 所有DateTime操作无asyncpg错误，评分计算产生合理非零分数，归因窗口计算正确

---

### U5. Test Infrastructure — Directory Unification and Shared Fixtures

**Goal:** 统一后端测试目录结构，扩展共享fixture系统

**Requirements:** R8, R9

**Dependencies:** U4

**Files:**
- `backend/tests/conftest.py`
- `backend/tests/fixtures/` (扩展)
- `backend/tests/test_api/`
- `backend/tests/test_services/`
- `backend/tests/test_models/`
- `backend/tests/test_content_pipeline/`
- `backend/tests/test_agent_framework/`
- `backend/tests/test_integration/`
- `backend/tests/test_middleware/`
- `backend/tests/test_infrastructure/`
- `backend/tests/test_repositories/`
- `backend/pyproject.toml`

**Approach:** 1) 将根目录散落的测试文件（test_config.py, test_performance.py, test_security.py, test_scheduler.py等）迁移到对应的`tests/`子目录；2) 扩展`tests/fixtures/`添加品牌、用户、内容的工厂fixture；3) 更新`conftest.py`统一fixture注册；4) 确保迁移后所有测试仍通过。

**Execution note:** 迁移前先运行全部测试记录基线，迁移后验证所有测试仍通过

**Patterns to follow:** 现有 `tests/conftest.py` 的 SQLite内存数据库 + 依赖注入覆盖模式，`tests/fixtures/` 的工厂fixture模式

**Test scenarios:**
- Directory structure: 所有测试文件位于`tests/`子目录下，根目录无散落测试文件
- Fixture availability: 新工厂fixture在所有测试文件中可用
- Test pass rate: 迁移后测试通过率与迁移前一致
- Import paths: 迁移后的测试文件import路径正确

**Verification:** `pytest` 全部通过，无根目录散落测试文件，新fixture可被任意测试文件使用

---

### U6. E2E Tests and CI Integration

**Goal:** 补充诊断-策略和内容-监控E2E测试，集成到CI，建立性能基线，添加安全扫描

**Requirements:** R10, R11, R12

**Dependencies:** U5

**Files:**
- `frontend/e2e/tests/diagnosis-strategy.spec.ts` (新建)
- `frontend/e2e/tests/content-monitoring.spec.ts` (新建)
- `frontend/e2e/pages/` (新增Page Objects)
- `.github/workflows/ci.yml`
- `.github/workflows/pr-check.yml`
- `backend/tests/test_performance.py`
- `backend/tests/test_security.py`

**Approach:** 1) 新增两个Playwright E2E spec覆盖诊断→策略推荐和内容生成→监控流程；2) 在CI workflow中添加E2E测试步骤（启动服务→运行Playwright→收集结果）；3) 建立性能基线（API响应时间p95）；4) 添加CI安全扫描步骤（bandit for Python, npm audit for frontend）。

**Patterns to follow:** 现有 `e2e/tests/core-flow-smoke.spec.ts` E2E测试模式，`.github/workflows/ci.yml` CI配置模式

**Test scenarios:**
- Diagnosis-strategy E2E: 用户提交品牌→系统执行诊断→生成策略推荐→用户可查看
- Content-monitoring E2E: 用户生成内容→内容发布→监控任务创建→监控数据展示
- CI E2E step: PR提交时自动运行E2E测试，失败则阻止合并
- Performance baseline: API端点p95响应时间记录，回归时CI告警
- Security scan: bandit扫描后端代码，npm audit扫描前端依赖，高危漏洞阻止合并

**Verification:** CI pipeline中E2E测试步骤运行成功，性能基线文件生成，安全扫描步骤存在且可执行

---

### U7. Platform Rules Center Test Completion

**Goal:** 补全平台规则中心测试用例至30个，覆盖RuleValidator、SensitiveFilter、SEOOptimizer、HTMLGenerator、ContentPipeline

**Requirements:** R14

**Dependencies:** U5

**Files:**
- `backend/tests/test_content_pipeline/test_rule_validator.py`
- `backend/tests/test_content_pipeline/test_sensitive_filter.py`
- `backend/tests/test_content_pipeline/test_seo_optimizer.py`
- `backend/tests/test_content_pipeline/test_html_generator.py`
- `backend/tests/test_content_pipeline/test_content_pipeline.py`
- `backend/tests/test_content_pipeline/test_content_generation.py`
- `.trae/specs/platform-rules-enforcement/tasks.md`
- `.trae/specs/platform-rules-enforcement/spec.md`

**Approach:** 以 `.trae/specs/platform-rules-enforcement/tasks.md` 中的30个测试用例为蓝图，在现有6个测试文件基础上补全。每个组件的测试覆盖：平台特定规则校验、边界条件、错误处理、组件间集成。优先覆盖P0平台（知乎、微信、百家号）的规则。

**Execution note:** 参照tasks.md中的TDD RED阶段测试用例，逐个实现

**Patterns to follow:** 现有 `test_content_pipeline/` 测试模式，`platform_rules.py` 中的规则配置结构

**Test scenarios:**
- RuleValidator: 微信诱导分享检测、知乎营销检测、小红书引流检测、百家号标题党检测、抖音水印检测、AI模式检测
- SensitiveFilter: 4类基础词库过滤、自定义词库、平台容差级别、替换策略
- SEOOptimizer: 关键词密度计算、密度范围校验、位置建议、平台特定SEO规则
- HTMLGenerator: 禁用标签过滤、微信外部链接移除、多格式输出（HTML/Markdown/纯文本）
- ContentPipeline: 4阶段顺序执行、高严重级别阻断、每阶段耗时记录、错误传播
- Cross-platform: 10个平台的规则配置完整性校验

**Verification:** 30个测试用例全部通过，`pytest tests/test_content_pipeline/` 无失败

---

### U8. Payment SDK Integration and Attribution Window

**Goal:** 集成微信支付和支付宝真实SDK，支持未配置时降级mock；归因窗口可配置

**Requirements:** R15, R16

**Dependencies:** U5

**Files:**
- `backend/app/services/payment/wechat_pay.py`
- `backend/app/services/payment/alipay.py`
- `backend/app/services/payment/mock_gateway.py`
- `backend/app/services/payment/base.py`
- `backend/app/services/payment/__init__.py`
- `backend/app/api/payments.py`
- `backend/app/services/attribution/attribution_engine.py`
- `backend/app/models/attribution_record.py`
- `backend/app/config.py`
- `backend/tests/test_services/test_payment.py`
- `backend/tests/test_services/test_attribution.py`

**Approach:** 1) 微信支付：使用`wechatpayv3`官方SDK或`requests`直接调用V3 API，实现NATIVE扫码支付的create_order（实际发送HTTP请求到微信）、verify_callback（验签）、query_order（查询订单状态）、refund（退款）；2) 支付宝：使用`alipay-sdk-python`或`requests`直接调用API，实现WAP支付的完整流程；3) 保留`_is_configured()`降级机制，未配置时自动使用MockGateway；4) 归因窗口：将硬编码28天改为从配置或订阅计划读取，支持14天/28天可配置。

**Patterns to follow:** 现有 `PaymentGateway` ABC接口，`_is_configured()` 降级模式，`config.py` 配置字段模式

**Test scenarios:**
- WeChat create_order: 配置完整时发送真实API请求（mock HTTP for test），返回支付二维码URL
- WeChat verify_callback: 微信回调签名验证通过/失败
- WeChat query_order: 查询已支付订单返回成功状态
- WeChat refund: 企业用户发起退款成功
- Alipay create_order: 配置完整时生成WAP支付表单
- Alipay verify_callback: RSA2签名验证通过/失败
- Fallback: 未配置时自动降级为MockGateway，所有操作返回模拟成功
- Attribution window 14 days: 配置14天窗口，归因在14天后完成
- Attribution window 28 days: 默认28天窗口行为不变
- Attribution scoring: 窗口期内维度变化正确计算delta

**Verification:** 支付网关在配置完整时调用真实API（测试环境用mock HTTP），未配置时降级mock；归因窗口可配置且计算正确

---

## Scope Boundaries

**Deferred for later:**
- 真实SMTP邮件集成（当前使用控制台输出）
- 知识库/生命周期/发布等占位页面实现
- Landing page移动端测试和表单后端集成
- 知乎/头条OAuth第三方登录验证
- 前端Playwright E2E浏览器自动化测试扩展
- 限流中间件从内存迁移到Redis
- 微信/支付宝SDK商户资质申请

**Deferred to Follow-Up Work:**
- Docker Compose生产环境的完整部署验证（需真实服务器）
- 归因系统端到端验证（依赖支付闭环完成后）
- 前端`reports/page.tsx`和`lifecycle/new/page.tsx`绕过统一API客户端的修复

---

## Risks & Dependencies

- **支付SDK商户资质未就绪**: 微信/支付宝SDK申请需要商户资质审核，可能需要1-2周。缓解：代码层面完成集成，未配置时降级mock
- **生产pgvector镜像兼容性**: `pgvector/pgvector:pg15`与现有迁移脚本的兼容性需验证。缓解：U1中优先验证
- **E2E测试环境依赖**: Playwright E2E测试需要完整运行的服务栈。缓解：CI中使用docker-compose启动服务
- **测试迁移风险**: 散落测试文件迁移可能引入import路径问题。缓解：U5中先记录基线再迁移
- **归因窗口可配置化**: 修改硬编码28天可能影响现有归因记录。缓解：仅影响新创建的归因记录，已有记录不受影响

---

## Open Questions

**Deferred to Planning:**
- CI环境选择（GitHub Actions / 自建Runner）—— 当前已有`.github/workflows/`，默认使用GitHub Actions
- 68列时区迁移是否需要数据回填—— 研究发现代码已修复，仅需运行时验证
- 微信支付V2(MD5签名) vs V3(RSA签名)选择—— V3是微信推荐的新协议，优先使用V3

---

## Sources & Research

- `docs/plans/2026-06-01-004-chore-geo-launch-readiness-sprint-plan.md` — 上线就绪冲刺计划
- `docs/plans/2026-06-01-005-chore-geo-tech-debt-cleanup-plan.md` — 技术债清理计划
- `docs/plans/2026-05-31-002-test-quality-assurance-system-plan.md` — 测试质量保障体系
- `docs/plans/2026-05-31-003-feat-geo-monetization-closed-loop-plan.md` — 变现闭环计划
- `.trae/specs/platform-rules-enforcement/spec.md` — 规则中心规格
- `.trae/specs/platform-rules-enforcement/tasks.md` — 规则中心30个测试用例
- `docker-compose.prod.yml` — 生产PostgreSQL镜像需切换为pgvector
- `backend/app/services/payment/wechat_pay.py` — 微信支付当前未实际调用API
- `backend/app/services/payment/alipay.py` — 支付宝当前未实际调用API
- `backend/app/services/attribution/attribution_engine.py` — 归因窗口硬编码28天