架构交互控制台
⚡ Nuxt 4🗄️ Supabase▲ Vercel☁️ Cloudflare🔷 Vue 3

单仓库混合渲染工程方案 v1.0

单仓库混编渲染方案,集成 API 服务、SPA 管理后台、ISR 官网及多域名活动落地页,使用接口优先契约与自动化提效手段维护。

适用项目类型
多端全栈服务(C 端用户 + 管理后台 + 移动端 API)
架构模式
单仓混合渲染 + 泛域名动态路由
开发范式
接口先行设计、多端代码生成与本地仿真调试流
模块构成
4 个核心模块 · 17 个细分章节
01

架构全景总览

系统分层架构图

客户端入口Cloudflare 边缘Vercel 运行时Nuxt 4 单仓后端数据服务
① 外部客户端层
📱
移动端 App
iOS / Android
📲
独立 H5
微信 / 抖音
🖥️
官网浏览器
yourdomain.com
⚙️
管理后台
admin.yourdomain.com
HTTPS 加密传输
② Cloudflare 边缘层(可选·免费)
🌐
DNS 代理
泛域名通配符解析
🚀
全球 CDN
静态资源加速
🛡️
WAF 防火墙
DDoS / 恶意流量
🔒
SSL 终止
Full (Strict) 模式
回源 HTTPS · Full Strict
③ Vercel Edge Runtime 层
🔀
Edge Middleware
子域名分流路由
ISR / SWR 缓存
静态边缘缓存策略
🖼️
图片优化
AVIF / WebP 转换
路由分发至 Nuxt 4 单仓三大子系统
ISR · SWR官网 / 营销 H5
yourdomain.com & *.yourdomain.com
Vue 3 SSRNuxt 4UnoCSSSEO 100分
app/pages/(client)/ & (h5)/
SPA · ssr:false管理后台 Admin
admin.yourdomain.com
Vue 3 SPA权限隔离审计日志数据大盘
app/pages/(admin)/
纯 JSON · no-storeAPI 引擎
api.yourdomain.com
Nitro ServerBearer/CookieOpenAPI多端兼容
server/api/v1/
Nuxt 4 混合单仓 · Nitro 引擎 统一 Auth 中间件 · 统一响应格式 · 统一错误处理server/middleware/ · server/utils/
服务端调用后端数据服务
⑤ 后端数据与服务层
🗄️
Supabase
PostgreSQLAuthRLSRealtimeStorage
📊
Analytics
DashboardReports实时监控
🔗
第三方服务
Resend 邮件短信AI API

四大子系统对应关系

官网 Corporate
yourdomain.com
→ /app/pages/(client)/
ISR · 1h
品牌展示、产品介绍、SEO 主力阵地。增量静态再生,首字节延迟趋近 0ms。
营销 H5 矩阵
*.yourdomain.com
→ /app/pages/(h5)/h5/[subdomain]/
SWR · 10min
各类活动推广、拉新转化落地页。动态配置驱动,无代码发布新活动。
管理后台 Admin
admin.yourdomain.com
→ /app/pages/(admin)/admin/
SPA · 无缓存
用户管理、数据大盘与运营工具。强权限隔离,完全禁止 SSR。
API 引擎 Engine
api.yourdomain.com
→ /server/api/v1/
纯接口 · 无缓存
面向 App/H5 提供纯净 RESTful 接口,双模式鉴权,OpenAPI 自动生成。
02

技术栈选型与职责划分

🔷
Vue 3
管理后台 UI 与官网渲染
3.5+ · script setup · Composition API
Nuxt 4 + Nitro
SSR/ISR/SWR 路由 · Server API 引擎
4.x · Hybrid Rendering
🗄️
Supabase 团队版
PostgreSQL · RLS · Auth · Realtime · DB Branching
Team Plan · $25/mo/project
Vercel 团队版
Serverless 部署 · 边缘函数 · 图片优化
Team Plan · $20/mo/member
🐙
GitHub 团队版
代码审查 · 分支保护 · Actions CI/CD
Team Plan · Actions 2000min/mo
☁️
Cloudflare 免费版
泛域名代理 · 全球 CDN · WAF · SSL
Free · 100G 出口流量免费
📊
Google Analytics
用户行为分析 · 转化漏斗 · 实时监控
GA4 · 免费额度充足
🎨
UnoCSS
轻量原子化 CSS · 官网/H5 零全局污染
Atomic CSS · 极轻量打包
03

