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

# 移動端 API

應用如何與伺服器通訊 —— 會話、可達性與負載。

## 初學者演練

先決條件：閱讀下面的兩個初學者指南並完成移動本地設定。將Expo值放入`apps/mobile/.env.local`中；將 `EXPO_PUBLIC_API_URL` 設定為您的裝置可以訪問的後端主機。僅限移動裝置的結帳沒有網路後端，因此請單獨啟動或連線一個。成功的 Expo 匯出證明 JavaScript 捆綁包，而不是裝置或購買接受。

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

1、在`apps/mobile/.env.local`中，將`EXPO_PUBLIC_API_URL`設定為手機可訪問的執行後端地址；請勿從物理裝置使用 `localhost`。

2. 按照移動本地設定啟動 Expo、登入並開啟工作區、設定和聊天螢幕。

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/mobile/ship-in-5-minutes.md)

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


## 瞭解本機範圍

Expo 包括本機身份驗證/會話和深度連結以及工作區、設定、聊天和 RevenueCat 購買介面。共享業務行為和授權保留在 Web 後端/包中； `apps/mobile/src` 下的本機客戶端呼叫這些 API 時無需嵌入提供者憑據。


## 使用會話認證的BFF

`/api/mobile` 路由涵蓋權益、RevenueCat 購買可用性與伺服器同步、組織、成員、邀請、審計、API 金鑰、webhook、域名、計劃任務、功能請求、推送 token、外觀、電商、內容、額度與用量。它們保留工作區歸屬和角色檢查，與 `sk_` bearer 金鑰的 `/api/v1` 公共契約不同。

使用裝置可訪問的 `EXPO_PUBLIC_API_URL` 和已配置的 origin/scheme；公開的 Expo 變數絕不包含供應商憑據。


## 在本機目標上進行驗證

檢查您打算支援的裝置/版本上的載入/錯誤/空狀態、重新連線、過期會話、禁止的管理操作和深層連結返回。 Expo 匯出證明捆綁，而不是本地交付或購買接受。

[所有API航線](https://supastack.dev/zh-tw/docs/web/project-structure.md)

[原生會話流程](https://supastack.dev/zh-tw/docs/mobile/authentication.md)


## 安裝與配置

應用呼叫 /api/mobile 和版本化的 /api/v1 端面下的 API,使用成員會話而非 Web 應用的 Cookie 假設。EXPO_PUBLIC_API_URL 是客戶端唯一知道的源;它在設計上是公開的,不攜帶金鑰。

會話令牌來自 Better Auth Expo 流程,儲存在原生安全儲存中 —— 絕不在明文 AsyncStorage 或打包配置中。

```
GET  /api/mobile/entitlement    # access state for the member
GET  /api/mobile/organization   # active workspace context
GET  /api/mobile/usage          # current-month AI spend, meter caps, and credit balance
GET  /api/mobile/appearance     # synced appearance bundle (GET/PUT)
POST /api/mobile/push-tokens    # register this device for push
/api/chat/threads*, /api/chat/stream   # chat, same contract as web
POST /api/v1/agent-runs         # budgeted assistant runs

Session: /api/auth/* (Better Auth Expo flow)
# Optional server-only token for authenticated Expo push sends:
# EXPO_ACCESS_TOKEN=
```


## 實現流程

在第一個認證請求之前解析儲存的會話,當伺服器報告過期時重新整理,被吊銷時乾淨地登出。將 API 不可達和無效會話視為不同狀態 —— 一個重試,另一個返回登入。

保持負載與 Web 契約相同:無論哪個客戶端呼叫,伺服器都應用相同的工作區、entitlement 和驗證規則。


## 驗證與排障

測試飛航模式失敗、會話中途令牌過期、已吊銷會話,以及帶著已儲存有效令牌的冷啟動。以失敗關閉(拒絕)結束的請求是正確的;以失敗開放結束的是釋出前要修復的 bug。


## 下一篇

[原生 UI 與主題](https://supastack.dev/zh-tw/docs/mobile/ui.md)