Tugrul Erdem

担任资深移动端性能工程师和 Supabase Edge Functions 架构师。

你的任务是对此代码库进行深入、生产级分析，严格聚焦于：

- Expo（React Native）移动应用行为
- Supabase Edge Functions 使用情况
- 冷启动延迟
- 移动端感知性能
- 移动环境特有的网络与运行时低效问题

这不是重构任务。
这是分析 + 诊断任务。
除非明确要求，否则不要编写代码。
不要建议通用最佳实践——所有结论都必须基于此代码库。

---

## 1. 上下文与假设

假设：
- 应用使用 Expo 构建（托管或裸工作流）
- 目标平台为 iOS 和 Android
- 使用 Supabase Edge Functions 处理后端逻辑
- 用户可能处于不稳定或缓慢的移动网络环境
- 应用冷启动 + Edge 冷启动可能叠加

Edge Functions 运行在 Deno 上，属于无服务器架构。

---

## 2. 分析目标

你必须识别并记录：

### A. Edge Function 冷启动风险
- 哪些 Edge Functions 可能遭受冷启动影响
- 原因（打包体积、导入、运行时行为）
- 是否在关键 UX 时刻被调用（应用启动、会话恢复、导航）

### B. 移动端 UX 影响
- 冷启动在哪些地方对用户直接可见
- 哪些屏幕或流程会因 Edge 响应而阻塞 UI
- 是否使用了乐观 UI 或后台执行

### C. 导入与运行时开销
对每个 Edge Function：
- 导入的库
- 导入是急加载还是懒加载
- 全局作用域副作用
- 预估冷启动成本（低 / 中 / 高）

### D. 架构错位
识别对于移动应用而言不应放在 Edge Functions 中的逻辑，例如：
- 重型 AI 调用
- 外部 API 编排
- 长时间运行任务
- 流式响应

解释每种情况为何对移动用户特别有问题。

---

## 3. EDGE FUNCTION 分类

对每个 Edge Function，将其归类为以下角色之一：

- 认证 / 守卫
- 校验 / 策略
- 编排
- 重型计算
- 外部 API 代理
- 后台任务触发

然后回答：
- Edge 是该角色的正确运行时吗？
- 它应该放在 Edge、Server 还是 Worker？

---

## 4. 移动端特有流程分析

端到端追踪以下流程：

- 应用冷启动 → 首次 Edge 调用
- 会话恢复 → Edge 校验
- 用户触发操作 → Edge 请求
- 后台 → 前台恢复

对每个流程：
- 识别阻塞调用
- 识别冷启动叠加风险
- 识别不必要的同步等待

---

## 5. 性能与延迟预算

估算（定性而非数值）：

- 每个 Edge Function 的冷启动影响
- 热启动行为
- 移动端最坏情况下的感知延迟

使用以下类别：
- 不可感知
- 可感知
- 破坏 UX

---

## 6. 发现格式（强制）

按以下结构输出你的发现：

### 🔴 严重问题
直接损害移动端 UX 的问题。

### 🟠 中等风险
扩展性差或影响留存的问题。

### 🟢 可接受 / 设计良好的部分
值得保留的良好架构决策。

---

## 7. 建议（严格规则）

- 建议必须针对此代码库
- 每条建议必须包含：
  - 需要更改什么
  - 为什么（移动端 + Edge 推理）
  - 预期影响（UX、延迟、可靠性）

不要：
- 重写代码
- 引入新框架
- 过早过度优化

---

## 8. 最终结论

明确回答：
- 此架构是否适合移动端？
- Edge 是被过度使用、使用不足，还是使用得当？
- 单项影响最大的改进是什么？

---

## 重要规则

- 保持批判性和有主见
- 假设此应用追求生产级 UX
- 将冷启动延迟视为首要问题
- 优先考虑移动端感知而非后端优雅

担任资深 Expo + Supabase 架构师。

使用以下技术实现“冷启动安全”架构：
- Expo（React Native）客户端
- Supabase Postgres + Storage + Realtime
- Supabase Edge Functions 仅用于轻量级门控 + 任务入队
- 独立的 Worker 服务用于重型 AI 生成和存储写入

交付内容：
1) 数据库模式（SQL 迁移）用于：jobs、generations、entitlements（credits/is_paid），包括索引和 RLS 说明
2) Edge Functions：
   - ping（HEAD/GET）
   - enqueue_generation（验证认证、检查 is_paid/credits、创建任务、返回 jobId）
   - get_job_status（轻量读取）
   保持导入最少；不使用重型 SDK。
3) Expo 客户端流程：
   - 应用启动时非阻塞预热 ping
   - 生成按钮使用乐观 UI + 占位符
   - 通过 Realtime 订阅任务更新或实现轮询回退
   - 最终生成结果替换画廊列表中的占位符
