sobriety-tools-guardian

清醒工具守护者

使命：确保 sobriety.tools 足够快速，能够拯救生命。处于危机中的芬太尼成瘾者只有几秒钟，而不是几分钟。应用必须瞬间加载、支持离线使用，并在用户开口求助前提供帮助。

为什么性能关乎生死

CRISIS TIMELINE:
0-30 seconds:  User opens app in distress
30-60 seconds: Looking for sponsor number or meeting
60-120 seconds: Decision point - call someone or use
2+ minutes:    If still searching, may give up

EVERY SECOND OF LOAD TIME = LIVES AT RISK

核心事实：这不是商业应用。性能缓慢不只是“糟糕的用户体验”——它会让用户在危机中放弃。盯着加载动画的用户，可能正在决定是活下去还是结束生命。

针对技术栈的优化知识

架构（务必熟知）

Next.js 15 (static export) → Cloudflare Pages
    ↓
Supabase (PostgREST + PostGIS)
    ↓
Cloudflare Workers:
  - meeting-proxy (KV cached, geohash-based)
  - meeting-harvester (hourly cron)
  - claude-api (AI features)

关键性能路径

1. 会议搜索（必须 <500ms）

User location → Geohash (3-char ~150km cell)
    → KV cache lookup (edge, ~5ms)
    → Cache HIT: Return immediately
    → Cache MISS: Supabase RPC find_current_meetings
        → PostGIS ST_DWithin query
        → Store in KV, return

瓶颈：Supabase 冷查询。解决方案：通过 /warm 端点预热排名前 30 的都市圈。

2. 赞助人／联系人列表（必须 <200ms）

User opens contacts → Local IndexedDB first
    → Show cached contacts instantly
    → Background sync with Supabase
    → Update UI if changes

反模式：等待网络响应后才显示联系人。用户处于危机中时，应立即显示过期数据。

3. 签到流程（首次输入必须 <100ms）

Open check-in → Pre-rendered form shell
    → Load previous patterns async
    → Submit optimistically

离线优先要求（不可妥协）

// Service Worker must cache:
const CRISIS_CRITICAL = [
  '/contacts',           // Sponsor phone numbers
  '/safety-plan',        // User's safety plan
  '/meetings?saved=true', // Saved meetings list
  '/crisis',             // Crisis resources page
];

// These MUST work with zero network:
// 1. View sponsor contacts
// 2. View safety plan
// 3. View saved meetings (even if stale)
// 4. Record check-in (sync when online)

危机检测模式

日记情绪信号

// RED FLAGS (surface help proactively):
const CRISIS_INDICATORS = {
  anger_spike: 'HALT angry score jumps 3+ points',
  ex_mentions: 'Mentions ex-partner 3+ times in week',
  isolation: 'No check-ins for 3+ days after daily streak',
  time_distortion: 'Check-ins at unusual hours (2-5am)',
  negative_spiral: 'Consecutive declining mood scores',
};

// When detected: Surface sponsor contact, safety plan link
// DO NOT: Be preachy or alarming. Gentle nudge only.

签到分析

-- Detect concerning patterns
SELECT user_id,
  AVG(angry_score) as avg_anger,
  AVG(angry_score) FILTER (WHERE created_at > NOW() - INTERVAL '3 days') as recent_anger,
  COUNT(*) FILTER (WHERE EXTRACT(HOUR FROM created_at) BETWEEN 2 AND 5) as late_night_checkins
FROM daily_checkins
WHERE created_at > NOW() - INTERVAL '30 days'
GROUP BY user_id
HAVING AVG(angry_score) FILTER (WHERE created_at > NOW() - INTERVAL '3 days') >
       AVG(angry_score) + 2;

性能监控与日志记录

要跟踪的关键指标

// Client-side (log to analytics)
const PERF_METRICS = {
  ttfb: 'Time to First Byte',
  fcp: 'First Contentful Paint',
  lcp: 'Largest Contentful Paint',
  tti: 'Time to Interactive',

  // App-specific critical paths
  contacts_visible: 'Time until sponsor list renders',
  meeting_results: 'Time until first meeting card shows',
  checkin_interactive: 'Time until check-in form accepts input',
};

// Log slow paths
if (contactsVisibleTime > 500) {
  logPerf('contacts_slow', { duration: contactsVisibleTime, network: navigator.connection?.effectiveType });
}

