项目结构

安装与配置

开始任何步骤前，请阅读开始之前和终端基础。在根目录打开 supastack 文件夹——即包含 package.json 的文件夹。Mobile checkout 包含 apps/mobile 和下述共享包；All Platforms monorepo 还附带 Web 后端和 Desktop 外壳。环境变量是存储在本地 .env 文件或托管平台控制台中的命名设置；修改后要重启应用，且服务器密钥绝不能出现在 EXPO_PUBLIC_ 值中。

1. 在编辑器中打开 apps/mobile/app/_layout.tsx——每个界面共享的根布局。

2. 浏览 apps/mobile/src/——每个功能领域一个文件夹，各自存放其逻辑与测试。

3. 在存储库根目录运行 corepack pnpm --filter @supastack/mobile start，然后在您的设备上打开预览。

Expo 应用按“路由调用功能模块”的方式组织。路由保持精简——它们只渲染界面；它们调用的逻辑连同测试一起放在 src/ 下。修改行为前先阅读 AGENTS.md 和 .ai/PROJECT_CONTEXT.md；.ai/ 镜像文档记录了单从文件看不出的决策。

apps/mobile/app/          Expo Router routes — sign-in, onboarding, invite, paywall
apps/mobile/app/(app)/    Signed-in screens — home, chat, notifications, settings, content, commerce, assistant
apps/mobile/src/          Feature modules — auth, api, purchases, offline, push, ui, theme, i18n
packages/ui-native/       Shared native view-models
packages/design-tokens/   Shared theme tokens
apps/mobile/app.config.ts Scheme and allowed-origin derivation
apps/mobile/eas.json      EAS build and submit profiles
docs/                     Runbooks incl. store submission
.agents/skills/           Task guides for coding agents

改动应该放在哪

编辑前先确定改动属于哪个文件夹。经验法则：路由文件只负责渲染；可复用逻辑放在 src/ 模块中；任何必须由服务器决定的事情绝不进入应用。

• 构建您的第一个移动端功能

• 新的已登录界面 → apps/mobile/app/(app)/ 放路由，apps/mobile/src/<feature>/ 放其逻辑。
• 新的未登录或独立界面 → apps/mobile/app/ 中 (app) 组之外的位置。
• 调用后端 → apps/mobile/src/api/client.ts——扩展类型化客户端，而不是临时发起 fetch。
• 多个界面共用的视觉元素 → apps/mobile/src/ui/ 原语；跨平台视图模型 → packages/ui-native/。
• 颜色、间距和深色/浅色值 → apps/mobile/src/theme/，由 packages/design-tokens/ 提供支持。
• 新的翻译键 → apps/mobile/src/i18n/ 下全部四个目录。
• 任何服务器端的内容——数据、权限、提供商调用 → Web 后端存储库；对仅购买 Mobile 的用户来说它是单独的 checkout。

实现流程

从路由文件开始，跟随它渲染的功能模块，再到 API 客户端调用——服务器决定所有权；应用绝不自行推导。.agents/skills/ 中的 add-a-mobile-screen 技能按同样的顺序走一遍。

编辑共享包或 API 客户端后运行包测试与类型检查；客户端必须保持与后端一致的契约。

验证与排障

如果 expo start 报告缺少模块，请在存储库根目录运行安装命令——仅靠应用文件夹无法解析 workspace 包。如果某个界面看起来没有样式，请检查它是否组合了 src/ui 原语，而不是使用硬编码颜色的原始元素。

corepack pnpm --filter @supastack/mobile test
corepack pnpm --filter @supastack/mobile typecheck