单仓目录结构规范

📌
AI Coding 强制约束此目录结构是所有 AI Agent 的强制约束。不允许在根目录下随意创建新的顶层目录。前台/后台/API 三层物理隔离,防止样式污染与安全越权。
Directory Structure
hehe-app/                            # 单仓根目录
├── app/                              # Nuxt 4 前端渲染层(Vue 3 组件与页面)
│   ├── components/
│   │   ├── client/                   # 官网/H5 专用轻量组件
│   │   ├── admin/                    # 管理后台专用重型组件(ECharts 等)
│   │   └── shared/                   # 前后台通用的极轻量组件
│   ├── composables/
│   │   ├── seo.ts                    # useAppSEO:SEO 注入统一入口(官网/H5 必须调用)
│   │   └── auth.ts                   # useAuth:客户端会话状态管理
│   └── pages/
│       ├── (client)/                 # 官网路由分组 → yourdomain.com
│       ├── (h5)/h5/[subdomain]/      # 营销 H5 → *.yourdomain.com
│       └── (admin)/admin/            # 管理后台 → admin.yourdomain.com
│
├── server/                           # Nitro 服务端层(Node.js API 引擎)
│   ├── middleware/
│   │   ├── 01.subdomain-rewrite.ts  # 子域名动态路由重写
│   │   ├── 02.auth.ts               # 全局 Auth 解析(Bearer + Cookie 双兼容)
│   │   └── 03.admin.ts              # Admin API 路由强拦截
│   ├── api/
│   │   ├── v1/                       # 对外公开 API(api.yourdomain.com)
│   │   └── admin/                    # 管理员专用私有 API
│   └── utils/
│       ├── auth.ts                   # assertUser / assertAdmin 鉴权断言
│       ├── audit.ts                  # writeAuditLog 操作审计日志
│       ├── ip.ts                     # getClientRealIP(优先 CF-Connecting-IP)
│       └── analytics.ts             # 数据分析埋点与上报
│
├── supabase/migrations/              # 数据库迁移 SQL(版本控制严格管理)
├── .github/workflows/                # CI 流水线(类型/安全/性能/DB 自动化校验)
├── .cursorrules                      # AI Coding 强制规范(Cursor/Claude 读取)
└── nuxt.config.ts                    # 核心配置(路由规则·渲染模式·缓存·图片)
04

多域名流量路由设计

Edge Middleware 核心实现

TypeScript · server/middleware/01.subdomain-rewrite.ts
export default defineEventHandler((event) => {
  const host = getHeader(event, 'host') || ''
  const path = event.path
  // 跳过静态资源与内部 Nuxt 路由
  if (path.startsWith('/_nuxt/') || path.startsWith('/api/')) return

  const ROOT_DOMAIN = useRuntimeConfig().rootDomain

  // 1. 官网:主域名或 www
  if (host === ROOT_DOMAIN || host === `www.${ROOT_DOMAIN}`) {
    if (!path.startsWith('/client'))
      event.node.req.url = `/client${path === '/' ? '' : path}`
    return
  }

  // 2. 管理后台
  if (host.startsWith('admin.')) {
    if (!path.startsWith('/admin'))
      event.node.req.url = `/admin${path}`
    return
  }

  // 3. API 引擎(禁止前台路由越界)
  if (host.startsWith('api.')) {
    if (!path.startsWith('/api/v1/'))
      throw createError({ statusCode: 404, statusMessage: 'API Not Found' })
    return
  }

  // 4. 动态营销 H5 子域名 *.yourdomain.com
  const parts = host.split('.')
  if (parts.length >= 3) {
    const subdomain = parts[0]
    if (!path.startsWith(`/h5/${subdomain}`))
      event.node.req.url = `/h5/${subdomain}${path === '/' ? '' : path}`
  }
})
05

混合渲染模式与边缘缓存策略

