登入與金流:收得到錢才是產品

步驟一:Supabase Auth 設定(email + Google OAuth)

先到 supabase.com 建一個新專案。建好後進 Dashboard。

Email 登入:左側選「Authentication → Providers → Email」,確認已啟用。「Confirm email」建議開啟——使用者要點信才能登入,避免亂填 email 造成後續金流問題。

Google OAuth:先到 Google Cloud Console 建一個 OAuth 2.0 用戶端 ID(類型選「Web 應用程式」),在「已授權的重新導向 URI」填入:

https://<你的-supabase-project-id>.supabase.co/auth/v1/callback

拿到 Client ID 和 Client Secret 後,回 Supabase Dashboard → Authentication → Providers → Google,貼上去啟用。

前端呼叫 Google 登入只要兩行(以 @supabase/ssr 為例):

// app/login/actions.ts
import { createClient } from '@/utils/supabase/server'
import { redirect } from 'next/navigation'

export async function signInWithGoogle() {
  const supabase = await createClient()
  const { data, error } = await supabase.auth.signInWithOAuth({
    provider: 'google',
    options: {
      redirectTo: `${process.env.NEXT_PUBLIC_SITE_URL}/auth/callback`,
    },
  })
  if (data.url) redirect(data.url)
}

Next.js App Router 搭配 Supabase 必須用 PKCE 流程(不是 implicit flow),原因是 SSR 環境不能讓 token 出現在 URL 裡——@supabase/ssr 套件已經幫你處理好了,用它就對了。另外需要建 /auth/callback 這個 route 來交換 code:

// app/auth/callback/route.ts
import { createClient } from '@/utils/supabase/server'
import { NextResponse } from 'next/server'

export async function GET(request: Request) {
  const { searchParams, origin } = new URL(request.url)
  const code = searchParams.get('code')
  if (code) {
    const supabase = await createClient()
    await supabase.auth.exchangeCodeForSession(code)
  }
  return NextResponse.redirect(`${origin}/dashboard`)
}

步驟二:訂閱資料庫 schema

在 Supabase SQL Editor 執行以下建表語句。這兩張表是整個金流系統的骨幹:

-- 使用者訂閱資料表
create table public.subscriptions (
  id uuid primary key default gen_random_uuid(),
  user_id uuid references auth.users(id) on delete cascade not null,
  stripe_customer_id text unique,
  stripe_subscription_id text unique,
  plan text not null default 'free',       -- 'free' | 'pro' | 'team'
  status text not null default 'active',   -- 'active' | 'past_due' | 'canceled'
  current_period_end timestamptz,          -- 這個訂閱週期什麼時候到期
  ai_calls_used integer not null default 0,
  ai_calls_limit integer not null default 50, -- free 方案預設 50 次/月
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- 每次 AI 呼叫的用量紀錄(選做,方便日後分析)
create table public.usage_logs (
  id uuid primary key default gen_random_uuid(),
  user_id uuid references auth.users(id) on delete cascade not null,
  feature text not null,           -- 哪個功能
  tokens_used integer default 0,
  created_at timestamptz default now()
);

-- RLS:使用者只能看到自己的資料
alter table public.subscriptions enable row level security;
create policy "Users can view own subscription"
  on public.subscriptions for select
  using (auth.uid() = user_id);

注意幾件事:

• stripe_customer_id 和 stripe_subscription_id 是和 Stripe 的接點,webhook 收到事件時靠這兩個欄位找到對應的使用者紀錄
• current_period_end 讓你不需要每次都打 Stripe API,本地就能判斷訂閱是否有效
• Row Level Security 必須開,不然使用者可以改別人的訂閱狀態

步驟三:Stripe 建立 Product 與 Price

登入 Stripe Dashboard → Products → Add product。

建一個「Pro Plan」產品,定價模型選「Recurring」(訂閱),設定月費金額(例如 $9.99 美元或 299 台幣),Billing period 選 Monthly。記下 Price ID(格式像 price_1AbcDef...),後面程式碼會用到。

如果你有年費方案,同一個 Product 底下再加一個 Price,Billing period 改 Yearly 並給個折扣。一個 Product 多個 Price 是 Stripe 的標準做法。

裝好 Stripe SDK:

npm install stripe @stripe/stripe-js

設定環境變數:

# .env.local
STRIPE_SECRET_KEY=sk_test_...        # 從 Stripe Dashboard → Developers → API Keys 拿
STRIPE_WEBHOOK_SECRET=whsec_...      # 稍後設定 webhook 後才有
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

步驟四:建立 Checkout Session API

使用者點「升級方案」按鈕時,前端打這支 API,後端產生 Stripe Checkout Session 並回傳結帳網址:

// app/api/billing/checkout/route.ts
import Stripe from 'stripe'
import { createClient } from '@/utils/supabase/server'
import { NextResponse } from 'next/server'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)

