SaaS Stripe 分析（生产就绪版）

🎯 何时使用此能力

主要触发场景：

• MRR/流失率追踪（“Stripe 指标”、“业务仪表盘”）
• 客户分析（“头部客户”、“LTV 排名”）
• 收入健康度评估（“预测”、“付款恢复”）
• 告警（“流失风险”、“高危客户”）

输入 Schema（JSON）：

{
  "days_back": 90,           // 7–365 天
  "segment_by": "geo",       // plan | geo | industry  
  "forecast_months": 6,      // 1–12 个月
  "customer_limit": 15       // 1–50
}

默认值：30 天、按 plan 划分、3 个月预测、Top 10 客户。

📤 输出格式（始终遵循）

SUCCESS:
{
  "status": "success",
  "data": {
    "mrr": {"current": 12450, "growth_pct": 11},
    "churn": {"revenue_pct": 3.2, "at_risk": 7},
    "segments": [{"name": "US", "arpu": 89}],
    "forecast": [13500, 14600, 15800],
    "insights": ["US ARPU 2x EU"],
    "action_items": [{"priority": "high", "impact": "revenue"}]
  },
  "metadata": {"execution_time_ms": 2100, "api_calls": 5}
}

ERROR: 
{
  "status": "error", 
  "error_type": "auth_error"|"rate_limit"|"network_error",
  "message": "面向用户的可操作修复建议"
}

🛠 配置与运行环境

必需配置

STRIPE_READ_KEY=sk_read_xxx...

精确的 Stripe 配置步骤：

1. Dashboard → Developers → API Keys → Restricted Key
2. 所需权限范围（Scopes）：read: Customer | read: Subscription | read: Invoice
3. 额外权限范围：read: Payment Intent（仅限只读，仅用于失败付款恢复）
4. ✅ 不启用任何写入/退款/扣款类权限范围

可选配置

STRIPE_CACHE_TTL=3600     # 秒（默认：1 小时）
STRIPE_TIMEOUT=8000       # 毫秒（默认：8 秒）

⚡ 性能与限制

• 执行耗时：平均 2.1 秒（并发发起 5 个调用）
• 分页处理：自动支持（适用于 1000+ 客户规模）
• 速率限制：已内置处理（收到 HTTP 429 后自动重试）
• 数据保留期：最长 365 天
• 输出体积：约 4KB（压缩后）

🔗 示例工作流

1. 日度仪表盘

用户：“Stripe 指标 + 预测”
→ 2 秒内返回完整 MRR / 流失率 / 客户数 / 收入预测

2. 流失调查

“流失风险 + 头部客户”
→ 高危客户列表 + LTV 排名 + 可挽回金额

3. 地域拓展分析

“按国家划分的收入”
→ 美国：66%｜欧盟：22%｜“是否需本地化定价？”

🧪 已验证测试用例

📊 指标说明

🔒 安全性（ClawHub 认证）

✅ 只读密钥（仅启用 read:customers / read:subscriptions / read:invoices / read:payment_intents）
✅ 不持久化存储任何数据  
✅ 不记录或输出任何密钥/敏感信息
✅ 分页机制防止拒绝服务攻击（DoS）
✅ 单次调用超时设为 8 秒
✅ 错误消息安全（不暴露密钥或内部细节）

📈 可组合性（Composability）

saas_stripe_analytics_final → churn_predictor → winback_email_generator
stripe_top_customers → personalized_upsell → send_custom_email
geo_revenue_breakdown → market_expansion_plan → generate_localized_landing

🚀 OpenClaw 集成

斜杠命令（Slash Commands）：

/stripe-metrics     # 默认 30 天仪表盘
/stripe-churn       # 聚焦流失率与恢复策略  
/stripe-forecast    # MRR 收入预测
/stripe-segments    # 按 plan / geo / industry 维度拆解

语音触发词（Voice Triggers）：

• “Hey，Stripe 数据？”
• “业务仪表盘”
• “本月收入情况”

📝 故障排查

🎯 创始人价值主张

每周节省 2 小时人工报表工作 → 专注增长核心事务

• 即时生成风投级业务仪表盘
• 主动推送流失预警
• 识别新市场拓展机会
• 量化定价实验 ROI
• 自动化收入预测

“Stripe 分析” → 您完整的 SaaS 指挥中心。

标签：saas,stripe,analytics,mrr,churn,lTV,customer,forecast | v1.0.3