For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh/docs/web/project-structure.md (or send Accept: text/markdown).

项目结构

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

询问本指南

安装与配置

在执行任何步骤之前，请阅读开始之前和终端基础知识。这些说明假设您在 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 存储库中。

构建你的第一个功能

新的营销或落地页 → 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 构建成功本身并不能证明与原生应用兼容。