構建你的第一個功能

初學者演練

先決條件：閱讀下面的兩個初學者指南，完成 Web 本地設定，並在編輯器的根目錄中開啟此 monorepo。網頁設定屬於apps/web-tanstack/.env.local； TanStack Start不讀取根.env。預設fake模式下的/dashboard是無資料庫演示； /auth 需要遷移資料庫。

簡而言之：工作區是一個團隊的單獨使用者、資料和設定。伺服器是可信後端；讓提供商金鑰遠離瀏覽器和電話程式碼。遷移是建立或更新表的版本化資料庫更改。人工智慧模型是回答的引擎；型號目錄是伺服器上可用型號 ID 和價格的列表。提供商是一種外部服務，例如人工智慧、電子郵件或計費服務。權利是允許工作區使用某項功能的授權。 Webhook 是一個服務傳送到另一個服務的 URL 的訊息。

1. 在儲存庫根目錄中開啟 VS Code，並要求您的編碼代理建立 apps/web-tanstack/src/routes/reports.tsx 和 packages/web-core/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-tanstack/src/routes/ 下新增一個路由檔案——它呼叫 createFileRoute 來發布頁面。從儀錶板或內容路由開始，以便重用其會話與活動工作區解析；共享頁面原始檔（page.load.ts 與 page.view.tsx）位於 packages/web-core/src/pages/ 下，並通過生成的繫結掛載。使用路由的 loader 進行受保護的讀取。

apps/web-tanstack/src/routes/reports.tsx
packages/web-core/src/reports.ts
.ai/apps/web-tanstack/src/routes/reports.md
.ai/packages/web-core/src/reports.md

解決伺服器上的所有權問題

通過現有的身份驗證/工作區幫助程式讀取登入身份和活動工作區。在載入記錄之前驗證成員資格。通過解析的 workspaceId 過濾每個查詢；切勿從表單或模型輸出中獲取所有者識別符號。

檢查管理操作的所有者/管理員許可權。當功能被付費時，在返回受保護的資料之前檢查其在讀取或操作邊界的權利；隱藏按鈕不強制訪問。

驗證訪問和恢復

測試匿名訪問、有效成員、另一個工作區的成員、已撤銷的會話以及所需的角色。通過恢復操作新增空和失敗載入狀態。將該路線保留在公共站點地圖之外，並將其字首新增到 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 的伺服器函式——處理程式位於 packages/web-core，通過 apps/web-tanstack/src/actions/ 下的 createServerFn 繫結進入應用（使用 corepack pnpm gen:actions 重新生成）。用 zod schema 校驗輸入，通過倉儲執行變更，並返回介面可渲染的型別化結果。

順序很關鍵：在檢查工作區歸屬之前就寫入的變更已經越過了邊界。在服務端推導歸屬 —— 絕不信任瀏覽器發來的工作區 id。

組裝介面

用共享元件與設計令牌搭建頁面 —— 套件的 blocks 與 ui-web 原語覆蓋了常見模式。處理好載入、錯誤與空狀態；只渲染順利路徑的功能不算完成。