🚀
ISR
Incremental Static Regeneration
3600s
边缘缓存生命周期
/client/**
官网页面。首字节 0ms,SEO 100 分,边缘节点后台异步刷新,完全不阻塞用户请求。
SWR
Stale While Revalidate
600s
边缘缓存生命周期
/h5/**
营销 H5。支持动态配置实时更新,活动高峰流量直接命中边缘节点,零服务器压力。
🔒
SPA
Client-Side Rendering (ssr: false)
无缓存
权限敏感,实时交互
/admin/**
管理后台。完全禁用 SSR,防止敏感数据在服务端泄露,彻底隔离重型 Admin 组件包。
🌐
API
Pure Serverless API (No Render)
no-store
绝对禁止任何缓存
/api/**
对外 API 引擎。支持 CORS 多端访问,Bearer/Cookie 双模式鉴权,实时响应移动端 App。
06

鉴权体系设计(多端兼容)

多层拦截鉴权机制

🛡️
第一层:Cloudflare WAF
拦截恶意爬虫、DDoS 流量,对 /api/admin/** 来源非 admin 域名的请求直接封锁
CF 边缘
🌐
第二层:Edge Middleware 域名重写
api 域名强制限制在 /api/v1/* 路由,admin 域名拦截非后台请求越界访问
Vercel Edge
🔑
第三层:全局 Auth 中间件(02.auth.ts)
解析 Cookie(Web/H5)或 Bearer JWT(App),将 Supabase 用户态注入 event.context.user
Nitro 中间件
🚫
第四层:Admin API 强拦截(03.admin.ts)
匹配 /api/admin/** 自动执行 assertAdmin(event),无管理员 role 强制返回 403
Nitro 中间件
🔐
第五层:Supabase RLS 行级安全
数据库层数据访问约束,即使绕过前四层,RLS 策略仍能确保用户仅访问授权数据
Supabase PG

双模式 Token 解析

TypeScript · server/utils/auth.ts
// assertUser: 验证用户身份(支持 Cookie + Bearer 双模式)
export async function assertUser(event: any) {
  const user = event.context.user
  if (!user) throw createError({ statusCode: 401, statusMessage: 'Unauthorized' })
  return user
}

// assertAdmin: 在 assertUser 基础上额外验证管理员角色
export async function assertAdmin(event: any) {
  const user = await assertUser(event)
  const { data: profile } = await client.from('profiles')
    .select('role').eq('id', user.id).single()

  if (profile?.role !== 'admin')
    throw createError({ statusCode: 403, statusMessage: 'Admin Access Forbidden' })
  return user
}
07

管理后台模块设计

核心功能模块

模块路由核心功能
数据大盘/admin用户活跃趋势;注册转化漏斗;实时数据快照
用户管理/admin/users用户列表(分页 ≤ 100);账号禁用/启用;会员等级手动调整
商品管理/admin/products商品列表;价格调整;库存状态管理;批量操作
营销活动/admin/campaigns新建/编辑/下线 H5 活动;二级子域名绑定;实时预览
审计日志/admin/audit-logs管理员所有操作记录;时间/操作人/IP 多维筛选;不可删除
⚠️
AI 编码强制约束所有 /api/admin/ 路由中涉及数据写入、删除、状态变更的操作,必须在业务逻辑执行后、响应返回前调用 writeAuditLog()。否则 CI 静态扫描将阻断合入。
08

请求耗时与系统指标采集

监控流程

1
请求拦截埋点
中间件 00.apm.ts 自动记录每次 API 请求的路径、耗时、状态码
2
滑动窗口计算
实时计算最近 100 次请求的平均时延、P95、P99 与报错率
3
阈值告警触发
时延超 800ms (Warning) 或 2000ms (Critical) 自动记录警报并高亮输出
4
系统资源快照
采集物理内存占用、CPU 负载与 Node 运行时长写入 APM 数据池
5
后台可视化展示
Admin 监控面板实时轮询渲染图表,支持一键模拟告警验证
6
活动日志写入
关键操作自动记录至 activity_logs 表,不可删除,可一键导出 CSV
09

性能与 SEO 优化指标

Core Web Vitals 指标目标

指标目标值CI 强制阻断阈值
LCP 最大内容绘制< 1.5s⛔ > 2.0s 强制打回
INP 交互延迟< 100ms⚠️ > 200ms 警告
CLS 布局偏移< 0.05⛔ > 0.1 强制打回
SEO 评分 Lighthouse100 分⛔ < 95 分强制打回
无障碍 a11y≥ 95 分⚠️ < 90 分警告
💡
AI 图片规范官网和 H5 中所有图片必须使用 <NuxtImg> 代替原生 <img>。首屏 Banner 必须添加 preload、fetchpriority="high" 和 loading="eager",确保 LCP 资产最优先下载。
10

Cloudflare 接入方案(可选·免费)

ℹ️
透明叠加,零侵入Cloudflare 作为前置 DNS 代理与 CDN 加速层接入。接入后不需要修改任何 Nuxt 4 代码或 Vercel 配置,完全透明叠加在现有架构之上。

DNS 配置规则

类型名称目标(Content)代理状态
CNAMEyourdomain.comcname.vercel-dns.com🟠 已代理
CNAMEwwwcname.vercel-dns.com🟠 已代理
CNAMEadmincname.vercel-dns.com🟠 已代理
CNAMEapicname.vercel-dns.com🟠 已代理
CNAME*(泛解析)cname.vercel-dns.com🟠 已代理
🚨
SSL/TLS 必须设为"完全(严格)Full (Strict)"绝对不能选择"灵活 Flexible"模式。否则 Cloudflare 用 HTTP 回源 Vercel,Vercel 强制 301 跳转 HTTPS,导致浏览器触发 ERR_TOO_MANY_REDIRECTS 无限重定向死循环崩溃。
11

数据库设计规范(Supabase 团队版)

核心数据表

SQL · supabase/migrations/init.sql
-- 用户档案表(与 auth.users 关联)
CREATE TABLE profiles (
  id                 UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
  username           TEXT UNIQUE NOT NULL,
  role               TEXT NOT NULL DEFAULT 'user' CHECK (role IN ('user', 'admin')),
  plan_status        TEXT NOT NULL DEFAULT 'free' CHECK (plan_status IN ('free', 'pro', 'enterprise')),
  created_at         TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 营销活动配置表(驱动动态 H5 渲染)
CREATE TABLE marketing_campaigns (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  subdomain   TEXT UNIQUE NOT NULL,
  title       TEXT NOT NULL,
  config      JSONB NOT NULL DEFAULT '{}',
  is_active   BOOLEAN NOT NULL DEFAULT TRUE,
  created_at  TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 必须开启 RLS(CI 门禁自动检查)
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;
ALTER TABLE marketing_campaigns ENABLE ROW LEVEL SECURITY;
ALTER TABLE activity_logs ENABLE ROW LEVEL SECURITY;
12

CI/CD 自动化构建与验证门禁(GitHub 团队版)

门禁 01
静态类型与代码合规
npx vue-tsc --noEmit
TS 类型全检,验证前台/后台/API 三层的接口契约是否完全对齐。同时运行 ESLint 代码风格检查。
类型不匹配 → 强制退回
门禁 02
API 安全越权自动化测试
curl /api/admin/users → 必须 401/403
自动模拟匿名用户和普通用户请求 /api/admin/** 管理接口,验证必须被强拦截。
越权放行 → 立即阻断
门禁 03
Supabase RLS 安全检查
npx supabase db lint
检查所有 SQL 迁移文件语法正确性,验证新增数据表是否已开启 RLS,防止数据越权读取。
RLS 缺失 → 强制阻断
门禁 04
Web Vitals 性能门禁
Lighthouse CI Action
仅在 /pages/(client)/ 或 /pages/(h5)/ 有改动时触发。LCP > 2s 或 SEO < 95 直接阻断合入。
LCP 退化 → 退回修复
13

代码生成规范与自动化校验保障

多 Agent 协作分工

Agent工作范围禁止触碰
前台 Agent (A)app/pages/(client)/ app/pages/(h5)/ app/components/client/admin 组件 · server/ 目录
后台 UI Agent (B)app/pages/(admin)/ app/components/admin/官网/H5 样式文件
API Agent (C)server/api/ server/utils/ supabase/migrations/前端 Vue 组件

.cursorrules 核心禁令(节选)

Markdown · .cursorrules
## 目录规范
- 严禁在根目录创建非规范的顶层目录
- 官网/H5 组件必须放在 app/components/client/ 或 shared/
- 管理端组件必须放在 app/components/admin/ 并使用局部导入

## 安全规范
- 严禁将 SUPABASE_SERVICE_ROLE_KEY 出现在任何前端代码中
- APM 告警阈值必须配置多级梯度,防止误报干扰

## 平台职责边界规范
- 严禁开通或使用 Vercel Postgres:数据库统一使用 Supabase PG
- 严禁将 HTTP API 路由写入 Supabase Edge Functions
- 限流计数器必须使用 Vercel KV,不得用 Supabase DB 表模拟

## 数据库规范
- 严禁在 Node.js 中对 >1000 条数据做内存级 reduce/map 聚合
- 统计类 API 必须命中 Materialized View 或预聚合表
- 所有列表查询必须限制 pageSize ≤ 100

## 审计规范
- 管理端所有写入/删除操作,必须在返回前调用 writeAuditLog()

## IP 规范
- 必须使用 getClientRealIP(event),禁止使用 getRequestIP()
14

本地开发沙盒配置

一键启动脚本

JSON · package.json scripts
{
  "scripts": {
    "supabase:start":  "supabase start",
    "apm:monitor":     "node scripts/test-supabase-connection.mjs",
    "dev":             "nuxt dev",
    "dev:all":         "concurrently \"npm:supabase:start\" \"npm:dev\"",
    "gen:types":       "supabase gen types typescript --local > app/types/database.types.ts",
    "check":           "vue-tsc --noEmit && eslint 'app/**/*.vue' 'server/**/*.ts'",
    "test:api-safety": "vitest run server/tests/security"
  }
}

