> ## 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

# 構建你的第一個功能

從新建介面到伺服器校驗資料的端到端演練。

## 初學者演練

先決條件：閱讀下面兩篇入門指南，完成 Mobile 本地安裝，並在編輯器中以根目錄開啟此儲存庫。Mobile 設定放在 `apps/mobile/.env.local`；Expo 不讀取根目錄的 .env。預覽需要一個可訪問的後端才能獲取真實資料。

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

1. 開啟 `.agents/skills/add-a-mobile-screen/SKILL.md`——或讓您的編碼代理照它執行——並建立一個小介面，例如 `apps/mobile/app/(app)/ideas.tsx`，其邏輯放在 `apps/mobile/src/ideas/`。

2. 通過正在執行的預覽在您的裝置上開啟新介面，確認它能為已登入成員正常渲染。

3. 檢查未登入賬戶和第二個工作區賬戶——必須保密的內容應返回拒絕或為空，因為邊界由伺服器強制。

對自定義程式碼，寫明介面名稱、它顯示的資料、誰可以看以及要處理的錯誤。把任務交給您的編碼代理，並要求它先讀 `AGENTS.md`、`.ai/PROJECT_CONTEXT.md` 以及將觸碰檔案的 `.ai/` 映象檔案；在編輯前列出檔案和檢查項；並向您展示 diff。使用示例值；切勿貼上真實金鑰。

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

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

[手機本地設定](https://supastack.dev/zh-tw/docs/mobile/ship-in-5-minutes.md)

[座席提示和專案記憶體](https://supastack.dev/zh-tw/docs/mobile/agents.md)


## 建立介面

在 `apps/mobile/app/(app)/` 下新增一個路由檔案——Expo Router 會把該檔案變成已登入介面棧中的一個介面。用 `apps/mobile/src/ui` 的原語（Screen、Card、Title、Detail、AppButton）來組合它，使其繼承應用的間距、字型和顏色。

```
apps/mobile/app/(app)/ideas.tsx
apps/mobile/src/ideas/index.ts
apps/mobile/src/ideas/index.test.ts
```


## 通過型別化客戶端讀寫

通過 `apps/mobile/src/api/client.ts` 獲取資料，它會為每個針對 `EXPO_PUBLIC_API_URL` 的請求附帶已儲存的會話，並返回型別化錯誤。保持與 Web 契約一致的載荷——同一組端點同時服務兩個客戶端。

如果介面要讀取工作區資料，請用 `apps/mobile/src/offline/` 中的輔助函式包裝該呼叫，使網路故障能回退到快取副本——僅限網路錯誤，絕不在認證或許可權錯誤後回退。


## 讓伺服器決定所有權

伺服器解析已登入成員和當前工作區，並按 `workspaceId` 限定每條記錄。應用顯示伺服器返回的內容；它絕不傳送需要伺服器信任的工作區 id。

如果您需要的資料沒有端點，請先在後端新增——業務規則在伺服器上。應用裡隱藏一個按鈕並不能強制訪問控制。


## 驗證訪問和恢復

檢查已登入成員、另一工作區的成員、未登入會話和飛航模式：成員資料正常顯示，外部資料被拒絕，未登入裝置回到登入頁，離線副本只在網路錯誤時提供。

[離線讀取快取](https://supastack.dev/zh-tw/docs/mobile/offline.md)

[Mobile 安全檢查清單](https://supastack.dev/zh-tw/docs/mobile/security.md)


## 完善各種狀態

通過共享原語為介面補上載入、空態和錯誤狀態，把每個新字串加入全部四個 i18n 目錄，並把路由接入首頁或設定導航，讓成員真正能找到它。


## 下一篇

[用編碼代理構建](https://supastack.dev/zh-tw/docs/mobile/agents.md)