export async function POST(request: Request) {
  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()

  if (!user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const { priceId } = await request.json()

  // 取出或建立 Stripe Customer
  const { data: sub } = await supabase
    .from('subscriptions')
    .select('stripe_customer_id')
    .eq('user_id', user.id)
    .single()

  let customerId = sub?.stripe_customer_id
  if (!customerId) {
    const customer = await stripe.customers.create({
      email: user.email,
      metadata: { supabase_user_id: user.id },
    })
    customerId = customer.id
    // 把 customer id 存進資料庫
    await supabase.from('subscriptions').upsert({
      user_id: user.id,
      stripe_customer_id: customerId,
    }, { onConflict: 'user_id' })
  }

  const session = await stripe.checkout.sessions.create({
    customer: customerId,
    line_items: [{ price: priceId, quantity: 1 }],
    mode: 'subscription',
    success_url: `${process.env.NEXT_PUBLIC_SITE_URL}/dashboard?upgraded=true`,
    cancel_url: `${process.env.NEXT_PUBLIC_SITE_URL}/pricing`,
  })

  return NextResponse.json({ url: session.url })
}

前端對應的按鈕:

// components/UpgradeButton.tsx
'use client'
export function UpgradeButton({ priceId }: { priceId: string }) {
  async function handleUpgrade() {
    const res = await fetch('/api/billing/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ priceId }),
    })
    const { url } = await res.json()
    window.location.href = url  // 轉到 Stripe Checkout 頁
  }
  return <button onClick={handleUpgrade}>升級 Pro 方案</button>
}

步驟五:Webhook 處理訂閱狀態(最關鍵的一步)

Webhook 是整個金流系統最容易出錯的地方。先在 Stripe Dashboard → Developers → Webhooks 新增 Endpoint,URL 填 https://你的網域/api/billing/webhook,事件選:

• checkout.session.completed
• customer.subscription.updated
• customer.subscription.deleted
• invoice.paid
• invoice.payment_failed

拿到 Webhook signing secret(whsec_...)填進 .env.local。

// app/api/billing/webhook/route.ts
import Stripe from 'stripe'
import { createClient } from '@/utils/supabase/server'
import { headers } from 'next/headers'
import { NextResponse } from 'next/server'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)

// ⚠️ 必須 export config 關閉 body parser,Stripe 驗簽名需要原始 body
export const config = { api: { bodyParser: false } }

export async function POST(request: Request) {
  const body = await request.text()
  const signature = (await headers()).get('stripe-signature')!

  let event: Stripe.Event
  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    )
  } catch {
    // 簽名錯誤:不是 Stripe 發來的,拒絕
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 })
  }

  const supabase = await createClient()

  switch (event.type) {
    case 'checkout.session.completed': {
      const session = event.data.object as Stripe.Checkout.Session
      const customerId = session.customer as string
      const subscriptionId = session.subscription as string
      // 取出訂閱詳情
      const subscription = await stripe.subscriptions.retrieve(subscriptionId)
      await syncSubscription(supabase, customerId, subscription)
      break
    }
    case 'customer.subscription.updated':
    case 'customer.subscription.deleted': {
      const subscription = event.data.object as Stripe.Subscription
      const customerId = subscription.customer as string
      await syncSubscription(supabase, customerId, subscription)
      break
    }
    case 'invoice.payment_failed': {
      const invoice = event.data.object as Stripe.Invoice
      // 付款失敗:把 status 改成 past_due,可以寄通知信
      await supabase
        .from('subscriptions')
        .update({ status: 'past_due' })
        .eq('stripe_customer_id', invoice.customer as string)
      break
    }
  }

  return NextResponse.json({ received: true })
}