本地多域名仿真(/etc/hosts)

Hosts File
127.0.0.1  yourdomain.localhost
127.0.0.1  www.yourdomain.localhost
127.0.0.1  admin.yourdomain.localhost
127.0.0.1  api.yourdomain.localhost
127.0.0.1  promo-test.yourdomain.localhost  # 测试营销 H5 子域名
15

项目启动检查清单

🏗️ 基础设施

Supabase 团队版项目创建,DB 分支功能开启
Vercel 团队版项目配置,绑定 GitHub 仓库
Cloudflare 添加域名,配置泛解析 CNAME
GitHub 团队版分支保护规则配置

💻 代码工程

nuxt.config.ts 路由规则与渲染模式配置完成
子域名重写中间件配置并通过本地测试
Auth 中间件(Cookie + Bearer 双模式)配置完成
.cursorrules AI 编码规范文件就绪

🔐 安全与合规

所有数据表已开启 RLS(supabase db lint 通过)
性能监控告警就绪,P95/P99 时延基线已校准
getClientRealIP 工具函数覆盖所有 IP 读取场景
GitHub Actions CI 验证门禁配置完成

🚀 性能

@nuxt/image 模块配置,官网首屏图片使用 preload
useAppSEO() 封装完成,官网/H5 强制调用
Lighthouse CI 预算文件配置(LCP < 2s 门禁)
Cloudflare HTTP/3 与 Brotli 压缩开启

