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

# 项目结构

找到应用、共享包以及它们之间的边界。

## 安装与配置

在执行任何步骤之前，请阅读[开始之前](https://supastack.dev/zh/docs/web/before-you-start.md) 和[终端基础知识](https://supastack.dev/zh/docs/web/terminal-basics.md)。这些说明假设您在 VS Code 中打开了完整的 supastack monorepo；它的根 package.json 标记存储库根。在 pnpm 命令中，工作区包是应用程序或共享代码文件夹；在产品中，工作空间是团队的数据容器和安全边界。 corepack pnpm --filter ... 从 monorepo 选择一个包，同时从其根运行命令。如果您仅打开同步的移动或桌面文件夹，则它不包含 Web 后端、Docker 设置或根脚本：从此 monorepo 或可访问的托管服务器运行后端，并使用平台文件夹自己的脚本。环境变量是存储在本地 .env 文件或托管仪表板中的命名设置；更改后重新启动相关应用程序，并将服务器机密保留在 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值之外。

1. 在 VS Code 中打开根 package.json，然后浏览 apps/web 网站、apps/mobile 浏览 Expo、apps/desktop 桌面 shell，以及共享片段的包。

2. 从存储库根目录运行 corepack pnpm --filter @supastack/web dev。

3. 打开 http://localhost:3000. 预期：Web 应用程序从 apps/web 启动，而共享包保留在同一存储库中；桌面窗口包含此 Web 应用程序而不是包含第二个产品。

pnpm workspace 包含 apps/web 里的 Next.js、apps/mobile 里的 Expo，以及 packages 下的共享包。从仓库根目录运行 workspace 命令。应用路由组合共享模块；产品专属行为属于使用方产品。

改动行为之前先读 AGENTS.md 与 .ai/PROJECT_CONTEXT.md。.ai/ 中的文件镜像解释了仅从组件可能看不出的决策与约束。

```
apps/web/app/       Routes and layouts
apps/web/src/       Web components and server composition
apps/mobile/        Expo application
packages/           Shared contracts and adapters
tests/              Cross-module and browser checks
docs/               Operational guides
```


## 要复制的命令

按照注释查看命令在哪个文件夹中运行。如果标记了两个终端，请打开两个终端窗口，并在使用第二个命令时保持第一个命令运行。

```
corepack pnpm --filter @supastack/web dev
```


## 改动应该放在哪

动手改之前，先决定这个改动归哪个应用或包管。经验法则：只有一个产品界面需要它，就放进那个应用；每个界面都需要，就放进 `packages/` 下的共享包。

Web 存储库和 All Platforms monorepo 包含下面所有文件夹。独立的 Mobile 或 Desktop 检出只包含它自己的应用——服务器代码仍在 Web 存储库中。

[构建你的第一个功能](https://supastack.dev/zh/docs/web/first-feature.md)

- 新的营销或落地页 → `apps/web/app/`——公开网站。
- 登录后产品内的新界面 → `apps/web/app/` 放路由、`apps/web/src/` 放逻辑——页面组合共享包。
- 新的 API 路由 → `apps/web/app/api/`——Web 应用的服务器半区。
- 所有应用共享的改动——数据表、契约、提供商适配器 → `packages/` 中对应的文件夹。
- 仅手机的界面 → `apps/mobile/`——它与 Web 应用的 API 通信，而不是自带后端。
- 仅桌面的行为 → `apps/desktop/`——Tauri 外壳包裹 Web 应用，几乎从不另起产品 UI。


## 实现流程

从拥有用户动作的路由开始，跟随它的服务端 handler，再看它调用的共享包。UI 组件不应重新实现工作区解析、计费授权或供应商选择。

新增路由时先决定它是公开还是需认证。访问用户记录之前在服务端解析已认证的归属，并把服务端凭证留在客户端 import 之外。


## 验证与排障

如果该命令报告没有项目与过滤器匹配，请检查终端是否位于包含根 package.json 的文件夹中。如果端口 3000 已被使用，请先停止其他本地 Web 服务器。不要寻找单独的桌面聊天或登录实现；桌面 shell 加载 Web 后端。

改动包契约后运行相关测试与类型检查。修改共享类型时同时检查 Web 与移动端调用方。Web 构建成功本身并不能证明与原生应用兼容。


## 下一篇

[配置](https://supastack.dev/zh/docs/web/configuration.md)