supabase-schema-from-requirements

根据需求定义 Supabase 架构

概述

将业务需求转化为可用于生产环境的 Supabase Postgres 架构，涵盖从规格说明到应用迁移的完整流程：提取实体、创建具有恰当类型和约束的表、配置行级安全策略、性能索引和时间戳触发器，以及生成 TypeScript 类型。尽早做好这项工作至关重要，因为所有下游功能——身份验证、存储、实时功能、边缘函数——都依赖于设计良好的表。

先决条件

• 已安装 Supabase CLI（npm install -g supabase），并已关联项目（supabase link）
• 项目中已安装 @supabase/supabase-js v2+
• 包含实体和访问规则的业务需求、PRD 或规格说明文档
• 本地 Supabase 正在运行（supabase start），或已关联远程项目

说明

步骤 1：解析需求并创建迁移

阅读需求文档，提取实体、属性、关系和访问控制规则。将每个实体映射到一个 Postgres 表。

实体提取示例（项目管理应用）：

实体	关键列	关系
组织	name、slug、plan	拥有多个项目、拥有多个成员
项目	name、description、status	属于某个组织、拥有多个任务
任务	title、priority、status、due_date	属于某个项目、分配给某个用户
成员	role（owner/admin/member）	连接用户与组织的关联表

创建迁移文件：

npx supabase migration new create_tables
# Creates: supabase/migrations/TIMESTAMP_create_tables.sql

使用标准 Postgres 数据类型（uuid、text、integer、boolean、timestamptz、jsonb）编写迁移 SQL： 完整迁移示例（项目管理应用——表、外键、索引、moddatetime 触发器）：references/worked-schema-examples.md。

数据类型选择指南：

用途	类型	说明
主键	uuid	始终使用 uuid_generate_v4() 作为默认值
名称、标题	text	在 Postgres 中优先于 varchar
计数、排名	integer	序列使用 bigint
标志	boolean	明确将默认值设为 true 或 false
时间戳	timestamptz	切勿使用不带时区的 timestamp
灵活数据	jsonb	可查询的 JSON；用于设置、元数据
列表	text[]	Postgres 数组，适用于简单标签或标记

步骤 2：添加行级安全策略

所有暴露给客户端的表都必须启用 RLS。先编写可复用的 security definer 辅助函数，再编写调用这些函数的各表策略。单个表的策略框架：

alter table public.organizations enable row level security;

create policy "Users read own orgs"
  on public.organizations for select
  using (public.is_org_member(id));

完整的策略示例——is_org_member / is_org_admin 辅助函数，以及针对组织、成员、项目和任务的所有 select/insert/update/delete 策略——见 references/rls-policies.md。策略名称应体现对象和操作（"Admins manage members"、"Assignee updates tasks"）。

步骤 3：应用迁移并生成类型

# Apply migration locally
npx supabase db reset

# Or push to a linked remote project
npx supabase db push

# Generate TypeScript types from the live schema
npx supabase gen types typescript --local > types/supabase.ts

将生成的 Database 类型作为 createClient 的泛型参数（参见 import type { Database } from './types/supabase'），以确保每个查询都具备端到端类型安全。完整的类型化客户端指南——涵盖类型化插入、外键联接、多表嵌套联接，以及 RLS 强制执行检查——见 references/typescript-client.md。

输出

• supabase/migrations/ 下包含所有表、约束和索引的 SQL 迁移文件
• 与需求中的访问控制规则相符的 RLS 策略
• 用于复用授权检查的辅助函数（is_org_member、is_org_admin）
• 用于自动管理 updated_at 的 moddatetime 触发器
• 位于 types/supabase.ts 的 TypeScript 类型，用于确保客户端查询类型安全
• 在常用筛选列（status、due_date）上创建部分索引

错误处理

错误	原因	解决方案
42P07: relation already exists	迁移中的表名冲突	使用 create table if not exists 或重命名该表
23503: foreign key violation	插入记录引用了不存在的父记录	先插入父记录，或检查 UUID
42501: insufficient privilege	RLS 辅助函数权限不足	在函数定义中添加 security definer
42883: function uuid_generate_v4() does not exist	未启用扩展	添加 create extension if not exists "uuid-ossp"
supabase db push 成功，但缺少表	迁移已被记录	检查 supabase_migrations.schema_migrations 并修复
PGRST204: column not found	TypeScript 类型不同步	重新运行 npx supabase gen types typescript --local > types/supabase.ts
new row violates row-level security	RLS 策略阻止了该操作	验证 auth.uid() 是否与预期值匹配；检查策略的 using 子句
moddatetime 触发器失败	未启用扩展	在迁移文件顶部添加 create extension if not exists "moddatetime"

示例

电商架构（不同领域，相同模式）。完整的电商迁移 SQL——包含带有外键和索引的商店、产品、订单和 order_items——位于 references/worked-schema-examples.md，对应的类型化客户端查询位于 references/typescript-client.md。

资源

• 行级安全指南
• 数据库迁移
• Supabase CLI 参考
• JavaScript 客户端 — Select
• TypeScript 支持
• PostgreSQL 数据类型

后续步骤

如需在此架构基础上集成身份验证、文件存储和实时订阅，请继续使用 supabase-auth-storage-realtime-core。