📋 平台职责确认

确认未开通 Vercel Postgres,数据库完全由 Supabase 承接
确认用户上传文件使用 Supabase Storage(RLS 隔离)
确认 Vercel KV 用于限流计数器等高频 KV 场景
确认所有 HTTP API 在 /server/api/,无 Edge Function 承接路由
16

平台职责边界决策(Supabase vs Vercel)

📌
架构硬性决策Supabase 负责"数据与身份",Vercel 负责"计算与交付"。两者都不应越界。错误使用将导致重复付费、数据孤岛、安全漏洞与架构混乱。

6 大重叠能力裁判结果

重叠能力选择平台核心决策理由
关系型数据库✅ Supabase PGRLS 行级安全 + Auth 深度集成 + DB 分支不可替代;Vercel Postgres 不具备这些企业级能力
文件存储✅ 场景分治用户私密文件 → Supabase Storage(RLS);公开营销素材 → public/ 目录 + Cloudflare CDN
HTTP API 路由✅ Vercel Nitro所有业务 HTTP API 由 Nuxt 4 Nitro 承接;Supabase Edge Functions 仅用于 DB 触发器增强
KV 缓存(限流)✅ Vercel KVSupabase 无内置 Redis;Vercel KV(Upstash Redis)直接补位
用户身份鉴权✅ Supabase AuthVercel 无原生 Auth;Supabase Auth 提供完整 OAuth/邮箱验证并与 DB/RLS 深度集成
Analytics 监控✅ 两者互补Supabase 看后端基础设施(DB 负载);Vercel 看前端体验(Web Vitals);维度不重叠

职责边界全景图

🗄️ Supabase 专属领土

数据持久化PostgreSQL 所有业务表与关系设计
用户身份Auth:邮箱 / OAuth / Magic Link / JWT
行级安全RLS Policy 所有权限控制逻辑
用户私密文件上传文件:头像 / 文档 / 付费内容
实时推送Realtime WebSocket 数据变更订阅
数据库分支PR 级别的 Schema 隔离测试
定时任务pg_cron 刷新物化视图 / 定期清理

▲ Vercel 专属领土

