运营与排障 SOP

Admin 后台

常用 Admin API（Bearer Token = ADMIN_SECRET）

用户问题排查 Checklist

用户报"消息发不出去 / AI 回复有问题 / 付了钱没到账"等问题时，不要先猜代码。按这个顺序查：

1. 查 Fly.io 日志：flyctl logs --app vividreams --no-tail | grep -E "ERROR|failed|exception" 看具体异常
2. 查用户数据：turso db shell vividreams 直接查 users / transactions / conversations
3. 发测试消息：用 Bot API sendMessage 验证 Telegram 链路本身通不通
4. 区分错误类型：
   • "AI service error" → LLM 流式异常（openrouter.py），查 LLM stream failed 日志
   • "Request failed" / HTTP 状态码 → FastAPI 500，看 traceback
   • "Insufficient energy" → 业务限制（正常），查 energy 字段
   • 付款没到账 → 查 transactions 表 + telegram_payment_charge_id，没记录就是 webhook 没收到
5. 确认影响范围：让另一个用户也测试一下 —— 看似个案常常是全局问题

紧急回滚

# 看历史 release
fly releases list -a vividreams

# 回到上一版
fly releases rollback <version> -a vividreams

# 验证
curl https://vividreams.fly.dev/health

# git revert 上一次推送，再推
git revert <commit-sha>
git push origin main

# 取消 webhook，让 Telegram 不再推 update
curl https://api.telegram.org/bot<BOT_TOKEN>/setWebhook -d url=

# 修复后重新设置
curl https://api.telegram.org/bot<BOT_TOKEN>/setWebhook \
     -d url=https://vividreams.fly.dev/webhook

新增角色 SOP（3 分钟扩容）

1. 读 Softieweb .env.local 确认 DATABASE_URL 没变
2. 用 Python psycopg2 查询，跳过 Vivi 已有角色：

   SELECT id, name, description, image, video, category, age,
          personality, prompt, first_message, sparks_cost, sort_order
   FROM characters
   WHERE is_active = true AND is_private = false AND category = 'FEMALE'
     AND name NOT IN (...)
   ORDER BY sort_order ASC NULLS LAST LIMIT N;

3. 转成 Vivi 格式（id 用首词小写 slug，重名加数字后缀），追加到 app/characters/data/characters.json
4. 检查脏数据：first_message 偶尔属于另一个角色（DB 历史问题），对不上就自己写问候语；prompt 中的 NSFW 描述（如 "Sexual Features: ..."）必须删掉，保留性格部分
5. 媒体不需要下载 / base64 —— resolveImg() 在 http:// 前缀时直接返回 CDN URL
6. Bump webapp/index.html 的 ?v=N（破坏 CDN 缓存）
7. git add + git commit -m "feat(characters): add ..." + git push origin main
8. 等 GitHub Actions 跑完，curl https://vivi-app-e7m.pages.dev/index.html | grep "?v=N" 验证

批量生图（角色图库预生成）

这部分走 n8n + ComfyUI + RunPod，不在 Vivi 仓库：

• Vivi 仓库的 scripts/submit_new_prompts.py 组装 payload → POST 到 Workflow 仓库的 n8n webhook
• n8n 工作流编排（gen-sfw / gen-nsfw / gen-scene）+ ComfyUI 参数 + RunPod Serverless 部署都在 Workflow 仓库
• Vivi 这边只关心：scenes 字段透传给 n8n、生成完后把图地址回填到角色 story 配置

Adsgram 充值 SOP

Adsgram 是 Telegram Mini App 的官方广告投放渠道，按预算充值后投流。流程：

1. 打开 https://partner.adsgram.ai/balance（用户已登录）
2. 选 "Payment in fiat" 标签页
3. Country 保持 Thailand
4. Currency 选 CNY 或 USD（按预算折算）
5. 填金额 → 提交 → 跳 Changelly 支付页
6. 到输入卡号环节 交给用户接管（Mastercard 支付）

当前活跃 Campaign ID：62741（2026-04 最新投放，旧 ID 60508 已废弃）。日预算约 $10，定向中东 + 欧美。

Lark 推送规范

所有推送必须用交互式卡片（msg_type: "interactive"），结构：

{
  "msg_type": "interactive",
  "card": {
    "config": { "wide_screen_mode": true },
    "header": {
      "title": { "tag": "plain_text", "content": "标题（带 emoji 前缀）" },
      "template": "indigo"
    },
    "elements": [
      { "tag": "markdown", "content": "**第一部分标题**\n\n正文..." },
      { "tag": "hr" },
      { "tag": "markdown", "content": "**第二部分标题**\n\n正文..." },
      { "tag": "note", "elements": [{ "tag": "plain_text", "content": "脚注信息" }] }
    ]
  }
}

颜色约定（header.template）

• indigo — 技术 / 分享
• red — 告警 / 故障
• green — 成功 / 上线
• orange — 注意 / 待办
• blue — 信息 / 日报

规则

• 每个段用 { "tag": "hr" } 分隔，底部用 note 标注来源 + 日期
• 只 @ 野荞（open_id 239e82d1），不要 @all，不要 @具体业务方
• 需要表格 / 对比 / 架构图：必须用 column_set 多列布局，不要用 ASCII 图或 Markdown 表格（Lark 不渲染）
• 构造好完整内容后只发一次，不要反复调试推送

需求写作模板（PM/同事提需求时）

需求必须满足"工程师看完不需要追问就能动手"的标准。常见问题：只描述现状没说改成什么 / 给了选项没做决策 / 一条混了多个改动 / 缺关键参数 / 没验收标准。

## 需求标题（一句话）

现状：当前是怎样的（截图 / 录屏更好）
改为：要变成怎样（明确终态，不是"是否要改"）
参数：涉及的具体数值 / 选项
优先级：P0 必须 / P1 重要 / P2 可以后做

不符合模板的需求收到后，先指出缺失项，要求补全后再排期。不要凭猜测开发。

常用命令速查

凭据 / Secret 索取入口

所有 secret 不放在公开文档里。需要时找 owner 索取，或在内部记忆库（~/.claude/projects/-Users-gloom-Vivi/memory/）查：