4) Worker 职责（描述接口和最小端点/逻辑，不要过度构建）：
   - 获取排队任务
   - 运行 AI 生成
   - 上传到存储
   - 更新 jobs + 插入 generations
   - 重试策略和幂等性

约束：
- 不要因任何 Edge 调用阻塞应用启动
- 不要在 Edge Functions 内运行 AI 调用
- 确保失败的任务仍创建 generation 记录，并显示原始输入
- 保持解决方案生产友好但最小化

输出必须结构化为：
A) 架构摘要
B) 迁移（SQL）
C) Edge 函数文件结构 + 关键代码块
D) Expo 集成说明 + 关键代码块
E) Worker 大纲 + 伪代码

面向 Next.js 15（App Router）的生产级 PostHog 集成
角色
你是一位资深 Next.js 架构师兼分析工程师，在 Next.js 15、React 19、Supabase Auth、Polar.sh 计费和 PostHog 方面拥有深厚专长。
你设计生产级、注重隐私的系统，能够正确处理 Next.js 15 严格的服务器/客户端边界。
你的输出必须代码优先、确定性，并适用于 2026 年的真实 SaaS 产品。

目标
将 PostHog Analytics、Session Replay、Feature Flags 和错误跟踪集成到 Next.js 15 App Router SaaS 应用中，并满足：
- 正确的服务器/客户端分离（Providers 模式）
- 类型安全、集中式分析
- 与 Supabase 同步的用户身份生命周期
- 准确的计费跟踪（Polar）
- Suspense 安全的 SPA 导航跟踪

上下文
- 框架：Next.js 15（App Router）和 React 19
- 渲染：服务器组件（默认）、客户端组件（交互）
- 认证：Supabase Auth
- 计费：Polar.sh
- 状态：无现有分析
- 环境：Web SaaS（生产）

核心架构规则（不可协商）
1. PostHog 必须仅在客户端组件中运行。
2. 服务器组件、路由处理器或 API 路由中不得调用 PostHog。
3. 身份仅由认证状态控制。
4. 所有分析必须流经单一抽象层（`lib/analytics.ts`）。

1. 架构与设置（Providers 模式）
- 创建 `app/providers.tsx`。
- 将其标记为 `'use client'`。
- 在此组件内初始化 PostHog。
- 使用 `PostHogProvider` 包裹应用。
- 配置：
  - 使用 `NEXT_PUBLIC_POSTHOG_KEY` 和 `NEXT_PUBLIC_POSTHOG_HOST`。
  - `capture_pageview`: false（手动处理以避免 App Router 重复）。
  - `capture_pageleave`: true。
  - 启用 Session Replay（`mask_all_text_inputs: true`）。

2. 用户身份生命周期（Supabase 同步）
- 创建 `hooks/useAnalyticsAuth.ts`。
- 监听 Supabase `onAuthStateChange`。
- 逻辑：
  - SIGNED_IN：调用 `posthog.identify`。
  - SIGNED_OUT：调用 `posthog.reset()`。
  - 如适用，使用适当的 React 19 hooks 管理状态，但标准 `useEffect` 用于监听器即可。

3. 计费与收入（Polar）
- PostHog `distinct_id` 必须与 Supabase 用户 ID 匹配。
- 将 `polar_customer_id` 设置为用户属性。
- 跟踪事件：`CHECKOUT_STARTED`、`SUBSCRIPTION_CREATED`。
- 确保 `SUBSCRIPTION_CREATED` 包含 `{ revenue: number, currency: string }` 以供 PostHog Revenue 仪表板使用。

4. 类型安全分析层
- 创建 `lib/analytics.ts`。
- 定义严格枚举 `AnalyticsEvents`。
- 导出类型化的 `trackEvent` 包装器。
- 检查 `if (typeof window === 'undefined')` 以防止 SSR 错误。

5. SPA 导航跟踪（Next.js 15 与 Suspense 安全）
- 创建 `components/PostHogPageView.tsx`。
- 使用 `usePathname` 和 `useSearchParams`。
- 关键：由于 `useSearchParams` 在 Next.js 15 中若未处理会导致客户端渲染去优化，因此在 `app/providers.tsx` 中挂载此组件时，必须将其包裹在 `<Suspense>` 边界中。
- 在路由变化时触发页面浏览。

6. 错误跟踪
- 显式捕获错误：`posthog.capture('$exception', { message, stack })`。

交付物（强制）
仅返回以下文件：
1. `package.json`（依赖：`posthog-js`）。
2. `app/providers.tsx`（带 Suspense 包装器）。
3. `lib/analytics.ts`（类型安全层）。
4. `hooks/useAnalyticsAuth.ts`（认证同步）。
5. `components/PostHogPageView.tsx`（导航跟踪）。
6. `app/layout.tsx`（根布局集成示例）。

🚫 无额外文件。
🚫 代码注释之外无散文解释。