代码构建与托管Nuxt 4 全栈应用 Serverless 部署
静态资源 CDNJS / CSS / 字体 / 公开图片全球分发
图片优化边缘压缩与 AVIF/WebP 格式转换
Preview 部署PR 自动生成隔离预览环境
API 路由执行Nitro Serverless & Edge Runtime
Web Vitals 监控真实用户 LCP / INP / CLS 数据采集
KV 高频缓存Vercel KV(Upstash Redis)限流 / 计数

🚫 灰色地带——明确禁止重复使用

🚫
Vercel Postgres禁止开通,DB 全部走 Supabase PG
🚫
双平台存储冗余同类文件禁止同时走两个存储服务
🚫
Edge Fn 承接路由HTTP API 路由禁止写入 Supabase Edge Fn

AI Coding 三大平台陷阱

⚠️
陷阱一:双平台存储冗余 AI 可能在 Nuxt 4 API 层先上传文件到 Vercel Blob,再触发 Supabase Storage 同步,造成同一份文件两处冗余、成本翻倍。
→ .cursorrules 约束:公开静态资产走 public/ 目录,用户上传走 Supabase Storage,禁止引入 Vercel Blob。
⚠️
陷阱二:HTTP 路由写入 Supabase Edge Function AI 有时将新业务接口写成 Supabase Edge Function,导致两套 API 体系并行,安全策略无法统一。
→ .cursorrules 约束:所有 HTTP API 路由只能在 /server/api/ 下,严禁写 Supabase Edge Function 承接 HTTP 路由。
⚠️
陷阱三:Service Role Key 位置错误 AI 可能将 SUPABASE_SERVICE_ROLE_KEY 误打包进前端 Bundle,造成超级管理员权限泄漏。
→ .cursorrules 约束:Service Role Key 只能存放在 Vercel 服务端专用环境变量(非 NUXT_PUBLIC_ 前缀)。
💡
成本控制三问原则 在引入任何新服务前,先回答:① 这个能力是否已被 Supabase 或 Vercel 其中之一覆盖?② 若两者都覆盖,与"数据安全/用户身份"更强相关?→ 选 Supabase。③ 若两者都覆盖,与"交付性能/计算速度"更强相关?→ 选 Vercel。
17

自动化开发辅助与调试技巧 (v1.0 增补)

💡
工程自动化与开发协同 单人全栈模式侧重于通过构建自动化验证门禁与强类型契约,来大幅缩减测试与维护周期。以下是常用的提效工程实践。

一、人机协同与类型契约 (Type & Contract)

1. 端到端全自动类型闭环

自动抽取 DB Schema 类型
通过自动化脚本将 Supabase 生成的 database.types.ts 转换为前端/API 复用的 TableRow<T> 强类型。
Nuxt 4 接口自动推断
借助 Nitro 引擎,前端 useFetch 调用 API 时完全无需手动声明返回类型,AI 在前端编码时可 100% 自动补全。
Zod/Valibot 统一契约
用 Schema-Driven 方式编写输入校验,AI 可据此同步生成前端 UI 表单验证与后端过滤逻辑,消灭类型漂移。

2. AI 友好自动脚手架生成器

运行本地 scripts/scaffolder.mjs,为 AI 搭建严格符合架构规范的前后端“毛坯房”,规避 AI 因理解大上下文产生的幻觉。

CLI
node scripts/scaffolder.mjs billing
# [OK] Created API: server/api/v1/billing/index.post.ts
# [OK] Created Page: app/pages/(client)/billing.vue

3. UnoCSS × AI 审美护城河

在 unocss.config.ts 中将高质感视觉设计(如 Glassmorphism 玻璃拟态卡片、现代微动效按钮、深色渐变背景)固化为别名 Shortcuts,禁止 AI 任意硬编码颜色,通过 .cursorrules 指引 AI 拼装出 Apple/Stripe 级别的极致现代设计。

unocss.config.ts
// shortcuts 示例
shortcuts: {
  'glass-card': 'bg-white/70 backdrop-blur-md border border-white/20 shadow-lg rounded-2xl',
  'btn-premium': 'bg-brand-primary hover:bg-brand-primary/90 text-white px-6 py-3 rounded-xl transition-all duration-200 hover:-translate-y-0.5 shadow-md'
}

二、离线沙盒与安全栅栏 (Sandbox & Security)

4. 本地零依赖快速沙盒引擎 (Mock Mode)

