文档

docs.title

docs.subtitle

common.loading

docs.sections.quickStart.title

docs.sections.quickStart.subtitle

docs.sections.quickStart.guide

docs.sections.quickStart.steps.clone

git clone https://github.com/yourusername/nextstarter.git

docs.sections.quickStart.steps.install

npm install

docs.sections.quickStart.steps.configure

docs.sections.quickStart.steps.configureDesc

docs.sections.quickStart.steps.start

npm run dev

docs.sections.techStack.title

docs.sections.techStack.subtitle

docs.sections.techStack.coreStack

docs.sections.techStack.frontendTech

docs.sections.techStack.frontendItems.nextjs
docs.sections.techStack.frontendItems.typescript
docs.sections.techStack.frontendItems.tailwind
docs.sections.techStack.frontendItems.framer

docs.sections.techStack.backendServices

docs.sections.techStack.backendItems.supabase
docs.sections.techStack.backendItems.stripe
docs.sections.techStack.backendItems.vercel
docs.sections.techStack.backendItems.github

docs.sections.configuration.title

docs.sections.configuration.subtitle

docs.sections.configuration.envConfig

docs.sections.configuration.required

docs.sections.configuration.requiredItems.supabaseUrl
docs.sections.configuration.requiredItems.supabaseKey

docs.sections.configuration.optional

docs.sections.configuration.optionalItems.stripeSecret
docs.sections.configuration.optionalItems.stripePublic
docs.sections.configuration.optionalItems.gaId
docs.sections.configuration.optionalItems.resendKey
docs.sections.configuration.optionalItems.resendEmail

docs.sections.email.title

docs.sections.email.subtitle

docs.sections.email.setup

docs.sections.email.envVars

RESEND_API_KEY=your_resend_api_key
RESEND_ADMIN_EMAIL=admin@yourdomain.com

docs.sections.email.description

RESEND_API_KEY: docs.sections.email.apiKeyDesc
RESEND_ADMIN_EMAIL: docs.sections.email.adminEmailDesc

docs.sections.email.importantNote

数据库配置文档

现代Web应用的统一数据库架构配置文档

版本: v1.0•文件: unified-database-setup.sql

📋 总览

本文档详细说明了 Next.js Starter Template 中统一数据库设置脚本的完整架构，包含所有表结构、安全策略、RPC函数、数据视图和索引配置。

🚀 核心特性

7个核心表：用户系统、支付系统、订阅管理

6个RPC函数：业务逻辑处理

3个数据视图：统计和查询优化

完整的安全策略：RLS策略、权限控制

优化索引：高性能查询支持

幂等性执行：可安全重复运行

📊 数据表架构

1. 用户系统表

public.users - 用户基础信息表

扩展 auth.users 表，存储用户的详细信息和偏好设置

id, email, username, avatar_url, is_premium, language, theme_preference...

主要字段结构：

-- 基础用户信息
id UUID PRIMARY KEY                    -- 用户ID (关联auth.users)
email TEXT                           -- 邮箱地址
username TEXT                        -- 用户名
avatar_url TEXT                      -- 头像URL
is_premium BOOLEAN DEFAULT false     -- 是否为付费用户
language TEXT DEFAULT 'en'          -- 语言偏好
theme_preference TEXT DEFAULT 'system' -- 主题偏好
first_name TEXT                      -- 名字
last_name TEXT                       -- 姓氏
display_name TEXT                    -- 显示名称

public.user_credits - 用户积分表

管理用户积分系统，支持积分的获得、消费和统计

user_id, credits, total_earned, total_spent, last_updated

public.credit_transactions - 积分交易记录表

记录所有积分交易的详细信息，提供完整的积分流水

user_id, amount, transaction_type, description, reference_id

2. 支付订阅系统表

public.payment_plans - 付费计划表

定义所有可用的付费计划和价格信息

plan_id, price, currency, billing_cycle, stripe_price_id, quota

public.subscriptions - 用户订阅表

管理用户的订阅状态和支付信息

user_id, stripe_customer_id, stripe_subscription_id, status

🔧 RPC函数

核心业务函数

update_user_credits()

更新用户积分并记录交易

-- 参数：用户ID, 积分变化量, 交易类型, 描述等
SELECT update_user_credits(
    'user-uuid', 
    100, 
    'earn', 
    '完成任务奖励'
);

get_user_subscription_status()

获取用户订阅状态详情

-- 返回用户完整订阅信息
SELECT * FROM get_user_subscription_status('user-uuid');

check_payment_already_processed()

检查支付事件是否已处理（防重复）

-- 防止重复处理Stripe事件
SELECT check_payment_already_processed('evt_stripe_event_id');

📈 数据视图

预定义数据视图

user_subscription_status

用户订阅状态概览，包含计划信息和到期时间

credit_transaction_summary

积分交易汇总统计，按用户聚合交易数据

