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

[终端基础知识](https://supastack.dev/zh/docs/web/terminal-basics.md)

[手机本地设置](https://supastack.dev/zh/docs/mobile/ship-in-5-minutes.md)

[座席提示和项目内存](https://supastack.dev/zh/docs/web/agents.md)


## 了解本机范围

Expo 包括本机身份验证/会话和深度链接以及工作区、设置、聊天和 RevenueCat 购买界面。共享业务行为和授权保留在 Web 后端/包中； `apps/mobile/src` 下的本机客户端调用这些 API 时无需嵌入提供者凭据。


## 使用会话认证的BFF

`/api/mobile` 路由涵盖权利、RevenueCat 购买可用性和服务器同步、组织、成员、邀请、审核、API 密钥、webhooks、域、时间表和功能请求。他们保留工作区所有权和角色检查。它们与 `sk_` 不记名密钥 `/api/v1` 公共合约不同。

使用您的设备可访问的 `EXPO_PUBLIC_API_URL` 和配置的源/方案；公共 Expo 变量从不包含提供者凭据。


## 在本机目标上进行验证

检查您打算支持的设备/版本上的加载/错误/空状态、重新连接、过期会话、禁止的管理操作和深层链接返回。 Expo 导出证明捆绑，而不是本地交付或购买接受。

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

[原生会话流程](https://supastack.dev/zh/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/v1/ai-tasks            # authorized work, same as web

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/docs/mobile/ui.md)