无需启动庞大笨重的 Supabase Docker 镜像。在 /server/utils/db.ts 中通过 MOCK_DB=true 开启内存/JSON 伪装层。支持高铁、咖啡厅、笔记本低电量等移动办公场景下秒级冷启动,预览流转,精细联调时再切回真实 DB。

TypeScript
export function getDB(event: any) {
  if (process.env.MOCK_DB === 'true') {
    return getLocalMockDB() // 返回内存伪装层
  }
  return dbClient // 返回真实 Supabase Client
}

5. SQL 注释驱动 RLS 与安全测试环

🛡️
SQL 注释驱动声明
在 migrations 中使用 -- @rls: enable 等元数据声明,本地校验脚本强制 AI 必须同步编写安全策略。
🛡️
单元越权模拟测试
编写 rls.test.ts,模拟不同权限的越权请求,100% 阻断 AI 因不理解 RLS policy 而导致的写表越权和漏配漏洞。

三、多端融合与全球合规 (Cross-platform & Compliance)

6. Capacitor 移动端融合架构 (多端同源)

在 Nuxt 单仓中直接引入 Capacitor,免去重写 React Native/Flutter 带来的人力耗费。打包 App 路由为 Native 壳,配合 Vercel 静态导出,在合规红线内实现 Bug 修复的秒级热更新。

Shell
# 安装 Capacitor 并创建原生壳
npm i @capacitor/core @capacitor/cli @capacitor/ios @capacitor/android
npx cap init "MyApp" "com.myapp.app" --web-dir=.output/public
npx cap sync

7. 全球合规与安全基线

RLS + JWT 双重防御
数据库层面通过 RLS Policy 强制数据隔离,API 层面通过 JWT 令牌 + assertUser 断言双重保障,任何越权操作在物理层被拦截。
GDPR Cookie 声明代码化
在 Layout 中使用轻量 cookieconsent 声明,仅在用户同意后才初始化第三方分析统计,彻底规避欧盟巨额罚款风险。
⚠️
Capacitor 移动端与热更新审核红线警告 (Apple App Store Compliance)
  • 禁止套壳直连:严禁直接加载远程 Vercel URL 作为 App 主内容(违反 Guideline 4.2 最小功能网页套壳禁令)。必须将静态资源构建后使用 npx cap sync 打包进 Native 本地包体内。
  • 热更新界限:热更新只能用于修复 Bug 和 UI 微调。严禁通过热更新更改 App 核心特征/主要功能(违反 Guideline 2.5.2),更不得绕过审核上架违规功能,否则面临直接下架或封号风险。
  • 支付双轨制限制:iOS 原生 App 中严禁使用 Stripe 等第三方支付绕过 App 内购买 (IAP)(违反 Guideline 3.1.1)。针对数字虚拟商品,必须走 Apple IAP 支付,或者做成“Reader App(仅提供登录消费,去掉 App 内购买按钮)”。

四、AI 运维与全球化 (AI Ops & Localization)

8. GitHub Actions AI 自愈 (Self-Healing CI)

当 CI 步骤如 ESLint 或 TypeScript 校验失败时,触发 AI Healer 机器人,自动读取最后一次运行报错日志,调用大模型 API 修复文件并自动 Push 回分支。人类只需专注核心商业逻辑。

YAML
# ci-self-heal step 核心逻辑
if: failure() && github.event_name == 'pull_request'
run: |
  node scripts/ai_healer.js
  git commit -am "style: [AI Auto-Heal] fix issues" && git push

9. LLM 全自动 i18n 提取与语义化翻译

借助 @nuxtjs/i18n,配合扫描脚本自动提取代码中的 $t() Key,使用大模型扮演多语言本地化专家,进行地道、专业的产品语义翻译(如 locales/en.jsonlocales/ja.json 自动写入),告别生硬机翻。

JavaScript
node scripts/auto-translate.mjs
# 1. 扫描 app/ 目录提取未翻译 $t() Key
# 2. 调用 LLM 翻译为地道多国语言,自动对齐写入 locales/*.json

10. 零配置 Telemetry 极简监控

监控维度选型提效原理解析
异常采集Sentry (Nuxt SDK)Nitro Server 中统一拦截,崩溃错误秒级捕获,无需编写臃肿逻辑。
全局日志流Axiom零部署零维护。Vercel 产生的控制台日志自动导流,每月 500GB 免费,配合 SQL 级多维搜索。
用户行为分析Vercel Web Analytics开箱即用,隐私合规,无需配置庞大的 Google Analytics 自定义埋点。
18

三方支付系统集成 (Stripe Checkout)