user_stats

用户综合统计视图，整合积分、订阅等关键指标

🔒 安全策略

Row Level Security (RLS)

所有用户数据表都启用了行级安全策略，确保用户只能访问和修改自己的数据：

用户表：只能查看/更新自己的记录

积分表：只能查看自己的积分信息

交易记录：只能查看自己的交易

订阅表：只能查看/更新自己的订阅

配额使用：只能查看自己的使用记录

订阅事件：只能查看相关事件

💻 使用指南

安装数据库脚本

# 1. 在 Supabase SQL Editor 中执行
# 复制 src/modules/supabase/unified-database-setup.sql 内容并运行

# 2. 或使用 CLI 工具
supabase db reset
supabase db push

常用查询示例

-- 获取用户完整信息
SELECT * FROM user_stats WHERE id = 'user-uuid';

-- 更新用户积分
SELECT update_user_credits('user-uuid', 100, 'earn', '任务完成');

-- 查看交易记录
SELECT * FROM get_recent_transactions('user-uuid', 20, 0);

-- 检查订阅状态
SELECT * FROM get_user_subscription_status('user-uuid');

⚠️ 重要注意事项

脚本具有幂等性，可以安全地重复运行

所有积分操作都在事务中执行，确保数据一致性

RLS策略提供数据安全保护，建议在生产环境启用

定期运行 cleanup_expired_sessions() 清理过期数据

数据库快速参考

快速查找数据库表、函数和策略的简要参考

📋 表结构速览

表名	用途	主要字段	索引数量
`users`	用户基础信息	id, email, username, is_premium	7个
`user_credits`	用户积分	user_id, credits, total_earned	2个
`credit_transactions`	积分交易记录	user_id, amount, transaction_type	5个
`user_quota_usage`	配额使用记录	user_id, usage_type, amount	3个
`payment_plans`	付费计划	plan_id, price, billing_cycle	3个
`subscriptions`	用户订阅	user_id, stripe_subscription_id, status	6个
`subscription_events`	订阅事件	user_id, event_type, stripe_event_id	5个

🔧 RPC函数列表

函数名	用途	参数	返回类型
`update_user_credits()`	更新用户积分	user_id, amount, type等	JSONB
`get_recent_transactions()`	获取交易记录	user_id, limit, offset	TABLE
`check_payment_already_processed()`	检查支付状态	stripe_event_id	BOOLEAN
`get_user_subscription_status()`	获取订阅状态	user_id	TABLE
`get_user_credits()`	获取用户积分	user_id	TABLE
`cleanup_expired_sessions()`	清理过期数据	无	INTEGER

📊 数据视图

视图名	用途	主要字段
user_subscription_status	用户订阅状态	user_id, subscription_status, plan_name
credit_transaction_summary	积分交易汇总	user_id, total_transactions, total_earned
user_stats	用户综合统计	id, current_credits, subscription_status

🔒 安全策略摘要

表名	策略	权限
`users`	只能查看/更新自己的记录	SELECT/UPDATE
`user_credits`	只能查看自己的积分	SELECT
`credit_transactions`	只能查看自己的交易	SELECT
`user_quota_usage`	只能查看自己的使用量	SELECT
`subscriptions`	只能查看/更新自己的订阅	SELECT/UPDATE
`subscription_events`	只能查看自己的事件	SELECT

⚡ 触发器

触发器	表	作用
update_updated_at	users, payment_plans, subscriptions	自动更新时间戳
on_auth_user_created	auth.users	新用户初始化

🔍 常用查询模式

获取用户完整信息

SELECT * FROM user_stats WHERE id = 'user-uuid';

更新积分

SELECT update_user_credits(
    'user-uuid', 100, 'earn', '完成任务'
);

查看交易记录

SELECT * FROM get_recent_transactions('user-uuid', 20, 0);

检查订阅状态

SELECT * FROM get_user_subscription_status('user-uuid');

📈 性能优化提示

索引优化

所有查询都已优化索引，主要在user_id、时间字段

使用LIMIT和OFFSET进行分页

查询技巧

定期执行 cleanup_expired_sessions()

利用视图进行复杂统计查询

🚨 注意事项

所有用户操作都受RLS策略保护

积分操作使用事务确保一致性

Stripe事件有去重机制防止重复处理

软删除字段 deleted_at 用于数据恢复

docs.sections.deployment.title

docs.sections.deployment.subtitle

docs.sections.deployment.vercelDeploy

docs.sections.deployment.steps.connectGithub

docs.sections.deployment.steps.connectGithubDesc

docs.sections.deployment.steps.importVercel

docs.sections.deployment.steps.importVercelDesc

docs.sections.deployment.steps.configEnv

docs.sections.deployment.steps.configEnvDesc

docs.sections.deployment.steps.deploy

docs.sections.deployment.steps.deployDesc

Next Starter

Build your next project with Next Starter