> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 构建你的第一个功能

从 schema 到上线界面的一次端到端走查。

## 初学者演练

先决条件：阅读下面的两个初学者指南，完成 Web 本地设置，并在编辑器的根目录中打开此 monorepo。网页设置属于`apps/web/.env.local`； Next.js不读取根`.env`。默认fake模式下的`/dashboard`是无数据库演示； `/auth` 需要迁移数据库。

简而言之：工作区是一个团队的单独用户、数据和设置。服务器是可信后端；让提供商密钥远离浏览器和电话代码。迁移是创建或更新表的版本化数据库更改。人工智能模型是回答的引擎；型号目录是服务器上可用型号 ID 和价格的列表。提供商是一种外部服务，例如人工智能、电子邮件或计费服务。权利是允许工作区使用某项功能的授权。 Webhook 是一个服务发送到另一个服务的 URL 的消息。

1. 在存储库根目录中打开 VS Code，并要求您的编码代理创建 `apps/web/app/reports/page.tsx` 和 `apps/web/src/reports.ts`。为其提供报告字段和允许的角色；需要服务器端成员资格检查和由 `workspaceId` 过滤的查询。

2. 以登录成员身份打开 `/reports`，并仅确认工作区的记录出现。

3. 尝试注销并使用第二工作区帐户；如果其中任何一个可以读取记录，请停止并修复服务器检查。

对于自定义代码，请从提供的 `prompts/README.md` 开始，然后复制最接近的提示：对于应用程序屏幕为 `prompts/new-app-screen.md`，对于公共页面为 `prompts/new-landing-page.md`。对于服务器、数据库或提供商工作，请为您的编码代理提供本指南的任务，并要求其读取 `AGENTS.md`、`.ai/PROJECT_CONTEXT.md` 和匹配的 `.ai/` 镜像；检查此处指定的确切源文件；列出文件并在编辑前进行检查；保留工作区所有权和仅限服务器的机密；并向您展示差异。告诉它您想要的行为、输入和输出字段、允许的角色、预期的成功和错误以及测试帐户、提供程序或设备。使用样本值；永远不要粘贴真正的秘密。

[开始之前](https://supastack.dev/zh/docs/web/before-you-start.md)

[终端基础知识](https://supastack.dev/zh/docs/web/terminal-basics.md)

[网络本地设置](https://supastack.dev/zh/docs/web/ship-in-5-minutes.md)

[座席提示和项目内存](https://supastack.dev/zh/docs/web/agents.md)


## 创建路线

在 `apps/web/app/` 下面添加一个页面。从仪表板或内容路由开始，以便您重用其会话和活动工作区分辨率。当其文件夹包含`page.tsx`时，路由存在；使用服务器组件进行受保护的读取。

```
apps/web/app/reports/page.tsx
apps/web/src/reports.ts
.ai/apps/web/app/reports/page.md
.ai/apps/web/src/reports.md
```


## 解决服务器上的所有权问题

通过现有的身份验证/工作区帮助程序读取登录身份和活动工作区。在加载记录之前验证成员资格。通过解析的 `workspaceId` 过滤每个查询；切勿从表单或模型输出中获取所有者标识符。

检查管理操作的所有者/管理员权限。当功能被付费时，在返回受保护的数据之前检查其在读取或操作边界的权利；隐藏按钮不强制访问。


## 验证访问和恢复

测试匿名访问、有效成员、另一个工作区的成员、已撤销的会话以及所需的角色。通过恢复操作添加空和失败加载状态。将该路线保留在公共站点地图之外，并将其前缀添加到 robots disallows。

[工作空间隔离](https://supastack.dev/zh/docs/web/security.md)

[权利检查](https://supastack.dev/zh/docs/web/setup-payments.md)


## 为记录建模

每个产品记录都始于数据库 schema。在 packages/db 中新增带 workspaceId 列的表，生成迁移，并编写在读写前先解析工作区的仓储助手。

```
// packages/db/src/schema.ts
export const ideas = pgTable("idea", {
  id: uuid().primaryKey(),
  workspaceId: uuid().notNull().references(() => workspaces.id),
  title: text().notNull(),
  createdAt: timestamp().defaultNow(),
});

corepack pnpm --filter @supastack/db db:generate
```


## 为操作授权

创建一个依次解析会话、工作区与 entitlement 的服务端 action。用 zod schema 校验输入，通过仓储执行变更，并返回界面可渲染的类型化结果。

顺序很关键：在检查工作区归属之前就写入的变更已经越过了边界。在服务端推导归属 —— 绝不信任浏览器发来的工作区 id。


## 组装界面

用共享组件与设计令牌搭建页面 —— 套件的 blocks 与 ui-web 原语覆盖了常见模式。处理好加载、错误与空状态；只渲染顺利路径的功能不算完成。


## 下一篇

[用编码代理构建](https://supastack.dev/zh/docs/web/agents.md)