Stripe Checkout 支付流程

1
前端发起支付
H5 页面调用 usePayment() composable,POST /api/v1/payments/create 创建订单
2
创建 Checkout Session
服务端调用 Stripe API 创建托管支付会话,返回支付 URL 与 Session ID
3
跳转 Stripe 托管页
用户重定向至 Stripe 托管支付页,完成信用卡/Apple Pay/Google Pay 支付
4
Webhook 回调
Stripe 向 /api/v1/payments/webhook 推送 checkout.session.completed 事件
5
订单状态更新
服务端验证 Webhook 签名后更新订单状态为 paid,写入审计日志
6
前端确认展示
用户返回 /payments/confirm 页面,展示支付成功状态与订单详情

Webhook 安全验证

TypeScript · server/utils/payments.ts
// Stripe Webhook 签名验证(策略层自动从 DB 读取密钥)
const strategy = getPaymentStrategy('stripe')
const result = await strategy.verifyWebhook(rawBody, signature)
// 支持事件类型:checkout.session.completed / charge.refunded
⚠️
安全强制约束Stripe Secret Key 严禁出现在前端代码;Webhook 端点必须验证签名(02.auth.ts 中已加白名单);所有金额计算必须使用 NUMERIC 类型,严禁浮点数。

数据库表设计

表名核心字段用途
ordersorder_no, amount, currency, status, payment_intent_id订单全生命周期追踪(pending→paid→refunded)
activity_logscategory, user_id, action, ip, metadata, created_at统一日志(auth/admin/system),JSONB metadata 灵活扩展
20

移动端用户认证体系

认证流程全链路

1
匿名用户浏览
H5 页面加载时自动 signInAnonymously(),device_id 写入 Cookie 标识设备,用户可浏览活动信息
2
触发登录引导
用户点击支付/预约时,若未登录则弹出 H5LoginModal,缓存待执行操作(pendingAction)
3
多方式登录
支持 Email+Password、Google OAuth、Facebook OAuth、Apple OAuth,客户端直连 Supabase Auth
4
Token 同步
登录成功后 access_token 写入 sb-access-token Cookie,supabase-auth.client.ts 插件监听 onAuthStateChange 自动同步
5
服务端识别
02.auth.ts 中间件从 Cookie/Bearer 提取 token,调用 Supabase getUser() 解析身份,写入 event.context.user
6
权限守卫
04.auth-guard.ts 拦截支付/订单接口,拒绝匿名用户访问,返回 403 引导登录

支持的登录方式对照

登录方式Provider实现机制适用场景
Email + PasswordemailSupabase signUp / signInWithPassword通用注册登录
GooglegoogleSupabase OAuth (signInWithOAuth)海外主流用户
FacebookfacebookSupabase OAuth (signInWithOAuth)东南亚/拉美用户
AppleappleSupabase OAuth (signInWithOAuth)iOS 用户(App Store 审核要求)
AnonymousanonymousSupabase signInAnonymously + device_id先浏览后登录

Token 生命周期管理

Access Token (1h)

短期有效 JWT,存储在 sb-access-token Cookie。每次 API 请求由 server middleware 验证。过期后自动用 Refresh Token 续期。

Refresh Token (30d)

长期有效 token,存储在 sb-refresh-token Cookie。Supabase SDK 自动在 access_token 过期前调用 refreshSession()。

Device ID (365d)

设备指纹,存储在 device-id Cookie。用于匿名用户标识和行为数据关联,绑定账号后迁移到 user_id。

匿名→绑定数据迁移策略

1
匿名用户行为记录
页面浏览等行为数据关联 device_id,存储在 activity_logs 等表中
2
触发绑定
用户点击“绑定账号”或“注册享更多”,调用 POST /api/v1/auth/link 绑定邮箱
3
身份转换
profiles 表更新 is_anonymous=false, auth_provider=email。Supabase Auth linkIdentity 合并身份
4
数据归属
后续新数据直接关联 user_id,历史行为数据可通过 device_id 回溯(审计用途)

数据库表设计

表名关键字段RLS 策略
profilesavatar_url, display_name, auth_provider, provider_id, device_id, is_anonymous, email_verified用户读写自己,admin 全权限
ℹ️
自动 Profile 创建迁移脚本 0003_user_auth.sql 包含 handle_new_user() 触发器函数,新用户通过 Supabase Auth 注册时自动在 profiles 表创建记录,无需前端额外处理。