20 KiB

Raw Blame History

title	type	status	date	origin
chore: GEO Platform Launch Sprint — Dual-Track to Billable Launch	chore	completed	2026-06-02	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

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天

20 KiB Raw Blame History Unescape Escape

GEO Platform Launch Sprint — Dual-Track to Billable Launch

Summary

Problem Frame

Requirements

Key Technical Decisions

High-Level Technical Design

Implementation Units

U1. Docker Compose Deployment Verification

U2. Production Environment Security Configuration

U3. Browser Authentication Flow Verification

U4. DateTime Timezone and Scoring Runtime Verification

U5. Test Infrastructure — Directory Unification and Shared Fixtures

U6. E2E Tests and CI Integration

U7. Platform Rules Center Test Completion

U8. Payment SDK Integration and Attribution Window

Scope Boundaries

Risks & Dependencies

Open Questions

Sources & Research

20 KiB

Raw Blame History