For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh-tw/docs/web/first-feature.md (or send Accept: text/markdown).
構建你的第一個功能
從 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/ 映象；檢查此處指定的確切原始檔；列出檔案並在編輯前進行檢查；保留工作區所有權和僅限伺服器的機密；並向您展示差異。告訴它您想要的行為、輸入和輸出欄位、允許的角色、預期的成功和錯誤以及測試帳戶、提供程式或裝置。使用樣本值；永遠不要貼上真正的秘密。
建立路線
在 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驗證訪問和恢復
測試匿名訪問、有效成員、另一個工作區的成員、已撤銷的會話以及所需的角色。通過恢復操作新增空和失敗載入狀態。將該路線保留在公共站點地圖之外，並將其字首新增到 robots disallows。
為記錄建模
每個產品記錄都始於資料庫 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 原語覆蓋了常見模式。處理好載入、錯誤與空狀態；只渲染順利路徑的功能不算完成。