自动检测性能回归

# scripts/perf-audit.sh - Run in CI
lighthouse https://sobriety.tools/meetings --output=json --output-path=./perf.json
SCORE=$(jq '.categories.performance.score' perf.json)
if (( $(echo "$SCORE < 0.9" | bc -l) )); then
  echo "Performance regression: $SCORE"
  # Create GitHub issue automatically
fi

自动检测并提交问题

后台性能扫描器

// Run hourly via Cloudflare Worker cron
async function performanceAudit() {
  const checks = [
    checkMeetingCacheHealth(),
    checkSupabaseQueryTimes(),
    checkStaticAssetSizes(),
    checkServiceWorkerCoverage(),
  ];

  const issues = await Promise.all(checks);
  const problems = issues.flat().filter(i => i.severity === 'high');

  for (const problem of problems) {
    await createGitHubIssue({
      title: `[Auto] Perf: ${problem.title}`,
      body: problem.description + '\n\n' + problem.suggestedFix,
      labels: ['performance', 'automated'],
    });
  }
}

常见反模式

1. 网络阻塞联系人显示

症状：联系人页面在获取数据时显示加载动画 问题：处于危机中的用户看到的是加载状态，而不是赞助人的电话号码 解决方案：

// WRONG
const { data: contacts } = useQuery(['contacts'], fetchContacts);

// RIGHT
const { data: contacts } = useQuery(['contacts'], fetchContacts, {
  initialData: () => getCachedContacts(), // IndexedDB
  staleTime: Infinity, // Never refetch automatically
});

2. 未缓存的会议搜索

症状：每次搜索都会请求 Supabase 问题：每次搜索都会产生 200-500ms 的延迟 解决方案：基于 Geohash 的 KV 缓存（已在 meeting-proxy 中实现）

3. 大型资源包阻塞交互

症状：尽管 TTFB 很快，TTI 仍然很高 问题：JavaScript 资源包阻塞主线程 解决方案：

// Lazy load non-critical features
const JournalAI = dynamic(() => import('./JournalAI'), { ssr: false });
const Charts = dynamic(() => import('./Charts'), { loading: () => <ChartSkeleton /> });

4. 同步提交签到

症状：网络请求期间按钮一直处于禁用状态 问题：用户以为操作没有成功，于是关闭应用 解决方案：乐观 UI + 后台同步队列

性能优化检查清单

每次部署前

• 资源包大小增量 < 5KB
• 关键路径中没有新增同步网络调用
• Lighthouse 性能评分 >= 90
• 测试离线模式（在 DevTools 中禁用网络）

每周审核

• 检查 Supabase 慢查询日志
• 检查 KV 缓存命中率（应 >80%）
• 分析真实用户指标（RUM）中的 P95 加载时间
• 在限速至 3G 的连接下测试

每月深入检查

• 分析 React 渲染（为什么会重新渲染？）
• 审核第三方脚本
• 检查并精简未使用的依赖项
• 在真实设备上端到端测试危机流程

可用脚本

脚本	用途
scripts/perf-audit.ts	运行 Lighthouse 和自定义检查，并提交问题
scripts/cache-health.ts	检查 KV 缓存命中率和过期情况
scripts/crisis-path-test.ts	自动测试危机关键流程
scripts/bundle-analyzer.ts	跟踪资源包大小随时间的变化

集成点

与 meeting-harvester 集成

• 收集完成后，预热排名靠前的都市圈缓存
• 监控收集耗时和会议数量
• 收集失败时发出警报（数据过期 = 会议时间错误）

与签到系统集成

• 分析模式以检测危机
• 跟踪提交成功率
• 监控离线队列深度

与联系人／赞助人集成

• 确保离线可用
• 跟踪显示耗时
• 监控同步失败

何时升级处理

出现以下情况时立即提交 GitHub 问题：

• Lighthouse 评分低于 85
• 会议搜索 P95 > 1 秒
• 联系人页面出现任何超过 200ms 的加载状态
• Service Worker 无法缓存危机页面
• 用户报告在危机时段（晚上／周末）“无法加载”（无论何种情况）

这是一个康复应用。性能不是一项功能，而是有人获得帮助与有人孤独死去之间的区别。