async function syncSubscription(
  supabase: ReturnType<typeof createClient> extends Promise<infer T> ? T : never,
  customerId: string,
  subscription: Stripe.Subscription
) {
  // 從 Price ID 判斷方案
  const priceId = subscription.items.data[0].price.id
  const plan = priceId === process.env.STRIPE_PRO_PRICE_ID ? 'pro' : 'free'
  const limit = plan === 'pro' ? 1000 : 50

  await supabase
    .from('subscriptions')
    .update({
      stripe_subscription_id: subscription.id,
      plan,
      status: subscription.status,  // 'active' | 'past_due' | 'canceled' | ...
      current_period_end: new Date(subscription.current_period_end * 1000).toISOString(),
      ai_calls_limit: limit,
      updated_at: new Date().toISOString(),
    })
    .eq('stripe_customer_id', customerId)
}

步驟六:存取控制中介層

Webhook 把訂閱狀態同步進資料庫之後,最後一塊拼圖是保護你的 AI 功能 API。每次使用者呼叫 AI 功能前,先檢查他有沒有資格用、有沒有額度剩:

// utils/checkAccess.ts
import { createClient } from '@/utils/supabase/server'
import { NextResponse } from 'next/server'

export async function checkAccess(requiredPlan: 'free' | 'pro' | 'team' = 'free') {
  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()

  if (!user) {
    return { allowed: false, response: NextResponse.json({ error: '請先登入' }, { status: 401 }) }
  }

  const { data: sub } = await supabase
    .from('subscriptions')
    .select('plan, status, ai_calls_used, ai_calls_limit')
    .eq('user_id', user.id)
    .single()

  // 沒有訂閱紀錄:當 free 方案處理
  const plan = sub?.plan ?? 'free'
  const status = sub?.status ?? 'active'
  const used = sub?.ai_calls_used ?? 0
  const limit = sub?.ai_calls_limit ?? 50

  // 訂閱逾期或取消
  if (status === 'canceled' || status === 'past_due') {
    return { allowed: false, response: NextResponse.json({ error: '訂閱已到期,請更新付款方式' }, { status: 403 }) }
  }

  // 方案不夠高
  const planHierarchy = { free: 0, pro: 1, team: 2 }
  if (planHierarchy[plan as keyof typeof planHierarchy] < planHierarchy[requiredPlan]) {
    return { allowed: false, response: NextResponse.json({ error: '需要升級方案才能使用此功能' }, { status: 403 }) }
  }

  // 額度用完
  if (used >= limit) {
    return { allowed: false, response: NextResponse.json({ error: 'AI 額度已用完,請等下個月或升級方案' }, { status: 429 }) }
  }

  return { allowed: true, userId: user.id, plan, used, limit }
}

在 AI 功能的 API route 裡使用:

// app/api/ai/summarize/route.ts
import { checkAccess } from '@/utils/checkAccess'
import { createClient } from '@/utils/supabase/server'

export async function POST(request: Request) {
  const access = await checkAccess('free')  // 這個功能 free 方案也能用
  if (!access.allowed) return access.response!

  // --- 在這裡執行真正的 AI 邏輯 ---
  const { text } = await request.json()
  // ... 呼叫 Claude API 或 OpenAI ...
  const result = '...'

  // 扣除額度
  const supabase = await createClient()
  await supabase
    .from('subscriptions')
    .update({ ai_calls_used: access.used + 1 })
    .eq('user_id', access.userId)

  return Response.json({ result })
}

到這裡,可以真實收費的最小流程就完整了:使用者登入 → 選方案 → Stripe Checkout 付款 → Webhook 同步狀態 → API 依方案開放功能。