GrowthLoop 是一个面向产品与增长团队的增长活动工作台：创建活动、生成可归因链接与二维码、追踪访问和转化、运营邀请裂变，并用 OpenAI-compatible 模型辅助产出营销素材。仓库默认可以零配置体验 Demo Mode，并提供接入 Supabase 所需的数据库与事件采集基础设施。
当前状态：完整可交互的 Demo 产品。管理台、公开落地页、报名成功页、邀请排行榜、短链跳转、归因看板、AI 批量素材与复盘回退、公开事件 Route 均可运行；生产环境仍需接入管理台 Supabase adapter 与用户鉴权。
- 活动管理：活动状态、时间窗口、目标地址与奖励配置
- 链接归因：短码、UTM 参数、点击量、二维码与分享入口
- 漏斗分析：访问、点击、注册、转化趋势和渠道拆分
- 邀请裂变：参与者、邀请码、邀请关系、排行榜与一次性奖励
- 素材工作台：服务端 AI 批量生成文案、收藏、导出并创建追踪链接
- AI 增长复盘：基于当前归因周期和渠道指标生成结论与下一步实验
- Demo Mode：无需数据库或 AI Key 即可浏览与操作示例数据
- Supabase 基础设施：PostgreSQL migration、RLS、受控埋点 RPC、可重复 seed
Browser / landing page
├── Next.js 16 App Router UI
├── DemoStore（本地、确定性演示数据）
└── Supabase client（生产模式）
├── PostgREST + Row Level Security
├── track_event RPC（匿名、受控埋点）
└── PostgreSQL（归因 / 转化 / 邀请奖励）
Next.js server route
└── OpenAI-compatible /chat/completions（API Key 仅服务端）
src/app：页面、布局、Route Handlerssrc/components：工作台与复用 UIsrc/lib：领域规则、Demo store、校验和 AI 服务端适配supabase/migrations：数据库 schema、索引、触发器、函数、RLSsupabase/seed.sql：确定性演示数据（240 条事件）docs/DATA_MODEL.md：数据关系、安全边界与归因规则
| 表 | 用途 | 关键约束 |
|---|---|---|
campaigns |
活动配置与所有权 | 唯一 slug、状态/时间窗口校验 |
tracking_links |
分享链接与 UTM | 全局唯一 code、同活动参与者 FK |
visitors |
活动内匿名访客 | (campaign_id, anonymous_id) 唯一 |
events |
行为事件流 | 可选 idempotency key、按活动/时间索引 |
conversions |
注册/购买等结果 | 外部 ID 幂等、固定 first/last touch |
participants |
邀请活动参与者 | 每活动访客/邮箱/邀请码唯一 |
referrals |
邀请人与被邀请人关系 | 防自邀、每访客只归属一次、奖励一次 |
creative_assets |
生成或上传的素材 | 类型/状态校验、URL/路径/内容至少一项 |
完整关系与 RLS 说明见 docs/DATA_MODEL.md。
要求 Node.js 20+、pnpm 9+。如需本地数据库，还需要 Docker 与 Supabase CLI。
pnpm install
cp .env.example .env.local
pnpm dev打开 http://localhost:3000。首次体验建议保留 Demo Mode；本地 Supabase 启动后再替换 .env.local 的 URL 和 key。
| 变量 | 暴露范围 | 必需 | 说明 |
|---|---|---|---|
NEXT_PUBLIC_SUPABASE_URL |
浏览器 | 生产数据模式 | Supabase Project URL；未配置时 UI 使用 Demo 数据 |
NEXT_PUBLIC_SUPABASE_ANON_KEY |
浏览器 | 生产数据模式 | 可公开 anon/publishable key，权限由 RLS 控制 |
SUPABASE_SERVICE_ROLE_KEY |
服务端 | 管理写入/奖励任务 | 绕过 RLS，绝不能暴露给浏览器 |
NEXT_PUBLIC_APP_URL |
浏览器/元数据 | 推荐 | 应用规范地址，默认 http://localhost:3000 |
NEXT_PUBLIC_SITE_URL |
浏览器 | 可选 | 兼容部署/分享链接的站点地址；建议与 APP URL 相同 |
NEXT_PUBLIC_DEMO_MODE |
浏览器 | 可选 | true 强制演示模式；当前 UI 也会在缺少 Supabase URL 时自动演示 |
ADMIN_ACCESS_KEY |
服务端 | 生产 adapter 可选 | 轻量管理入口密钥；Demo Mode 不需要，正式产品建议替换为完整鉴权 |
OPENAI_API_KEY |
服务端 | AI 生成时 | OpenAI 或兼容服务的 API key |
OPENAI_BASE_URL |
服务端 | 可选 | 默认 https://api.openai.com/v1 |
OPENAI_MODEL |
服务端 | 可选 | /chat/completions 可用的模型名 |
不要将 service-role 或 AI key 添加 NEXT_PUBLIC_ 前缀。修改公开环境变量后需重新构建。
# 安装 CLI 后启动本地服务，应用 migration 并执行 seed
supabase start
supabase db reset
# 获取本地 URL / anon key / service-role key
supabase statussupabase db reset 会重建本地数据库并执行 migration 与 seed。seed 与浏览器 Demo 的“AI Coding 线下分享会”示例保持一致，可重复运行，包含 1 个活动、30 个访客、20 个参与者、5 条链接、240 条事件、14 次转化、15 条邀请和 8 份素材。
连接远端项目：
supabase login
supabase link --project-ref <project-ref>
supabase db push不要对生产库运行 db reset 或 demo seed。先创建 Supabase Auth 用户，再将真实活动的 owner_id 指向该用户。
Demo Mode 使用 src/lib/seed.ts、领域 store 和浏览器 localStorage，不依赖网络，适合产品评审与界面开发。设置 NEXT_PUBLIC_DEMO_MODE=true，或不设置 NEXT_PUBLIC_SUPABASE_URL 即可启用。数据会在同一浏览器中保留，也可以在设置页一键重置；它不代表服务端持久化、并发、鉴权或生产级性能。
Supabase 的 seed.sql 是另一套数据库演示数据，用于验证 SQL、看板查询和 RLS，不等同于浏览器内存 Demo。
服务端适配器调用标准 POST {OPENAI_BASE_URL}/chat/completions，因此可以连接 OpenAI 或支持该协议的网关/自托管服务。配置服务端 key、base URL 和模型；不要从客户端直接请求供应商。
OPENAI_API_KEY=...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-5-mini兼容服务需要支持 JSON 响应格式。生产环境应设置超时、速率限制、输入长度限制、内容安全策略与成本告警；AI 不可用时保留人工编辑/确定性模板回退。
匿名客户端不直接写表，而调用 track_event RPC：
await supabase.rpc("track_event", {
p_campaign_slug: "ai-coding-meetup",
p_anonymous_id: anonymousId,
p_event_name: "link_click",
p_properties: { placement: "hero" },
p_tracking_code: "share-demo-1",
p_session_id: sessionId,
p_page_url: location.href,
p_referrer_url: document.referrer || null,
p_idempotency_key: crypto.randomUUID(),
});anonymous_id应保存在第一方 cookie/localStorage；不要使用指纹技术绕过用户同意。- 每个业务事件使用稳定且唯一的
idempotency_key，重试不会重复入库。 visitors.first_touch保留occurred_at最早的触点（支持晚到事件），更新的事件才推进last_touch。- 转化发生时把当时的 first/last tracking link 固化到
conversions，避免后续访问改写历史归因。 - 入库前清理 URL 查询参数和 properties 中的密码、token、邮箱等敏感信息。
pnpm lint
pnpm exec tsc --noEmit
pnpm exec vitest run
pnpm build
# 安装 Docker + Supabase CLI 后验证完整数据库重建
supabase db reset数据库验收重点：匿名直写被拒绝、跨 owner 数据不可见、重复事件只生成一行、自邀/重复邀请失败、同一邀请不能二次奖励，以及 first touch 不被晚到事件覆盖。
- 在 Supabase 创建生产项目并执行
supabase db push。 - 把仓库导入 Vercel，使用 pnpm 与默认 Next.js 构建命令。
- 按上表配置 Preview/Production 环境变量，生产设
NEXT_PUBLIC_DEMO_MODE=false。 - 在 Supabase Auth 更新 Site URL 与 Redirect URLs；在 Vercel 配置域名。
- 先验证 Preview，再提升同一 commit 到 Production。
上线前逐项完成 DEPLOYMENT_CHECKLIST.md。
以下截图由项目本地 Demo Mode 的真实页面生成，便于在导入 Vercel 或接入 Supabase 前快速核对产品形态。
- 管理台当前使用 Demo adapter；数据库 schema、RLS 与公开事件 Route/RPC 已就绪，但管理数据持久化和用户鉴权仍需接线。
- 浏览器 Demo 数据仅保存在当前浏览器，无法跨设备同步，也不适合多用户并发。
- 公共 RPC 不自带边缘限流、验证码或机器人检测；上线必须在入口补充防滥用措施。
- 报表以应用查询为主，超大事件量需要聚合表、物化视图、分区和保留策略。
- 素材表只保存 URL/路径/文本与元数据；文件上传、转码、内容审核和对象存储策略未包含。
- Last-touch 采用最近接收的有效事件语义；跨设备身份合并与隐私同意管理尚未实现。
- 完成 Supabase repository adapter、Auth 与端到端 Route Handler
- 增加服务端事件签名、限流、bot/fraud scoring 和 webhook 重放队列
- 增加实时漏斗、队列化聚合、cohort/LTV 与多触点归因模型
- 增加奖励审批、预算上限、退款冲正和审计日志
- 接入 Supabase Storage、素材版本、内容审核与多模型路由
- 增加 Playwright E2E、SQL/RLS 集成测试、可访问性与可观测性基线
尚未指定许可证；对外分发前请补充 LICENSE。