> ## 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-tw/docs/web/before-you-start.md)

[終端基礎知識](https://supastack.dev/zh-tw/docs/web/terminal-basics.md)

[網路本地設定](https://supastack.dev/zh-tw/docs/web/ship-in-5-minutes.md)

[座席提示和專案記憶體](https://supastack.dev/zh-tw/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-tw/docs/web/security.md)

[權利檢查](https://supastack.dev/zh-tw/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-tw/docs/web/agents.md)